Руководство по импорту и экспорту

Введение
Импорт целевых объектов
- Импорт исполняемых файлов
- Импорт библиотек
Экспорт целевых объектов
Создание переносимых пакетов
Использование файла конфигурации пакета
Добавление компонентов

Введение

В этом руководстве мы представим концепцию целевых объектов IMPORTED и продемонстрируем, как импортировать существующие исполняемые файлы или библиотеки с диска в проект CMake. Затем мы покажем, как CMake поддерживает экспорт целевых объектов из одного проекта CMake и их импорт в другой. Наконец, мы продемонстрируем, как упаковать проект с файлом конфигурации для лёгкой интеграции в другие проекты CMake. Это руководство и полный пример исходного кода можно найти в каталоге Help/guide/importing-exporting дерева исходного кода CMake.

Импорт целевых объектов

Целевые объекты IMPORTED используются для преобразования файлов за пределами проекта CMake в логические целевые объекты внутри проекта. Целевые объекты IMPORTED создаются с помощью опции IMPORTED команд add_executable() и add_library(). Для целевых объектов IMPORTED файлы сборки не генерируются. После импорта целевые объекты IMPORTED могут быть использованы как и любые другие целевые объекты в проекте и обеспечивают удобную и гибкую ссылку на внешние исполняемые файлы и библиотеки.

По умолчанию имя целевого объекта IMPORTED имеет область действия в каталоге, в котором он создаётся, и ниже. Мы можем использовать опцию GLOBAL для расширения видимости, чтобы целевой объект был доступен глобально в системе сборки.

Подробные сведения о целевом объекте IMPORTED задаются путём установки свойств, имена которых начинаются с IMPORTED_ и INTERFACE_. Например, IMPORTED_LOCATION содержит полный путь к целевому объекту на диске.

Импорт исполняемых файлов

Начнём с простого примера, который создаёт целевой объект IMPORTED исполняемого файла, а затем ссылается на него с помощью команды add_custom_command().

Для начала нам нужно выполнить некоторые настройки. Мы хотим создать исполняемый файл, который при запуске создаёт базовый файл main.cc в текущем каталоге. Подробности этого проекта не важны. Перейдите в Help/guide/importing-exporting/MyExe, создайте каталог сборки, запустите cmake и выполните сборку и установку проекта.

$ cd Help/guide/importing-exporting/MyExe
$ mkdir build
$ cd build
$ cmake ..
$ cmake --build .
$ cmake --install . --prefix <install location>
$ <install location>/myexe
$ ls
[...] main.cc [...]

Теперь мы можем импортировать этот исполняемый файл в другой проект CMake. Исходный код этого раздела доступен в Help/guide/importing-exporting/Importing. В файле CMakeLists используйте команду add_executable() для создания нового целевого объекта под названием myexe. Используйте опцию IMPORTED чтобы указать CMake, что этот целевой объект ссылается на исполняемый файл, расположенный за пределами проекта. Правила для его сборки не будут генерироваться, и свойство целевого объекта IMPORTED будет установлено в true.

add_executable(myexe IMPORTED)

Далее, установите свойство IMPORTED_LOCATION целевого объекта с помощью команды set_property(). Это сообщит CMake о расположении целевого объекта на диске. Возможно, потребуется скорректировать расположение до <install location> указанного на предыдущем шаге.

set_property(TARGET myexe PROPERTY
             IMPORTED_LOCATION "../InstallMyExe/bin/myexe")

Теперь мы можем использовать этот целевой объект IMPORTED так же, как и любой другой целевой объект, собранный внутри проекта. В этом случае предположим, что мы хотим использовать сгенерированный исходный файл в нашем проекте. Используйте целевой объект IMPORTED в команде add_custom_command():

add_custom_command(OUTPUT main.cc COMMAND myexe)

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

Наконец, используйте вывод от add_custom_command():

add_executable(mynewexe main.cc)

Импорт библиотек

Аналогичным образом к библиотекам из других проектов можно получить доступ через целевые объекты IMPORTED.

Примечание: Полный исходный код примеров в этом разделе не предоставлен и оставлен в качестве упражнения для читателя.

В файле CMakeLists добавьте библиотеку IMPORTED и укажите её расположение на диске:

