add_library

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

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

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

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

Добавляет целевой объект библиотеки, называемый <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 или STATIC библиотеки могут быть помечены свойством целевого объекта FRAMEWORK для создания фреймворка OS X.

Если библиотека не экспортирует какие-либо символы, она не должна объявляться как 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 установлено в True. Имя целевого объекта имеет область видимости в каталоге, в котором он создан, и ниже, но опция GLOBAL расширяет область видимости. На него можно ссылаться так же, как и на любой целевой объект, созданный в рамках проекта. IMPORTED библиотеки полезны для удобной ссылки из команд, таких как target_link_libraries(). Подробности об импортированной библиотеке задаются с помощью свойств, имена которых начинаются с IMPORTED_ и INTERFACE_. Наиболее важное из таких свойств — IMPORTED_LOCATION (и его вариант для каждой конфигурации IMPORTED_LOCATION_<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. Библиотеки объектов не могут быть линкованы. Некоторые системы сборки могут не поддерживать целевые объекты, состоящие только из объектных файлов, поэтому рекомендуется добавить хотя бы один реальный исходный файл в любой целевой объект, который ссылается на $<TARGET_OBJECTS:objlib>.

Библиотеки псевдонимов

add_library(<name> ALIAS <target>)

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

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

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

Создаёт библиотеку интерфейса. Библиотечный целевой объект INTERFACE не создаёт напрямую выходных данных сборки, хотя на него могут быть установлены свойства, и он может быть установлен, экспортирован и импортирован. Обычно свойства INTERFACE_* заполняются для целевого объекта интерфейса с помощью команд:

• set_property(),
• target_link_libraries(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().