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()