add_library(foo STATIC IMPORTED)
set_property(TARGET foo PROPERTY
             IMPORTED_LOCATION "/path/to/libfoo.a")

Затем используйте библиотеку IMPORTED внутри нашего проекта:

add_executable(myexe src1.c src2.c)
target_link_libraries(myexe PRIVATE foo)

В Windows .dll и её .lib библиотека импорта могут быть импортированы вместе:

add_library(bar SHARED IMPORTED)
set_property(TARGET bar PROPERTY
             IMPORTED_LOCATION "c:/path/to/bar.dll")
set_property(TARGET bar PROPERTY
             IMPORTED_IMPLIB "c:/path/to/bar.lib")
add_executable(myexe src1.c src2.c)
target_link_libraries(myexe PRIVATE bar)

Библиотека с несколькими конфигурациями может быть импортирована с помощью одного целевого объекта:

find_library(math_REL NAMES m)
find_library(math_DBG NAMES md)
add_library(math STATIC IMPORTED GLOBAL)
set_target_properties(math PROPERTIES
  IMPORTED_LOCATION "${math_REL}"
  IMPORTED_LOCATION_DEBUG "${math_DBG}"
  IMPORTED_CONFIGURATIONS "RELEASE;DEBUG"
)
add_executable(myexe src1.c src2.c)
target_link_libraries(myexe PRIVATE math)

Сгенерированная система сборки будет связывать myexe с m.lib при сборке в конфигурации release, и md.lib при сборке в конфигурации debug.

Экспорт целевых объектов

Хотя целевые объекты IMPORTED сами по себе полезны, они всё же требуют, чтобы проект, который их импортирует, знал расположение файлов целевого объекта на диске. Настоящая мощь целевых объектов IMPORTED проявляется, когда проект, предоставляющий файлы целевого объекта, также предоставляет файл CMake для помощи в их импорте. Проект может быть настроен для создания необходимой информации, чтобы его можно было легко использовать другими проектами CMake, будь то из каталога сборки, локальной установки или при упаковке.

В оставшихся разделах мы последовательно разберём набор примеров проектов. Первый проект создаст и установит библиотеку и соответствующие файлы конфигурации и пакета CMake. Второй проект будет использовать сгенерированный пакет.

Начнём с рассмотрения проекта MathFunctions в каталоге Help/guide/importing-exporting/MathFunctions. Здесь у нас есть заголовочный файл MathFunctions.h, который объявляет функцию sqrt:

#pragma once

namespace MathFunctions {
double sqrt(double x);
}

И соответствующий исходный файл MathFunctions.cxx:

#include "MathFunctions.h"

#include <cmath>

namespace MathFunctions {
double sqrt(double x)
{
  return std::sqrt(x);
}
}

Не беспокойтесь слишком сильно о деталях файлов C++, они просто предназначены как простой пример, который будет компилироваться и запускаться на многих системах сборки.

Теперь мы можем создать файл CMakeLists.txt для проекта MathFunctions. Начните с указания версии cmake_minimum_required() и имени project():

cmake_minimum_required(VERSION 3.15)
project(MathFunctions)

# specify the C++ standard
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED True)

Создайте библиотеку под названием MathFunctions с помощью команды add_library():

add_library(MathFunctions STATIC MathFunctions.cxx)

Затем используйте команду target_include_directories(), чтобы указать каталоги включения для целевого объекта:

target_include_directories(MathFunctions
                           PUBLIC
                           "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>"
                           "$<INSTALL_INTERFACE:include>"
)

Нам нужно сообщить CMake, что мы хотим использовать разные каталоги включения в зависимости от того, собираем ли мы библиотеку или используем её из установленной локации. Если этого не сделать, при создании информации об экспорте CMake экспортирует путь, специфичный для текущей директории сборки, и он не будет действительным для других проектов. Мы можем использовать generator expressions, чтобы указать, что при сборке библиотеки включить текущую директорию исходных файлов. В противном случае, при установке, включить директорию include . Более подробную информацию см. в разделе «Создание переносимых пакетов».

Команды install(TARGETS) и install(EXPORT) работают вместе для установки как целевых объектов (в нашем случае библиотеки), так и файла CMake, предназначенного для упрощения импорта целевых объектов в другой проект CMake.

