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.

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