add_library

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

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

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

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

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

Если EXCLUDE_FROM_ALL задано, соответствующее свойство будет установлено для созданного объекта. Смотрите документацию по свойству целевого объекта EXCLUDE_FROM_ALL для получения подробностей.

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

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

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

add_library(<name> OBJECT [<source>...])

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

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

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

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

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

Создаёт целевой объект импортированной библиотеки под названием <name>. Правила для его сборки не генерируются, и свойство целевого объекта IMPORTED имеет значение True. Название целевого объекта имеет область действия в каталоге, в котором оно создано, и ниже, но опция GLOBAL расширяет видимость. К нему можно обратиться как к любому объекту, собранному в проекте. Импортированные библиотеки IMPORTED удобны для ссылки из команд, таких как target_link_libraries(). Подробности об импортированной библиотеке задаются с помощью свойств, имена которых начинаются с IMPORTED_ и INTERFACE_.

Значение <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_*.

См. документацию свойств 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() и т.д. Целевой объект-псевдоним нельзя устанавливать или экспортировать.