В первую очередь, в команде install(TARGETS) мы укажем целевой объект, имя EXPORT и назначения, которые сообщают CMake, куда установить целевые объекты.

install(TARGETS MathFunctions
        EXPORT MathFunctionsTargets
        LIBRARY DESTINATION lib
        ARCHIVE DESTINATION lib
        RUNTIME DESTINATION bin
        INCLUDES DESTINATION include
)

Здесь опция EXPORT сообщает CMake создать экспорт под названием MathFunctionsTargets. Сгенерированные целевые объекты IMPORTED имеют соответствующие свойства, определяющие их требования к использованию, такие как INTERFACE_INCLUDE_DIRECTORIES, INTERFACE_COMPILE_DEFINITIONS и другие соответствующие встроенные INTERFACE_ свойства. Вариант INTERFACE пользовательских свойств, перечисленных в COMPATIBLE_INTERFACE_STRING и другие Свойства совместимого интерфейса также передаются сгенерированным целевым объектам IMPORTED. Например, в данном случае целевой объект IMPORTED будет иметь своё свойство INTERFACE_INCLUDE_DIRECTORIES, заполненное директорией, указанной свойством INCLUDES DESTINATION. Поскольку был задан относительный путь, он рассматривается как относительный к CMAKE_INSTALL_PREFIX.

Обратите внимание, мы не попросили CMake установить экспорт ещё.

Не забывайте установить файл заголовка MathFunctions.h с помощью команды install(FILES). Файл заголовка должен быть установлен в директорию include, как указано в команде target_include_directories() выше.

install(FILES MathFunctions.h DESTINATION include)

Теперь, когда библиотека MathFunctions и файл заголовка установлены, нам также необходимо явно установить подробности экспорта MathFunctionsTargets . Используйте команду install(EXPORT) для экспорта целевых объектов в MathFunctionsTargets, как определено командой install(TARGETS).

install(EXPORT MathFunctionsTargets
        FILE MathFunctionsTargets.cmake
        NAMESPACE MathFunctions::
        DESTINATION lib/cmake/MathFunctions
)

Эта команда генерирует файл MathFunctionsTargets.cmake и устанавливает его в lib/cmake. Этот файл содержит код, подходящий для использования другими проектами для импорта всех целевых объектов, перечисленных в команде установки, из дерева установки.

Опция NAMESPACE добавит MathFunctions:: к именам целевых объектов при записи в файл экспорта. Эта конвенция с двойными двоеточиями подсказывает CMake, что имя является целевым объектом IMPORTED при использовании в проектах-потомках. Таким образом, CMake может вывести диагностическое сообщение, если пакет, который его предоставляет, не найден.

Сгенерированный файл экспорта содержит код, создающий IMPORTED библиотеку.

# Create imported target MathFunctions::MathFunctions
add_library(MathFunctions::MathFunctions STATIC IMPORTED)

set_target_properties(MathFunctions::MathFunctions PROPERTIES
  INTERFACE_INCLUDE_DIRECTORIES "${_IMPORT_PREFIX}/include"
)

Этот код очень похож на пример, который мы создали вручную в разделе «Импортирование библиотек». Обратите внимание, что ${_IMPORT_PREFIX} вычисляется относительно расположения файла.

Внешний проект может загрузить этот файл с помощью команды include() и сослаться на библиотеку MathFunctions из дерева установки, как будто она была собрана в своём собственном дереве. Например:

1
2
3

Строка 1 загружает файл CMake целевого объекта. Хотя мы экспортировали только один целевой объект, этот файл может импортировать любое количество целевых объектов. Их расположение вычисляется относительно расположения файла, чтобы дерево установки легко можно было перемещать. Строка 3 ссылается на импортированную библиотеку MathFunctions из дерева установки. Результирующая система сборки будет подключаться к библиотеке из её установленной локации.

Исполняемые файлы также можно экспортировать и импортировать с помощью той же процедуры.

Любое количество установок целевых объектов может быть связано с одним и тем же именем экспорта. Имена экспортов считаются глобальными, поэтому любая директория может вносить установку целевого объекта. Команда install(EXPORT) должна быть вызвана только один раз для установки файла, который ссылается на все целевые объекты. Ниже приведен пример того, как несколько экспортов можно объединить в один файл экспорта, даже если они находятся в разных поддиректориях проекта.

