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 ресурсная DLL или управляемая C++/CLI DLL, не экспортирующая неуправляемые символы, должна быть MODULE библиотекой. Это связано с тем, что CMake ожидает SHARED библиотеку с соответствующей импортной библиотекой в Windows.

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

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

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

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

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 import library (.lib или .dll.a) на диске, а IMPORTED_LOCATION — расположение файла .dll runtime library (необязательно, но необходимо для генератора выражений TARGET_RUNTIME_DLLS).

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

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

OBJECT

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

INTERFACE

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

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

GLOBAL

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

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

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

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

add_library(<name> ALIAS <target>)

Создаёт Целевой объект-псевдоним, такой что <name> может быть использован для ссылки на <target> в последующих командах. Целевой объект-псевдоним не появляется в сгенерированной системе сборки как целевой объект make. Целевой объект <name> не может быть ALIAS.

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

См. также

• add_executable()