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

По умолчанию файл библиотеки будет создан в каталоге дерева сборки, соответствующем каталогу дерева исходного кода, в котором была выполнена команда. См. документацию свойств целевого объекта ARCHIVE_OUTPUT_DIRECTORY, LIBRARY_OUTPUT_DIRECTORY и RUNTIME_OUTPUT_DIRECTORY для изменения этого расположения. См. документацию свойства целевого объекта OUTPUT_NAME для изменения части <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 import library (.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> в последующих командах. Объект-псевдоним не отображается в сгенерированной системе сборки как целевой объект make. Объект-псевдоним <target> не может быть ALIAS.

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

См. также

• add_executable()