CMake-команда add_library

Звичайні бібліотеки

Сигнатура

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

Опис

Додає файлову ціль бібліотеки з назвою <name> для побудови з вказаних файлів вихідного дерельного коду з виклику даної команди. Ім’я <name> відповідає назві логічної цілі і має являти собою унікальний ідентифікатор в межах проекту. Кінцева назва файлу побудованої бібліотеки конструюється у відповідності правилам платформи призначення (на подобі lib<name>.a або <name>.lib).

Нововведення у версії 3.1: Аргументи файлів вихідного джерельного коду для команди add_library() можуть використовувати вирази генерації, що використовує синтаксис $<...>. Перегляньте їхню документацію на сторінці cmake-generator-expressions(7) за доступними виразами.

Нововведення у версії 3.11: Файли вихідного джерельного коду можуть бути не вказаними, якщо вони будуть пізніше доданими за допомогою команди target_sources().

Параметри STATIC, SHARED або MODULE можуть надаватися для вказування типу бібліотеки що будується. Статичні бібліотеки що вказуються за допомогою параметру STATIC являються архівами об’єктних файлів для використання під час компонування цілей. Динамічні бібліотеки, які створюються за допомогою параметру SHARED компонуються динамічно і завантажуються під час виконання кінцевої побудованої програми. Модулі, які створюються за допомогою параметру MODULE являються додатками або розширеннями, які не компонуються з іншими цілями, але можуть завантажуватись динамічно під час виконання програм, використовуючи dlopen і суміжну з нею функціональність. Якщо не вказано жодного типу тоді неявно використовується STATIC або SHARED тип в залежності від значення змінної BUILD_SHARED_LIBS. Для бібліотек побудованих з параметрами SHARED або MODULE цільова властивість POSITION_INDEPENDENT_CODE встановлюється у значення ON автоматично. Бібліотека, яка зібрана з SHARED параметром може позначатись цільовою властивістю FRAMEWORK для створення фреймворку для операційної системи macOS.

Нововведення у версії 3.8: Статична бібліотека зібрана з параметром STATIC може позначатись цільовою властивістю FRAMEWORK для створення статичного фреймворку.

Якщо бібліотека не експортує жодних символів, вона не повинна оголошуватись у якості динамічної бібліотеки за допомогою параметру SHARED. Наприклад, DLL-ресурс ОС MS Windows або С++/CLI DLL бібліотека, яка не експортує жодних символів повинна помічатись параметром MODULE. Причина криється у тому, що система Cmake очікує щоб бібліотека побудована з параметром SHARED мала асоційовану імпортовану бібліотеку на ОС MS Windows.

За умовчанням файл бібліотеки буде створено у дереві каталогів у відповідності до дерева каталогів наданого джерельного вихідного коду з якого дана команда була викликана. Детальніше у документації на цільові властивості ARCHIVE_OUTPUT_DIRECTORY, LIBRARY_OUTPUT_DIRECTORY і RUNTIME_OUTPUT_DIRECTORY щоб змінити кінцеве розміщення цільового файлу збудованої бібліотеки. Детальніше у документації про цільову властивість OUTPUT_NAME для зміни частини імені <name> фінальної назви файлу.

Якщо надається EXCLUDE_FROM_ALL — відповідна властивість буде встановленою на створеній цілі. Деталі у документації по цільовій властивості EXCLUDE_FROM_ALL.

Більше деталей про те як створюються властивості системи будування на сторінці документації по cmake-buildsystem(7).

Деталі того, що робити якщо деякі файли вихідного джерельного коду потребують попередньої обробки і є необхідність доступу до них у оригінальному вигляді з використовуваної IDE, розміщені на сторінці документації 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> ...)

Нововведення у версії 3.12: Компонування з об’єктними бібліотеками може виконуватись за допомогою команди target_link_libraries().

Інтерфейсні бібліотеки

add_library(<name> INTERFACE)

Створює інтерфейсну бібліотеку. Інтерфейсна бібліотека створена за допомогою параметру 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).

Нововведення у версії 3.19: Ціль інтерфейсної бібліотеки може створюватись з вказуванням джерельних файлів вихідного коду:

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

Файли джерельного вихідного коду можуть вказуватись прямо у команді add_library() або доданими пізніше за допомогою викликів команди target_sources() з використанням ключових слів PRIVATE або PUBLIC.

