add_library

• Библиотеки обычного типа
• Библиотеки объектов
• Библиотеки интерфейсов
• Импортируемые библиотеки
• Библиотеки псевдонимов
• См. также

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

Библиотеки обычного типа

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

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

См. руководство cmake-buildsystem(7) для получения дополнительной информации о определении свойств системы сборки.

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

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

add_library(<name> OBJECT [<source>...])

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

Библиотека интерфейса, созданная с указанной выше подписью, не содержит исходных файлов и не включается как целевой объект в сгенерированной системе сборки.

add_library(<name> INTERFACE [<source>...] [EXCLUDE_FROM_ALL])

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

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

Создаёт целевой объект импортированной библиотеки под названием <name>. Правила для его сборки не генерируются, и свойство целевого объекта IMPORTED равно True. Имя целевого объекта имеет область видимости в каталоге, в котором он создан, и ниже, но опция GLOBAL расширяет область видимости. К нему можно обратиться как к любому целевому объекту, собранному в рамках проекта. IMPORTED библиотеки полезны для удобной ссылки из команд, таких как target_link_libraries(). Сведения об импортированной библиотеке задаются путём установки свойств, имена которых начинаются с IMPORTED_ и INTERFACE_.

<type> должно быть одним из следующих:

STATIC, SHARED, MODULE, UNKNOWN

Ссылается на файл библиотеки, расположенный вне проекта. Свойство целевого объекта IMPORTED_LOCATION (или его конфигурационно-зависимая разновидность IMPORTED_LOCATION_<CONFIG>) определяет местоположение основного файла библиотеки на диске:

• Для SHARED библиотеки на большинстве платформ, отличных от Windows, основной файл библиотеки — это файл .so или .dylib, используемый как компоновщиками, так и динамическими загрузчиками. Если файл ссылаемой библиотеки имеет поле SONAME (или на macOS, имеет поле LC_ID_DYLIB, начиная с @rpath/ ), значение этого поля должно быть установлено в свойстве целевого объекта IMPORTED_SONAME. Если файл ссылаемой библиотеки не имеет поля SONAME, но платформа поддерживает его, то свойство целевого объекта IMPORTED_NO_SONAME должно быть установлено.
• Для SHARED библиотеки на Windows свойство целевого объекта IMPORTED_IMPLIB (или его конфигурационно-зависимая разновидность IMPORTED_IMPLIB_<CONFIG>) определяет местоположение файла DLL import библиотеки (.lib или .dll.a) на диске, и IMPORTED_LOCATION - местоположение .dll библиотеки времени выполнения (и является необязательным, но необходимым для генератора выражений TARGET_RUNTIME_DLLS).

Дополнительные требования к использованию могут быть указаны в свойствах INTERFACE_*.

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

OBJECT

Ссылается на набор файлов объектных файлов, расположенных вне проекта. Свойство целевого объекта IMPORTED_OBJECTS (или его конфигурационно-зависимая разновидность IMPORTED_OBJECTS_<CONFIG>) определяет местоположения файлов объектных файлов на диске. Дополнительные требования к использованию могут быть указаны в свойствах INTERFACE_*.

INTERFACE

Не ссылается на библиотечные файлы или файлы объектных файлов на диске, но может указывать требования к использованию в свойствах INTERFACE_*.

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

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

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