add_library

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

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

Обычные библиотеки

add_library(<name> [<type>] [EXCLUDE_FROM_ALL] <sources>...)

Добавляет цель-библиотеку с именем <name>, которая будет собрана из исходных файлов, перечисленных при вызове команды.

Необязательный параметр <type> задаёт тип создаваемой библиотеки:

STATIC

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

SHARED

Разделяемая библиотека: динамическая библиотека, которую могут компоновывать другие цели и загружать во время выполнения.

MODULE

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

Если параметр <type> не указан, по умолчанию используется STATIC или SHARED в зависимости от значения переменной BUILD_SHARED_LIBS.

Доступны следующие параметры:

EXCLUDE_FROM_ALL

Автоматически устанавливает свойство цели EXCLUDE_FROM_ALL. Подробности см. в документации этого свойства цели.

Параметр <name> соответствует логическому имени цели и должен быть уникальным в пределах всего проекта. Фактическое имя файла собранной библиотеки формируется в соответствии с соглашениями целевой платформы (например, lib<name>.a или <name>.lib).

Для библиотек SHARED и MODULE свойство цели POSITION_INDEPENDENT_CODE автоматически устанавливается в ON. Для библиотеки SHARED можно установить свойство цели FRAMEWORK, чтобы создать фреймворк macOS.

Если библиотека не экспортирует символы, её нельзя объявлять как библиотеку SHARED. Например, DLL ресурсов Windows или управляемая DLL C++/CLI, которая не экспортирует неуправляемые символы, должна быть библиотекой MODULE. Это связано с тем, что CMake ожидает, что у библиотеки SHARED в Windows всегда будет соответствующая библиотека импорта.

По умолчанию файл библиотеки создаётся в каталоге дерева сборки, соответствующем каталогу дерева исходных файлов, из которого была вызвана команда. Чтобы изменить это расположение, см. документацию свойств целей ARCHIVE_OUTPUT_DIRECTORY, LIBRARY_OUTPUT_DIRECTORY и RUNTIME_OUTPUT_DIRECTORY. Чтобы изменить часть <name> итогового имени файла, см. документацию свойства цели OUTPUT_NAME.

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

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

Объектные библиотеки

add_library(<name> OBJECT <sources>...)

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

Другие цели, созданные с помощью 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(), как и любая другая цель.

Добавлено в версии 3.15: Интерфейсная библиотека может иметь свойства PUBLIC_HEADER и PRIVATE_HEADER. Заголовочные файлы, указанные этими свойствами, можно установить с помощью команды install(TARGETS).

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

Добавлено в версии 3.19.

Добавляет цель интерфейсной библиотеки с исходными файлами (в дополнение к требованиям использования и свойствам, описанным в above signature). Исходные файлы можно перечислить непосредственно в вызове add_library или добавить позднее с помощью вызовов target_sources() с ключевыми словами PRIVATE или PUBLIC.

Если у интерфейсной библиотеки есть исходные файлы (то есть задано свойство цели SOURCES) или наборы заголовочных файлов (то есть задано свойство цели HEADER_SETS), она появится в сгенерированной системе сборки как цель сборки, подобно цели, определённой командой add_custom_target(). Она не компилирует исходные файлы, но содержит правила сборки для пользовательских команд, созданных командой add_custom_command().

Доступны следующие параметры:

EXCLUDE_FROM_ALL

Автоматически задаёт свойство цели EXCLUDE_FROM_ALL. Подробности см. в документации этого свойства цели.

Примечание

В большинстве сигнатур команд, где встречается ключевое слово INTERFACE, перечисленные после него элементы становятся только частью требований использования этой цели и не входят в её собственные настройки. Однако в этой сигнатуре add_library ключевое слово INTERFACE относится только к типу библиотеки. Исходные файлы, перечисленные после него в вызове add_library, PRIVATE интерфейсной библиотеке и не появляются в её свойстве цели INTERFACE_SOURCES.

add_library(<name> INTERFACE SYMBOLIC)

Добавлено в версии 4.2.

Добавляет символическую цель интерфейсной библиотеки. Символические интерфейсные библиотеки полезны для представления необязательных компонентов или возможностей пакета. У них нет требований использования, они не компилируют исходные файлы и не создают на диске артефакт библиотеки, но их можно экспортировать и устанавливать. Их также можно проверять на существование с помощью стандартной подкоманды if(TARGET).

Символическую интерфейсную библиотеку можно использовать как цель для компоновки, чтобы обеспечить наличие необязательных компонентов зависимости. Например, если библиотека libgui может предоставлять или не предоставлять возможность widget, потребительский пакет может выполнить компоновку с widget, чтобы указать, что этот компонент должен быть доступен. Это позволяет проверять вызовы find_package(), в которых объявлены обязательные компоненты, путём компоновки с соответствующими символическими целями.

Для символической интерфейсной библиотеки свойство цели SYMBOLIC имеет значение true.

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

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

Добавляет цель импортированной библиотеки с именем <name>. На цель можно ссылаться так же, как на любую цель, собираемую в проекте, за исключением того, что по умолчанию она видна только в каталоге, где создана, и его подкаталогах.

Значение <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 (это необязательно, но необходимо для генераторного выражения TARGET_RUNTIME_DLLS).

Дополнительные требования использования можно задать в свойствах INTERFACE_*.

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

OBJECT

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

INTERFACE

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

Доступны следующие параметры:

GLOBAL

Делает имя цели видимым глобально.

Для сборки импортированных целей правила не генерируются, а свойство цели IMPORTED имеет значение True. Импортированные библиотеки удобно использовать для ссылок из таких команд, как target_link_libraries().

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

См. также

• add_executable()