# A/CMakeLists.txt
add_executable(myexe src1.c)
install(TARGETS myexe DESTINATION lib/myproj
        EXPORT myproj-targets)

# B/CMakeLists.txt
add_library(foo STATIC foo1.c)
install(TARGETS foo DESTINATION lib EXPORTS myproj-targets)

# Top CMakeLists.txt
add_subdirectory (A)
add_subdirectory (B)
install(EXPORT myproj-targets DESTINATION lib/myproj)

Создание пакетов

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

Для начала нам нужно внести несколько изменений в файл CMakeLists.txt. В первую очередь, включите модуль CMakePackageConfigHelpers, чтобы получить доступ к некоторым вспомогательным функциям для создания файлов конфигурации.

include(CMakePackageConfigHelpers)

Затем мы создадим файл конфигурации пакета и файл версии пакета.

Создание файла конфигурации пакета

Используйте команду configure_package_config_file(), предоставляемую модулем CMakePackageConfigHelpers, для генерации файла конфигурации пакета. Обратите внимание, что эту команду следует использовать вместо обычной команды configure_file(). Это помогает обеспечить переносимость полученного пакета, избегая жёстко закодированных путей в установленных файлах конфигурации. Путь, заданный для INSTALL_DESTINATION должен быть местом назначения, куда будет установлен файл MathFunctionsConfig.cmake . В следующем разделе мы рассмотрим содержимое файла конфигурации пакета.

configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in
  "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake"
  INSTALL_DESTINATION lib/cmake/MathFunctions
)

Установите сгенерированные файлы конфигурации с помощью команды INSTALL(files). И MathFunctionsConfigVersion.cmake и MathFunctionsConfig.cmake устанавливаются в одно место, завершая создание пакета.

install(FILES
          "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake"
          "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake"
        DESTINATION lib/cmake/MathFunctions
)

Теперь нам нужно создать собственный файл конфигурации пакета. В этом случае файл Config.cmake.in очень прост, но достаточно, чтобы позволить последующим этапам использовать цели IMPORTED.

@PACKAGE_INIT@

include("${CMAKE_CURRENT_LIST_DIR}/MathFunctionsTargets.cmake")

check_required_components(MathFunctions)

Первая строка файла содержит только строку @PACKAGE_INIT@. Она расширяется при конфигурировании файла и позволяет использовать перемещаемые пути, префикс которых PACKAGE_. Она также предоставляет макросы set_and_check() и check_required_components().

Макропомощник check_required_components гарантирует, что все запрошенные, необязательные компоненты найдены путем проверки переменных <Package>_<Component>_FOUND для всех необходимых компонентов. Этот макрос должен вызываться в конце файла конфигурации пакета, даже если пакет не имеет компонентов. Таким образом, CMake может убедиться, что проект последующей стадии не указал несуществующие компоненты. Если check_required_components завершится неудачно, переменная <Package>_FOUND устанавливается в FALSE, и пакет считается не найденным.

Макрос set_and_check() следует использовать в файлах конфигурации вместо обычной команды set() для задания каталогов и расположения файлов. Если ссылаемый файл или каталог не существует, макрос завершится неудачно.

Если пакет MathFunctions должен предоставить какие-либо макросы, они должны находиться в отдельном файле, который устанавливается в то же место, что и файл MathFunctionsConfig.cmake, и включаться оттуда.

Все необходимые зависимости пакета также должны быть найдены в файле конфигурации пакета. Предположим, что нам необходима библиотека Stats в нашем проекте. В файле CMakeLists мы добавим:

find_package(Stats 2.6.4 REQUIRED)
target_link_libraries(MathFunctions PUBLIC Stats::Types)

Поскольку цель Stats::Types является зависимостью типа PUBLIC от MathFunctions, последующие стадии также должны найти пакет Stats и связаться с библиотекой Stats::Types. Пакет Stats должен быть найден в файле конфигурации для обеспечения этого.

include(CMakeFindDependencyMacro)
find_dependency(Stats 2.6.4)

Макрос find_dependency из модуля CMakeFindDependencyMacro помогает распространять, является ли пакет REQUIRED, или QUIET, и т. д. Макрос find_dependency также устанавливает MathFunctions_FOUND в False, если зависимость не найдена, наряду с диагностическим сообщением о том, что пакет MathFunctions не может использоваться без пакета Stats.

