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 — связано с глобальным пространством имен.
• DIRECTORY — связано с одним каталогом.
• TARGET — связано с одной целью.
• SOURCE — связано с одним исходным файлом.
• TEST — описывает тест с именем, заданным командой add_test().
• VARIABLE — описывает переменную языка CMake.
• CACHED_VARIABLE — описывает переменную кэша CMake.

Обратите внимание: в отличие от команд 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()