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 фреймворка.

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

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

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

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

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

См. также

• add_executable()