Упражнение: Добавьте необходимую библиотеку в проект MathFunctions.

Создание файла версии пакета

Модуль CMakePackageConfigHelpers предоставляет команду write_basic_package_version_file() для создания простого файла версии пакета. Этот файл считывается CMake, когда вызывается find_package(), чтобы определить совместимость с запрошенной версией и установить некоторые зависящие от версии переменные, такие как <PackageName>_VERSION, <PackageName>_VERSION_MAJOR, <PackageName>_VERSION_MINOR и т. д. См. документацию cmake-packages для получения более подробной информации.

set(version 3.4.1)

set_property(TARGET MathFunctions PROPERTY VERSION ${version})
set_property(TARGET MathFunctions PROPERTY SOVERSION 3)
set_property(TARGET MathFunctions PROPERTY
  INTERFACE_MathFunctions_MAJOR_VERSION 3)
set_property(TARGET MathFunctions APPEND PROPERTY
  COMPATIBLE_INTERFACE_STRING MathFunctions_MAJOR_VERSION
)

# generate the version file for the config file
write_basic_package_version_file(
  "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake"
  VERSION "${version}"
  COMPATIBILITY AnyNewerVersion
)

В нашем примере MathFunctions_MAJOR_VERSION определен как COMPATIBLE_INTERFACE_STRING, что означает, что он должен быть совместимым среди зависимостей любого зависимого. Установив эту пользовательскую собственную настройку в этой версии и в следующей версии MathFunctions, cmake выдаст диагностическое сообщение, если будет предпринята попытка использования версии 3 вместе с версией 4. Пакеты могут выбрать такой подход, если разные главные версии пакета разработаны для несовместимости.

Экспорт целей из дерева сборки

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

Если мы хотим, чтобы наш пример проекта также использовался из каталога сборки, нам нужно только добавить следующее в CMakeLists.txt:

export(EXPORT MathFunctionsTargets
       FILE "${CMAKE_CURRENT_BINARY_DIR}/cmake/MathFunctionsTargets.cmake"
       NAMESPACE MathFunctions::
)

Здесь мы используем команду export(), чтобы сгенерировать цели экспорта для дерева сборки. В этом случае мы создадим файл, названный MathFunctionsTargets.cmake в подкаталоге cmake каталога сборки. Сгенерированный файл содержит необходимый код для импорта цели и может быть загружен внешним проектом, который осведомлен о дереве сборки проекта. Этот файл специфичен для дерева сборки и не является перемещаемым.

Можно создать подходящий файл конфигурации пакета и файл версии пакета для определения пакета для дерева сборки, который может использоваться без установки. Потребители дерева сборки могут просто убедиться, что CMAKE_PREFIX_PATH содержит каталог сборки или установить MathFunctions_DIR в <build_dir>/MathFunctions в кэше.

Пример применения этой функции — построение исполняемого файла на платформе хоста при кросс-компиляции. Проект, содержащий исполняемый файл, может быть собран на платформе хоста, а затем проект, который компилируется для другой платформы, может его загрузить.

Сборка и установка пакета

На этом этапе мы сгенерировали перемещаемую конфигурацию CMake для нашего проекта, которая может быть использована после установки проекта. Попробуем собрать проект MathFunctions:

mkdir MathFunctions_build
cd MathFunctions_build
cmake ../MathFunctions
cmake --build .

В каталоге сборки обратите внимание, что файл MathFunctionsTargets.cmake был создан в подкаталоге cmake.

Теперь установите проект:

$ cmake --install . --prefix "/home/myuser/installdir"

Создание перемещаемых пакетов

Пакеты, созданные командой install(EXPORT), предназначены для перемещаемости, используя пути, относительные к расположению самого пакета. Они не должны ссылаться на абсолютные пути файлов на машине, где пакет был собран, которые не будут существовать на машинах, где пакет может быть установлен.

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

target_include_directories(tgt INTERFACE
  # Wrong, not relocatable:
  $<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/include/TgtName>
)

target_include_directories(tgt INTERFACE
  # Ok, relocatable:
  $<INSTALL_INTERFACE:include/TgtName>
)

$<INSTALL_PREFIX> generator expression может использоваться в качестве заполнителя для префикса установки без создания неперемещаемого пакета. Это необходимо, если используются сложные генераторные выражения:

