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, свойство целевого объекта IMPORTED_IMPLIB (или его вариант для конфигурации IMPORTED_IMPLIB_<CONFIG>) указывает расположение файла импорта DLL-библиотеки (.lib или .dll.a) на диске, а свойство IMPORTED_LOCATION — расположение .dll библиотеки времени выполнения (и является необязательным). Дополнительные требования к использованию могут быть указаны в свойствах 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() и т.д. Целевой объект ALIAS не может быть установлен или экспортирован.