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

Псевдоним ALIAS на не-GLOBAL импортированную цель имеет область действия в каталоге, в котором создан псевдоним, и ниже. Свойство целевой библиотеки ALIAS_GLOBAL используется для проверки глобальности псевдонима.

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

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

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

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