target_include_directories(tgt INTERFACE
  # Ok, relocatable:
  $<INSTALL_INTERFACE:$<INSTALL_PREFIX>/include/TgtName>
)

Это также относится к путям, ссылающимся на внешние зависимости. Не рекомендуется заполнять свойства, которые могут содержать пути, такие как INTERFACE_INCLUDE_DIRECTORIES или INTERFACE_LINK_LIBRARIES, путями, относящимися к зависимостям. Например, этот код может плохо работать для перемещаемого пакета:

target_link_libraries(MathFunctions INTERFACE
  ${Foo_LIBRARIES} ${Bar_LIBRARIES}
  )
target_include_directories(MathFunctions INTERFACE
  "$<INSTALL_INTERFACE:${Foo_INCLUDE_DIRS};${Bar_INCLUDE_DIRS}>"
  )

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

В идеале такие зависимости следует использовать через собственные IMPORTED цели, у которых есть свои свойства IMPORTED_LOCATION и требования к использованию, такие как INTERFACE_INCLUDE_DIRECTORIES, заполненные соответствующим образом. Эти импортированные цели могут затем использоваться с командой target_link_libraries() для MathFunctions:

target_link_libraries(MathFunctions INTERFACE Foo::Foo Bar::Bar)

С этим подходом пакет ссылается на свои внешние зависимости только по именам импортированных целей. Когда пользователь использует установленный пакет, пользователь запустит соответствующие find_package() команды (через макрос find_dependency описанный выше), чтобы найти зависимости и заполнить импортированные цели соответствующими путями на своей машине.

Использование файла конфигурации пакета

Теперь мы готовы создать проект для использования установленной MathFunctions библиотеки. В этом разделе мы будем использовать исходный код из Help\guide\importing-exporting\Downstream. В этом каталоге есть исходный файл под названием main.cc, который использует MathFunctions библиотеку для вычисления квадратного корня заданного числа и затем выводит результаты:

// A simple program that outputs the square root of a number
#include <iostream>
#include <string>

#include "MathFunctions.h"

int main(int argc, char* argv[])
{
  if (argc < 2) {
    std::cout << "Usage: " << argv[0] << " number" << std::endl;
    return 1;
  }

  // convert input to double
  const double inputValue = std::stod(argv[1]);

  // calculate square root
  const double sqrt = MathFunctions::sqrt(inputValue);
  std::cout << "The square root of " << inputValue << " is " << sqrt
            << std::endl;

  return 0;
}

Как и прежде, мы начнём с команд cmake_minimum_required() и project() в файле CMakeLists.txt. Для этого проекта мы также укажем стандарт C++.

cmake_minimum_required(VERSION 3.15)
project(Downstream)

# specify the C++ standard
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED True)

Мы можем использовать команду find_package():

find_package(MathFunctions 3.4.1 EXACT)

Создать исполняемый файл:

add_executable(myexe main.cc)

И подключиться к MathFunctions библиотеке:

target_link_libraries(myexe PRIVATE MathFunctions::MathFunctions)

Вот и всё! Теперь давайте попробуем построить проект Downstream.

mkdir Downstream_build
cd Downstream_build
cmake ../Downstream
cmake --build .

Во время настройки CMake могла появиться ошибка:

CMake Warning at CMakeLists.txt:4 (find_package):
  By not providing "FindMathFunctions.cmake" in CMAKE_MODULE_PATH this
  project has asked CMake to find a package configuration file provided by
  "MathFunctions", but CMake did not find one.

  Could not find a package configuration file provided by "MathFunctions"
  with any of the following names:

    MathFunctionsConfig.cmake
    mathfunctions-config.cmake

  Add the installation prefix of "MathFunctions" to CMAKE_PREFIX_PATH or set
  "MathFunctions_DIR" to a directory containing one of the above files.  If
  "MathFunctions" provides a separate development package or SDK, be sure it
  has been installed.

Установите CMAKE_PREFIX_PATH в место, где MathFunctions был установлен ранее, и попробуйте снова. Убедитесь, что только что созданный исполняемый файл работает как ожидалось.

Добавление компонентов

