add_library

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

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

Обычные библиотеки

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

Добавляет целевую библиотеку, называемую <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 Framework.

Если библиотека не экспортирует какие-либо символы, она не должна объявляться как библиотека типа 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.

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

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

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

add_library(<name> <SHARED|STATIC|MODULE|OBJECT|UNKNOWN> IMPORTED
            [GLOBAL])

Целевая библиотека IMPORTED ссылается на файл библиотеки, расположенный вне проекта. Для неё не генерируются правила построения, и свойство цели IMPORTED имеет значение True. Имя цели имеет область действия в каталоге, где оно создано, и ниже, но опция GLOBAL расширяет видимость. К ней можно обратиться, как к любой цели, созданной в рамках проекта. Библиотеки IMPORTED полезны для удобной ссылки из команд, таких как target_link_libraries(). Детали импортированной библиотеки задаются путём установки свойств, имена которых начинаются с IMPORTED_ и INTERFACE_. Наиболее важным таким свойством является IMPORTED_LOCATION (и его вариант для конфигураций IMPORTED_LOCATION_<CONFIG>), которое указывает расположение основного файла библиотеки на диске. Или, для библиотек объектов, IMPORTED_OBJECTS (и IMPORTED_OBJECTS_<CONFIG>) указывает расположения объектных файлов на диске. Более подробная информация приведена в документации свойств IMPORTED_* и INTERFACE_*.

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

add_library(<name> OBJECT <src>...)

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

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

Библиотеки интерфейсов

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

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

Также может быть создан INTERFACE Импортированный целевой объект с этой подписью. IMPORTED Целевой объект библиотеки ссылается на библиотеку, определённую вне проекта. Имя целевого объекта имеет область действия в каталоге, в котором он создан, и ниже, но GLOBAL опция расширяет видимость. К нему можно обратиться, как к любому целевому объекту, построенному внутри проекта. IMPORTED Библиотеки полезны для удобной ссылки из команд, таких как target_link_libraries().