add_library

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

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

Библиотеки по умолчанию

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

Добавляет целевую библиотеку, названную <name>, для компиляции из исходных файлов, перечисленных в вызове команды. (Исходные файлы можно опустить, если они будут добавлены позже с помощью target_sources().) Название <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 или STATIC могут быть помечены свойством FRAMEWORK для создания фреймворка macOS.

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

По умолчанию, файл библиотеки будет создан в каталоге сборки, соответствующем каталогу исходного дерева, в котором была вызвана команда. Для изменения этого расположения см. документацию по свойствам целевых объектов ARCHIVE_OUTPUT_DIRECTORY, LIBRARY_OUTPUT_DIRECTORY и RUNTIME_OUTPUT_DIRECTORY. Для изменения части имени выходного файла, см. документацию по свойству целевого объекта OUTPUT_NAME.

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

Аргументы исходных файлов для add_library могут использовать «генераторные выражения» с синтаксисом $<...>. См. руководство cmake-generator-expressions(7) для доступных выражений. Дополнительные сведения о определении свойств системы сборки см. в руководстве 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(), как и любой другой целевой объект.

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

Начиная с CMake 3.19, целевой объект библиотеки интерфейса может быть создан с исходными файлами:

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

Исходные файлы могут быть перечислены непосредственно в вызове add_library или добавлены позже вызовами target_sources() с ключевыми словами PRIVATE или PUBLIC.

Если библиотека интерфейса содержит исходные файлы (то есть, свойство целевого объекта SOURCES задано), она будет отображаться в генерируемой системе сборки как целевой объект, аналогично целевому объекту, определенному командой add_custom_target(). Она не компилирует исходные файлы, но содержит правила сборки для пользовательских команд, созданных командой add_custom_command().

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

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

Создает IMPORTED библиотечный целевой объект, называемый <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.

Псевдоним на не-GLOBAL Импортированный целевой объект имеет область действия в каталоге, в котором создан псевдоним, и ниже. Свойство целевого объекта ALIAS_GLOBAL может использоваться для проверки, является ли псевдоним глобальным.

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