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 или управляемая 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 устанавливается в значение 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().