define_property

Определяет и документирует пользовательские свойства.

define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
                 TEST | VARIABLE | CACHED_VARIABLE>
                 PROPERTY <name> [INHERITED]
                 [BRIEF_DOCS <brief-doc> [docs...]]
                 [FULL_DOCS <full-doc> [docs...]]
                 [INITIALIZE_FROM_VARIABLE <variable>])

Определяет одно свойство в области для использования с командами set_property() и get_property(). Она в основном полезна для определения способа инициализации или наследования свойства. Исторически эта команда также связывала документацию со свойством, но это больше не является основным вариантом использования.

Первый аргумент определяет тип области, в которой должно использоваться свойство. Он должен быть одним из следующих:

GLOBAL    = associated with the global namespace
DIRECTORY = associated with one directory
TARGET    = associated with one target
SOURCE    = associated with one source file
TEST      = associated with a test named with add_test
VARIABLE  = documents a CMake language variable
CACHED_VARIABLE = documents a CMake cache variable

Обратите внимание, что в отличие от set_property() и get_property(), нет необходимости указывать фактическую область; важен только тип области.

Требуемый PROPERTY параметр сразу за ним следует имя определяемого свойства.

Если указан параметр INHERITED, то команда get_property() будет обращаться к следующей более высокой области, когда запрошенное свойство не задано в указанной области команды.

• DIRECTORY область обращается к области родительского каталога, продолжая переход по родительским каталогам до тех пор, пока свойство не будет найдено в каком-либо из каталогов или пока не останется более родительских каталогов. Если свойство не найдено на верхнем уровне каталога, оно обращается к GLOBAL области.
• TARGET, SOURCE и TEST свойства обращаются к DIRECTORY области, включая дальнейшее обращение к родительским каталогам и т. д. по мере необходимости.

Обратите внимание, что это поведение цепочки областей применяется только к вызовам get_property(), get_directory_property(), get_target_property(), get_source_file_property() и get_test_property(). При установке свойств нет поведения наследования, поэтому использование APPEND или APPEND_STRING с командой set_property() не будет учитывать унаследованные значения при определении содержимого для добавления.

Параметры BRIEF_DOCS и FULL_DOCS следуют за строками, которые должны быть связаны со свойством в качестве краткого и полного описания. CMake не использует эту документацию, кроме предоставления её проекту через соответствующие параметры команды get_property().

Переопределение свойств

После определения свойства для определённого типа области его нельзя переопределить. Попытки переопределения существующего свойства вызовом define_property() с тем же типом области и именем свойства будут молча игнорироваться. Определение одного и того же имени свойства для двух разных типов областей допустимо.

get_property() можно использовать для определения того, уже определено ли свойство для определённого типа области, и, если да, для проверки его определения. Например:

# Initial definition
define_property(TARGET PROPERTY MY_NEW_PROP
  BRIEF_DOCS "My new custom property"
)

# Later examination
get_property(my_new_prop_exists
  TARGET NONE
  PROPERTY MY_NEW_PROP
  DEFINED
)

if(my_new_prop_exists)
  get_property(my_new_prop_docs
    TARGET NONE
    PROPERTY MY_NEW_PROP
    BRIEF_DOCS
  )
  # ${my_new_prop_docs} is now set to "My new custom property"
endif()

См. также

• get_property()
• set_property()