add_library

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

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

Библиотеки обычного типа

add_library(<name> [<type>] [EXCLUDE_FROM_ALL] <sources>...)

Добавляет целевой объект библиотеки, называемый <name>, который будет построен из исходных файлов, перечисленных в вызове команды.

Необязательный параметр <type> указывает тип создаваемой библиотеки:

STATIC

Архив файлов объектов для использования при линковке других целевых объектов.

SHARED

Динамическая библиотека, которая может быть связана с другими целевыми объектами и загружена во время выполнения.

MODULE

Плагин, который не может быть связан с другими целевыми объектами, но может быть динамически загружен во время выполнения с помощью функций типа dlopen.

Если параметр <type> не указан, по умолчанию используется STATIC или SHARED, в зависимости от значения переменной BUILD_SHARED_LIBS.

Доступные параметры:

EXCLUDE_FROM_ALL

Автоматически устанавливает свойство целевого объекта EXCLUDE_FROM_ALL. Для получения подробностей см. документацию по этому свойству целевого объекта.

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

Для библиотек SHARED и MODULE свойство целевого объекта POSITION_INDEPENDENT_CODE устанавливается в ON автоматически. Библиотека SHARED может быть помечена свойством целевого объекта FRAMEWORK для создания macOS Framework.

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

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

См. руководство cmake-buildsystem(7) для получения дополнительной информации об определении свойств системы сборки.

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

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

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

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

Другие целевые объекты, созданные с помощью 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> 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(), как и любой другой целевой объект.

Добавлен в версии 3.15: Библиотека интерфейса может иметь свойства PUBLIC_HEADER и PRIVATE_HEADER. Заголовки, указанные этими свойствами, могут быть установлены с помощью команды install(TARGETS).

add_library(<name> INTERFACE [EXCLUDE_FROM_ALL] <sources>...)

Добавлен в версии 3.19.

Добавить целевой объект Библиотеки интерфейса с исходными файлами (в дополнение к требованиям использования и свойствам, как описано в above signature). Исходные файлы могут быть перечислены непосредственно в вызове add_library или добавлены позже вызовами target_sources() с ключевыми словами PRIVATE или PUBLIC.

Если у библиотеки интерфейса есть исходные файлы (т.е. установлено свойство целевого объекта SOURCES) или наборы заголовков (т.е. установлено свойство целевого объекта HEADER_SETS), она будет отображаться в сгенерированной системе сборки как целевой объект, подобно объекту, определённому командой add_custom_target(). Она не компилирует исходники, но содержит правила сборки для пользовательских команд, созданных командой add_custom_command().

Варианты:

EXCLUDE_FROM_ALL

Автоматически устанавливает свойство целевого объекта EXCLUDE_FROM_ALL. Подробнее см. документацию по этому свойству целевого объекта.

Примечание

В большинстве подписей команд, где появляется ключевое слово INTERFACE, элементы, указанные после него, становятся только частью требований использования этого целевого объекта, но не частью его собственных настроек. Однако в этой подписи add_library, ключевое слово INTERFACE относится только к типу библиотеки. Исходники, указанные после него в вызове add_library, PRIVATE библиотеке интерфейса и не отображаются в свойстве целевого объекта INTERFACE_SOURCES.

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

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

Добавить Целевой объект импортированной библиотеки под названием <name>. Название целевого объекта может быть использовано как любое другое целевой объект, созданный в проекте, за исключением того, что по умолчанию он виден только в каталоге, в котором он создан, и ниже.

<type> должно быть одним из:

STATIC, SHARED, MODULE, UNKNOWN

Ссылка на файл библиотеки, расположенный вне проекта. Свойство целевого объекта IMPORTED_LOCATION (или его вариант для каждой конфигурации IMPORTED_LOCATION_<CONFIG>) определяет расположение главного файла библиотеки на диске:

• Для SHARED библиотеки на большинстве платформ, отличных от Windows, главный файл библиотеки — это .so или .dylib файл, используемый как линковщиками, так и динамическими загрузчиками. Если у файла библиотеки есть SONAME (или на macOS, имеет LC_ID_DYLIB начиная с @rpath/), значение этого поля следует установить в свойстве целевого объекта IMPORTED_SONAME. Если у файла библиотеки нет SONAME, но платформа его поддерживает, то следует установить свойство целевого объекта IMPORTED_NO_SONAME.
• Для SHARED библиотеки на Windows, свойство целевого объекта IMPORTED_IMPLIB (или его вариант для каждой конфигурации IMPORTED_IMPLIB_<CONFIG>) указывает расположение файла DLL-библиотеки импорта (.lib или .dll.a) на диске, а IMPORTED_LOCATION — расположение .dll библиотеки времени выполнения (и является необязательным, но необходимым для генераторского выражения TARGET_RUNTIME_DLLS).

Дополнительные требования к использованию могут быть указаны в свойствах INTERFACE_*.

Тип библиотеки UNKNOWN обычно используется только при реализации Модулей поиска. Он позволяет использовать путь к импортированной библиотеке (часто найденной с помощью команды find_library()) без необходимости знать, какой тип библиотеки это.

OBJECT

Ссылка на набор файлов объектов, расположенных вне проекта. Свойство целевого объекта IMPORTED_OBJECTS (или его вариант для каждой конфигурации IMPORTED_OBJECTS_<CONFIG>) указывает расположения файлов объектов на диске. Дополнительные требования к использованию могут быть указаны в свойствах INTERFACE_*.

INTERFACE

Не ссылается на файлы библиотек или объектов на диске, но может указать требования к использованию в свойствах INTERFACE_*.

Варианты:

GLOBAL

Сделать имя целевого объекта глобально видимым.

Правила для сборки импортированных целевых объектов не генерируются, и свойство целевого объекта IMPORTED равно True. Импортированные библиотеки полезны для удобной ссылки из команд, таких как target_link_libraries().

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

Библиотеки псевдонимов

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