Давайте отредактируем проект MathFunctions для использования компонентов. Исходный код для этого раздела можно найти в Help\guide\importing-exporting\MathFunctionsComponents. Файл CMakeLists для этого проекта добавляет две подпапки: Addition и SquareRoot.

cmake_minimum_required(VERSION 3.15)
project(MathFunctionsComponents)

# specify the C++ standard
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED True)

add_subdirectory(Addition)
add_subdirectory(SquareRoot)

Сгенерировать и установить файлы конфигурации пакета и версию пакета:

include(CMakePackageConfigHelpers)

# set version
set(version 3.4.1)

# generate the version file for the config file
write_basic_package_version_file(
  "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake"
  VERSION "${version}"
  COMPATIBILITY AnyNewerVersion
)

# create config file
configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in
  "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake"
  INSTALL_DESTINATION lib/cmake/MathFunctions
  NO_CHECK_REQUIRED_COMPONENTS_MACRO
)

# install config files
install(FILES
          "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake"
          "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake"
        DESTINATION lib/cmake/MathFunctions
)

Если COMPONENTS указаны, когда потомки используют find_package(), они перечислены в переменной <PackageName>_FIND_COMPONENTS. Мы можем использовать эту переменную для проверки того, что все необходимые целевые компоненты включены в Config.cmake.in. Одновременно эта функция будет действовать как пользовательский макрос check_required_components, чтобы убедиться, что дочерние элементы пытаются использовать только поддерживаемые компоненты.

@PACKAGE_INIT@

set(_supported_components Addition SquareRoot)

foreach(_comp ${MathFunctions_FIND_COMPONENTS})
  if (NOT _comp IN_LIST _supported_components)
    set(MathFunctions_FOUND False)
    set(MathFunctions_NOT_FOUND_MESSAGE "Unsupported component: ${_comp}")
  endif()
  include("${CMAKE_CURRENT_LIST_DIR}/MathFunctions${_comp}Targets.cmake")
endforeach()

Здесь MathFunctions_NOT_FOUND_MESSAGE задан как сообщение о том, что пакет не был найден, потому что был указан недопустимый компонент. Эта переменная сообщения может быть установлена для любых случаев, когда переменная _FOUND имеет значение False, и будет отображена пользователю.

Каталоги Addition и SquareRoot похожи. Давайте посмотрим на один из файлов CMakeLists:

# create library
add_library(SquareRoot STATIC SquareRoot.cxx)

add_library(MathFunctions::SquareRoot ALIAS SquareRoot)

# add include directories
target_include_directories(SquareRoot
                           PUBLIC
                           "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>"
                           "$<INSTALL_INTERFACE:include>"
)

# install the target and create export-set
install(TARGETS SquareRoot
        EXPORT SquareRootTargets
        LIBRARY DESTINATION lib
        ARCHIVE DESTINATION lib
        RUNTIME DESTINATION bin
        INCLUDES DESTINATION include
)

# install header file
install(FILES SquareRoot.h DESTINATION include)

# generate and install export file
install(EXPORT SquareRootTargets
        FILE MathFunctionsSquareRootTargets.cmake
        NAMESPACE MathFunctions::
        DESTINATION lib/cmake/MathFunctions
)

Теперь мы можем собрать проект, как описано в предыдущих разделах. Чтобы протестировать использование этого пакета, мы можем использовать проект в Help\guide\importing-exporting\DownstreamComponents. Есть два отличия от предыдущего проекта Downstream. Во-первых, нам нужно найти компоненты пакета. Измените строку find_package со:

find_package(MathFunctions 3.4.1 EXACT)

на:

find_package(MathFunctions 3.4 COMPONENTS Addition SquareRoot)

и строку target_link_libraries со:

target_link_libraries(myexe PRIVATE MathFunctions::MathFunctions)

на:

target_link_libraries(myexe PRIVATE MathFunctions::Addition MathFunctions::SquareRoot)

В main.cc, замените #include MathFunctions.h на:

#include "Addition.h"
#include "SquareRoot.h"

Наконец, используйте Addition библиотеку:

  const double sum = MathFunctions::add(inputValue, inputValue);
  std::cout << inputValue << " + " << inputValue << " = " << sum << std::endl;

Соберите проект Downstream и убедитесь, что он может найти и использовать компоненты пакета.

© 2000–2021 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/v3.20/guide/importing-exporting/index.html