Якщо інтерфейсна бібліотека має файли вихідного джерельного коду (тобто цільова властивість SOURCES є встановленою) або набори заголовкових файлів (тобто встановлено цільову властивість HEADER_SETS), вона з’явиться у згенерованій системі побудови у якості цілі побудови на подобі цілі визначеною за допомогою команди add_custom_target(). Вона не компілює жодних джерельних файлів вихідного коду, однак містить правила побудови для визначених користувачем нових команд створених за домомогою команди add_custom_command().

Зверніть увагу. У більшості сигнатур команди де з’являється ключове слово INTERFACE, елементи вказані після неї стають частиною вимог використання даної цілі і не являються частиною її налаштувань. Однак, у даній сигнатурі команди add_library, ключове слово INTERFACE відноситься тільки до типу бібліотеки. Файли вихідного джерельного коду вказані після виклику add_library являються приватними для інтерфейної бібліотеки і не з’являються у її властивості INTERFACE_SOURCES.

Імпортовані бібліотеки

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

Створює ціль для імпортованої бібліотеки названою <name>. Жодні правила генеруються для її побудови, і цільова властивість IMPORTED встановлюється у True. Ім’я цілі має область видимості у директорії у якій вона створена і в дочірніх, але опція GLOBAL розширює видимість. До неї можна звертатись з команд на подобі target_link_libraries(). Детальні про імпортовану бібліотеку вказуються за допомогою встановлення властивостей імена яких починаються з IMPORTED_ і INTERFACE_.

Параметр вкзаганий у якості значення для <type> повинен бути одним з наступних.

STATIC, SHARED_MODULE, UNKNOWN

Звертається до файлу бібліотеки, який розміщений ззовні проекту. Цільова властивість IMPORTED_LOCATION (або її варіант IMPORTED_LOCATION_<CONFIG> для кожної окремої конфігурації) вказує розміщення головного файлу бібліотеки на диску:

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

OBJECT

Вказує набір об’єктих файлів, які розміщені ззовні проекту. Цільова властивість IMPORTED_OBJECTS (або її варіант IMPORTED_OBJECTS_<CONFIG>) вказує розміщення об’єкту файлів на диску. Додаткові вимоги використання можуть вказуватись через властивості з префіксом INTERFACE_* у імені.

INTERFACE

Не звертається до будь-якої бібліотеки чи об’єктних файлів на диску, але може вказувати вимоги використання у властивостях INTERFACE_*.

Деталі у документації до властивостей IMPORTED_* і INTERFACE_*.

Бібліотечні псевдоніми

add_library(<name> ALIAS <target>)

Створює псевдонім цілі, такий що назва <name> може бути використаною щоб звертатись до цілі <target> у наступних командах. Ім’я <name> не з’являється у згенерованій системі побудови у якості цілі побудови. Ціль <target> не може являтись псевдонімом.

Нововведення у версії 3.11: Псевдонім може звертатись до глобальної імпортованої цілі (GLOBAL).

Нововведення у версії 3.18: Псевдонім може звертатись до не глобальної імпортованої цілі. Такий псевдонім має область видимості чи існування у директорії у якій він був створений або в дочірніх директоріях. Цільова властивість ALIAS_GLOBAL може використовуватись для перевірки чи псевдонім являється глобальним чи ні.

Цілі псевдоніми можуть використовуватись у якості цілей здатних до компонування і у якості цілей для зчитування властивостей. Вони також можуть тестуватись на існування у звичайній підкоманді if(TARGET). Ім’я <name> не може використовуватись для модвифікування цілі <target>, тобто, вона не може використовуватись у якості операнду до команд set_property(), set_target_properties(), target_link_libraries() тощо. Ціль псевдонім не може інсталюватись або експортуватись.

Перегляньте також

Приклад

Тривіальний приклад використання команди add_library() можна переглянути за адресою https://github.com/yuriysydor1991/Qt1SimpleTextEditor/blob/1.0.0/src/window/CMakeLists.txt#L26 у проекті простого текстового редактора написаного на C++17 з використанням візуальної системи Qt5. Адреса проекту на GitHub https://github.com/yuriysydor1991/Qt1SimpleTextEditor.

Оригінал документу

Оригінал документу розміщений за адресою https://cmake.org/cmake/help/latest/command/add_library.html