add_library

• Библиотеки по умолчанию
• Импортированные библиотеки
• Библиотеки объектов
• Псевдонимы библиотек
• Библиотеки интерфейса

Добавляет библиотеку в проект, используя указанные исходные файлы.

Библиотеки по умолчанию

add_library(<name> [STATIC | SHARED | MODULE]
            [EXCLUDE_FROM_ALL]
            source1 [source2 ...])

Добавляет целевой объект библиотеки, называемый <name>, который должен быть построен из исходных файлов, перечисленных в вызове команды. <name> соответствует логическому имени целевого объекта и должно быть уникальным в рамках проекта. Фактическое имя файла создаваемой библиотеки формируется на основе конвенций для целевой платформы (таких как lib<name>.a или <name>.lib).

STATIC, SHARED, или MODULE могут быть заданы для указания типа создаваемой библиотеки. Библиотеки STATIC представляют собой архивы файлов объектов, используемые при компоновке других целевых объектов. Библиотеки SHARED компонуются динамически и загружаются во время выполнения. Библиотеки MODULE являются плагинами, которые не компонуются в другие целевые объекты, но могут быть загружены динамически во время выполнения с использованием функциональности типа dlopen. Если тип не указан явно, тип выбирается как STATIC или SHARED, в зависимости от того, равно ли текущее значение переменной BUILD_SHARED_LIBS значению ON. Для библиотек SHARED и MODULE свойство целевого объекта POSITION_INDEPENDENT_CODE устанавливается в ON автоматически. Библиотеку SHARED можно пометить свойством целевого объекта FRAMEWORK для создания фреймворка в OS X.

Если библиотека не экспортирует какие-либо символы, её нельзя объявлять как библиотеку SHARED. Например, DLL ресурсов Windows или управляемая C++/CLI DLL, которая не экспортирует неуправляемые символы, должна быть библиотекой MODULE. Это связано с тем, что CMake ожидает, что библиотека SHARED всегда будет иметь связанную библиотеку импорта в Windows.

По умолчанию файл библиотеки будет создан в каталоге дерева сборки, соответствующем каталогу дерева исходников, в котором была выполнена команда. Смотрите документацию свойств целевого объекта ARCHIVE_OUTPUT_DIRECTORY, LIBRARY_OUTPUT_DIRECTORY и RUNTIME_OUTPUT_DIRECTORY для изменения этого расположения. Смотрите документацию свойства целевого объекта OUTPUT_NAME для изменения части <name> конечного имени файла.

Если указано EXCLUDE_FROM_ALL, соответствующее свойство будет установлено для созданного целевого объекта. См. документацию свойства целевого объекта EXCLUDE_FROM_ALL для получения подробной информации.

Аргументы исходных файлов для команды add_library могут использовать «генераторские выражения» со синтаксисом $<...>. Обратитесь к руководству cmake-generator-expressions(7) для получения списка доступных выражений. Обратитесь к руководству cmake-buildsystem(7) для получения дополнительных сведений об определении свойств системы сборки.

Импортированные библиотеки

add_library(<name> <SHARED|STATIC|MODULE|UNKNOWN> IMPORTED
            [GLOBAL])

Целевой объект импортированной библиотеки ссылается на файл библиотеки, расположенный вне проекта. Не генерируются правила для его построения, и свойство целевого объекта IMPORTED установлено в значение True. Имя целевого объекта имеет область действия в каталоге, где оно создано, и ниже, но опция GLOBAL расширяет видимость. К нему можно обратиться как к любому целевому объекту, созданному в рамках проекта. Импортированные библиотеки IMPORTED удобны для удобной ссылки из команд, таких как target_link_libraries(). Сведения об импортированной библиотеке задаются путем установки свойств, имена которых начинаются с IMPORTED_ и INTERFACE_. Наиболее важным таким свойством является IMPORTED_LOCATION (и его вариант для конфигурации IMPORTED_LOCATION_<CONFIG>), которое указывает расположение основного файла библиотеки на диске. Смотрите документацию свойств IMPORTED_* и INTERFACE_* для получения дополнительной информации.

Библиотеки объектов

add_library(<name> OBJECT <src>...)

Создаёт библиотеку объектов. Библиотека объектов компилирует исходные файлы, но не архивирует и не компонует их файлы объектов в библиотеку. Вместо этого другие целевые объекты, созданные с помощью команды add_library() или add_executable(), могут ссылаться на объекты, используя выражение вида $<TARGET_OBJECTS:objlib>, где objlib — имя библиотеки объектов. Например:

add_library(... $<TARGET_OBJECTS:objlib> ...)
add_executable(... $<TARGET_OBJECTS:objlib> ...)

будет включать файлы объектов objlib в библиотеку и исполняемый файл вместе с файлами, скомпилированными из собственных исходников. Библиотеки объектов могут содержать только файлы, которые подлежат компиляции, заголовочные файлы и другие файлы, которые не повлияют на компоновку обычной библиотеки (например, .txt). Они могут содержать пользовательские команды, генерирующие такие исходники, но не команды PRE_BUILD, PRE_LINK, или POST_BUILD. Библиотеки объектов не могут быть импортированы, экспортированы, установлены или компонованы. Некоторые системы сборки могут не поддерживать целевые объекты, содержащие только файлы объектов, поэтому рекомендуется добавить по крайней мере один реальный исходный файл в любой целевой объект, который ссылается на $<TARGET_OBJECTS:objlib>.

Псевдонимы библиотек

add_library(<name> ALIAS <target>)

Создаёт псевдоним целевого объекта, таким образом, <name> может использоваться для ссылки на <target> в последующих командах. Псевдоним <name> не отображается в генерированной системе сборки как целевой объект make. Псевдоним <target> не может быть импортированным целевым объектом или ALIAS. Псевдонимы ALIAS могут использоваться как компонуемые целевые объекты и как целевые объекты для чтения свойств. Их также можно проверить на существование с помощью обычной команды if(TARGET). Псевдоним <name> нельзя использовать для изменения свойств целевого объекта <target>, то есть его нельзя использовать в качестве операнда команды set_property(), set_target_properties(), target_link_libraries() и т.д. Целевой объект ALIAS не может быть установлен или экспортирован.

Библиотеки интерфейса

add_library(<name> INTERFACE [IMPORTED [GLOBAL]])

Создаёт библиотеку интерфейса. Целевой объект библиотеки интерфейса INTERFACE напрямую не создаёт выходные данные сборки, хотя на него могут быть установлены свойства, он может быть установлен, экспортирован и импортирован. Обычно свойства INTERFACE_* заполняются на целевом объекте интерфейса с помощью команд:

• set_property(),
• target_link_libraries(INTERFACE),
• target_include_directories(INTERFACE),
• target_compile_options(INTERFACE),
• target_compile_definitions(INTERFACE), и
• target_sources(INTERFACE),

а затем используется в качестве аргумента к команде target_link_libraries() как любой другой целевой объект.

Также может быть создан INTERFACE Импортированный целевой объект. IMPORTED библиотечный целевой объект ссылается на библиотеку, определённую за пределами проекта. Имя целевого объекта имеет область действия в каталоге, в котором он создан, и ниже, но GLOBAL параметр расширяет видимость. К нему можно обратиться как к любому целевому объекту, созданному в рамках проекта. IMPORTED библиотеки полезны для удобной ссылки из команд, таких как target_link_libraries().