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. Например, Windows ресурсная DLL или управляемая C++/CLI DLL, не экспортирующая неуправляемые символы, должна быть библиотекой типа 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>) для библиотек объектов, указывающие расположения объектных файлов на диске.
• PUBLIC_HEADER файлы, которые будут установлены во время вызова install()

См. документацию свойств IMPORTED_* и INTERFACE_* для получения дополнительной информации.

Тип библиотеки UNKNOWN обычно используется только при реализации модулей поиска. Это позволяет использовать путь к импортированной библиотеке (часто найденной с помощью команды find_library()), не зная её тип. Это особенно полезно в Windows, где у статической библиотеки и импортной библиотеки DLL одно и то же расширение файла.

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

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().