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.

Если библиотека не экспортирует какие-либо символы, её нельзя объявлять как библиотеку SHARED. Например, библиотека ресурсов 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 о том, что делать, если некоторые исходные файлы предварительно обрабатываются, и вам необходимо сделать исходные файлы доступными в среде разработки.

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

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

Целевой объект импортированной библиотеки ссылается на файл библиотеки, расположенный за пределами проекта. Для него не генерируются правила сборки, и свойство целевого объекта 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. Целевые объекты псевдонимов могут использоваться как компонуемые целевые объекты и как целевые объекты для чтения свойств. Они также могут быть проверены на существование с помощью обычной подкоманды if(TARGET). Псевдоним <name> не может использоваться для изменения свойств <target>, то есть он не может использоваться в качестве операнда set_property(), set_target_properties(), target_link_libraries() и т.д. Целевой объект псевдонима не может быть установлен или экспортирован.

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

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

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