add_library

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

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

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

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

Добавляет целевую библиотеку, названную <name>, для построения из исходных файлов, перечисленных в вызове команды. (Исходные файлы можно опустить, если они будут добавлены позже с помощью target_sources().) <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 или STATIC может быть помечена свойством целевого объекта FRAMEWORK для создания macOS Framework.

Если библиотека не экспортирует какие-либо символы, её нельзя объявлять как библиотеку SHARED. Например, библиотека ресурсов 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) для получения дополнительной информации об определении свойств системы сборки.

Также см. HEADER_FILE_ONLY о том, что делать, если некоторые исходные файлы предварительно обработаны, и вы хотите, чтобы исходные файлы были доступны в IDE.

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

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

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

Подробности об импортированной библиотеке задаются с помощью свойств, имена которых начинаются с IMPORTED_ и INTERFACE_.

Наиболее важные свойства:

• IMPORTED_LOCATION (и его конфигурационная разновидность IMPORTED_LOCATION_<CONFIG>), которые указывают расположение основного файла библиотеки на диске.
• IMPORTED_OBJECTS (и IMPORTED_OBJECTS_<CONFIG>) для библиотек объектов, указывают расположения файлов объектов на диске.
• PUBLIC_HEADER файлы, которые должны быть установлены во время вызова команды install().

Дополнительную информацию см. в документации по свойствам IMPORTED_* и INTERFACE_*.

Тип библиотеки UNKNOWN обычно используется только при реализации Модулей поиска. Он позволяет использовать путь к импортированной библиотеке (часто найденной с помощью команды find_library()), не зная её типа. Это особенно полезно на Windows, где статическая библиотека и библиотека импорта DLL имеют одинаковое расширение файла.

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

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. Некоторые системы нативной сборки (например, Xcode) могут не поддерживать целевые объекты, содержащие только файлы объектов, поэтому рекомендуется добавить по крайней мере один настоящий исходный файл в любой целевой объект, который ссылается на $<TARGET_OBJECTS:objlib>.

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

add_library(<name> ALIAS <target>)

Создаёт целевой псевдоним, таким образом, <name> может быть использовано для ссылки на <target> в последующих командах. Псевдоним <name> не появляется в сгенерированной системе сборки как целевой объект make. Псевдоним <target> не может быть не-GLOBAL импортированным целевым объектом или 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_link_options(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().