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 resource 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 о том, что делать, если некоторые исходные файлы предварительно обработаны, и вам необходимо иметь доступ к исходным файлам в среде разработки.

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

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-импортной библиотеки (.lib или .dll.a ) на диске, а IMPORTED_LOCATION — это местоположение .dll библиотеки времени выполнения (и является необязательным).

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

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

OBJECT

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

INTERFACE

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

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

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

add_library(<name> ALIAS <target>)

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

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