cmake-packages(7)

• Введение

• Использование пакетов

  • Пакеты с файлами конфигурации
  • Пакеты с модулями поиска

• Структура пакета

  • Файл конфигурации пакета
  • Файл версии пакета

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

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

    • Создание файла конфигурации пакета для дерева сборки
  • Создание переносимых пакетов

• Регистр пакетов

  • Регистр пакетов пользователя
  • Системный регистр пакетов
  • Отключение регистра пакетов
  • Пример регистра пакетов
  • Владение регистром пакетов

Введение

Пакеты предоставляют информацию о зависимостях для систем сборки CMake. Пакеты находятся с помощью команды find_package(). Результатом использования find_package() является либо набор IMPORTED целей, либо набор переменных, соответствующих информации, необходимой для сборки.

Использование пакетов

CMake предоставляет прямую поддержку для двух типов пакетов: пакетов с файлами конфигурации и пакетов с модулями поиска. Непрямая поддержка pkg-config пакетов также предоставляется через модуль FindPkgConfig. Во всех случаях базовая форма вызовов find_package() одинакова:

find_package(Qt4 4.7.0 REQUIRED) # CMake provides a Qt4 find-module
find_package(Qt5Core 5.1.0 REQUIRED) # Qt provides a Qt5 package config file.
find_package(LibXml2 REQUIRED) # Use pkg-config via the LibXml2 find-module

В тех случаях, когда известно, что файл конфигурации пакета предоставляется предком, и следует использовать только его, ключевое слово CONFIG может быть передано команде find_package():

find_package(Qt5Core 5.1.0 CONFIG REQUIRED)
find_package(Qt5Gui 5.1.0 CONFIG)

Аналогично, ключевое слово MODULE указывает на использование только модуля поиска:

find_package(Qt4 4.7.0 MODULE REQUIRED)

Явное указание типа пакета улучшает сообщение об ошибке, отображаемое пользователю, если пакет не найден.

Оба типа пакетов также поддерживают указание компонентов пакета, либо после ключевого слова REQUIRED:

find_package(Qt5 5.1.0 CONFIG REQUIRED Widgets Xml Sql)

или как отдельный список COMPONENTS:

find_package(Qt5 5.1.0 COMPONENTS Widgets Xml Sql)

или как отдельный список OPTIONAL_COMPONENTS:

find_package(Qt5 5.1.0 COMPONENTS Widgets
                       OPTIONAL_COMPONENTS Xml Sql
)

Обработка COMPONENTS и OPTIONAL_COMPONENTS определяется пакетом.

Установив переменную CMAKE_DISABLE_FIND_PACKAGE_<PackageName> в значение TRUE, поиск пакета <PackageName> не будет выполняться, и он всегда будет NOTFOUND.

Пакеты с файлами конфигурации

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

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

Автоматически также устанавливается набор переменных, предоставляющих информацию о состоянии пакета. Переменная <PackageName>_FOUND устанавливается в значение true или false в зависимости от того, был ли пакет найден. Переменная кэша <PackageName>_DIR устанавливается в местоположение файла конфигурации пакета.

Пакеты с модулями поиска

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

В отличие от случая с предоставляемым предком файлом конфигурации пакета, ни одна точка отсчета не идентифицирует пакет как найденный, поэтому переменная <PackageName>_FOUND не устанавливается автоматически командой find_package(). Однако можно ожидать, что она будет установлена по умолчанию, и это должна сделать автор модуля поиска. Аналогично, нет переменной <PackageName>_DIR, но каждый артефакт, например расположения библиотек и заголовочных файлов, обеспечивает отдельную переменную кэша.

См. руководство cmake-developer(7) для получения дополнительной информации о создании файлов модулей поиска.

Структура пакета

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

Файл конфигурации пакета

Представьте себе проект Foo, который устанавливает следующие файлы:

<prefix>/include/foo-1.2/foo.h
<prefix>/lib/foo-1.2/libfoo.a

Он также может предоставить файл конфигурации пакета CMake:

<prefix>/lib/cmake/foo-1.2/FooConfig.cmake

содержащий определение IMPORTED целей или определение переменных, таких как:

# ...
# (compute PREFIX relative to file location)
# ...
set(Foo_INCLUDE_DIRS ${PREFIX}/include/foo-1.2)
set(Foo_LIBRARIES ${PREFIX}/lib/foo-1.2/libfoo.a)

Если другой проект хочет использовать Foo, ему достаточно найти файл FooConfig.cmake и загрузить его, чтобы получить всю необходимую информацию о местоположении содержимого пакета. Так как файл конфигурации пакета предоставляется установкой пакета, он уже знает все местоположения файлов.

Команда find_package() может быть использована для поиска файла конфигурации пакета. Эта команда строит набор префиксов установки и ищет под каждым префиксом в нескольких местах. Учитывая имя Foo, она ищет файл, называемый FooConfig.cmake или foo-config.cmake. Полный набор местоположений указан в документации к команде find_package(). Одно место, где она ищет, это:

<prefix>/lib/cmake/Foo*/

где Foo* — выражение поиска с игнорированием регистра. В нашем примере выражение поиска сопоставит <prefix>/lib/cmake/foo-1.2 и файл конфигурации пакета будет найден.

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

Файл версии пакета

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

Имя файла версии пакета должно совпадать с именем файла конфигурации пакета, но к нему добавлено либо -version или Version перед расширением .cmake. Например, файлы:

<prefix>/lib/cmake/foo-1.3/foo-config.cmake
<prefix>/lib/cmake/foo-1.3/foo-config-version.cmake

и:

<prefix>/lib/cmake/bar-4.2/BarConfig.cmake
<prefix>/lib/cmake/bar-4.2/BarConfigVersion.cmake

являются парами файлов конфигурации пакета и соответствующих файлов версии пакета.

Когда команда find_package() загружает файл версии, она сначала устанавливает следующие переменные:

PACKAGE_FIND_NAME

<PackageName>

PACKAGE_FIND_VERSION

Полная строка запрошенной версии

PACKAGE_FIND_VERSION_MAJOR

Основная версия, если запрошена, иначе 0

PACKAGE_FIND_VERSION_MINOR

Вспомогательная версия, если запрошена, иначе 0

PACKAGE_FIND_VERSION_PATCH

Версия исправления, если запрошена, иначе 0

PACKAGE_FIND_VERSION_TWEAK

Версия доработки, если запрошена, иначе 0

PACKAGE_FIND_VERSION_COUNT

Количество компонентов версии, от 0 до 4

Файл версии должен использовать эти переменные для проверки совместимости или точного соответствия запрошенной версии и установить следующие переменные с результатами:

PACKAGE_VERSION

Полная строка предоставленной версии

PACKAGE_VERSION_EXACT

True, если версия — точное соответствие

PACKAGE_VERSION_COMPATIBLE

True, если версия совместима

PACKAGE_VERSION_UNSUITABLE

True, если версия непригодна

Файлы версий загружаются в вложенном пространстве имен, поэтому они могут свободно устанавливать любые переменные, которые им нужны в рамках их вычислений. Команда find_package очищает пространство имен, когда файл версии завершен и проверены переменные вывода. Когда файл версии утверждает, что является приемлемым соответствием для запрошенной версии, команда find_package устанавливает следующие переменные для использования проектом:

<PackageName>_VERSION

Полная предоставленная строка версии

<PackageName>_VERSION_MAJOR

Главная версия, если указана, иначе 0

<PackageName>_VERSION_MINOR

Вспомогательная версия, если указана, иначе 0

<PackageName>_VERSION_PATCH

Версия исправления, если указана, иначе 0

<PackageName>_VERSION_TWEAK

Версия доработки, если указана, иначе 0

<PackageName>_VERSION_COUNT

Количество компонентов версии, от 0 до 4

Переменные сообщают о версии пакета, который фактически был найден. Часть их имени <PackageName> соответствует аргументу, заданному команде find_package().

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

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

project(UpstreamLib)

set(CMAKE_INCLUDE_CURRENT_DIR ON)
set(CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE ON)

set(Upstream_VERSION 3.4.1)

include(GenerateExportHeader)

add_library(ClimbingStats SHARED climbingstats.cpp)
generate_export_header(ClimbingStats)
set_property(TARGET ClimbingStats PROPERTY VERSION ${Upstream_VERSION})
set_property(TARGET ClimbingStats PROPERTY SOVERSION 3)
set_property(TARGET ClimbingStats PROPERTY
  INTERFACE_ClimbingStats_MAJOR_VERSION 3)
set_property(TARGET ClimbingStats APPEND PROPERTY
  COMPATIBLE_INTERFACE_STRING ClimbingStats_MAJOR_VERSION
)

install(TARGETS ClimbingStats EXPORT ClimbingStatsTargets
  LIBRARY DESTINATION lib
  ARCHIVE DESTINATION lib
  RUNTIME DESTINATION bin
  INCLUDES DESTINATION include
)
install(
  FILES
    climbingstats.h
    "${CMAKE_CURRENT_BINARY_DIR}/climbingstats_export.h"
  DESTINATION
    include
  COMPONENT
    Devel
)

include(CMakePackageConfigHelpers)
write_basic_package_version_file(
  "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsConfigVersion.cmake"
  VERSION ${Upstream_VERSION}
  COMPATIBILITY AnyNewerVersion
)

export(EXPORT ClimbingStatsTargets
  FILE "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsTargets.cmake"
  NAMESPACE Upstream::
)
configure_file(cmake/ClimbingStatsConfig.cmake
  "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsConfig.cmake"
  COPYONLY
)

set(ConfigPackageLocation lib/cmake/ClimbingStats)
install(EXPORT ClimbingStatsTargets
  FILE
    ClimbingStatsTargets.cmake
  NAMESPACE
    Upstream::
  DESTINATION
    ${ConfigPackageLocation}
)
install(
  FILES
    cmake/ClimbingStatsConfig.cmake
    "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsConfigVersion.cmake"
  DESTINATION
    ${ConfigPackageLocation}
  COMPONENT
    Devel
)

Модуль CMakePackageConfigHelpers предоставляет макрос для создания простого файла ConfigVersion.cmake. Этот файл устанавливает версию пакета. Он читается CMake при вызове find_package() для определения совместимости с запрошенной версией и для установки некоторых зависящих от версии переменных <PackageName>_VERSION, <PackageName>_VERSION_MAJOR, <PackageName>_VERSION_MINOR и т. д. Команда install(EXPORT) используется для экспорта целевых задач в наборе экспорта ClimbingStatsTargets, определенном ранее командой install(TARGETS). Эта команда генерирует файл ClimbingStatsTargets.cmake для хранения целевых задач IMPORTED, подходящих для использования downstream, и организует его установку в lib/cmake/ClimbingStats. Сгенерированные файлы ClimbingStatsConfigVersion.cmake и cmake/ClimbingStatsConfig.cmake устанавливаются в том же месте, завершая создание пакета.

Сгенерированные целевые задачи IMPORTED имеют соответствующие свойства, определяющие их требования к использованию, такие как INTERFACE_INCLUDE_DIRECTORIES, INTERFACE_COMPILE_DEFINITIONS и другие релевантные встроенные свойства INTERFACE_. Вариант INTERFACE пользовательских свойств, перечисленных в COMPATIBLE_INTERFACE_STRING и другие Свойства совместимого интерфейса, также передаются сгенерированным целевым задачам IMPORTED. В приведенном выше случае ClimbingStats_MAJOR_VERSION определен как строка, которая должна быть совместима между зависимостями любого зависимого элемента. Установив это пользовательское свойство в этой версии и в следующей версии ClimbingStats, cmake(1) выдаст диагностическое сообщение, если будет попытка использования версии 3 вместе с версией 4. Пакеты могут выбрать использование такой модели, если разные главные версии пакета предназначены для несовместимости.

Двойные двоеточия NAMESPACE указываются при экспорте целевых задач для установки. Эта конвенция двойных двоеточий подсказывает CMake, что имя является целевой задачей IMPORTED, когда оно используется downstream с командой target_link_libraries(). Таким образом, CMake может выдать диагностическое сообщение, если пакет, предоставляющий его, еще не найден.

В этом случае при использовании install(TARGETS) был указан INCLUDES DESTINATION. Это приводит к тому, что целевые задачи IMPORTED имеют свои INTERFACE_INCLUDE_DIRECTORIES заполненные каталогом include в CMAKE_INSTALL_PREFIX. Когда целевая задача IMPORTED используется downstream, она автоматически использует записи из этого свойства.

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

В этом случае файл ClimbingStatsConfig.cmake может быть таким простым:

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

Поскольку это позволяет downstream использовать целевые задачи IMPORTED. Если пакет ClimbingStats должен предоставлять какие-либо макросы, они должны быть в отдельном файле, который устанавливается в том же месте, что и файл ClimbingStatsConfig.cmake, и включаться оттуда.

Это также можно расширить, чтобы охватить зависимости:

# ...
add_library(ClimbingStats SHARED climbingstats.cpp)
generate_export_header(ClimbingStats)

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

Поскольку целевая задача Stats::Types является зависимостью PUBLIC от ClimbingStats, downstream также должен найти пакет Stats и связать его с библиотекой Stats::Types. Пакет Stats должен быть найден в файле ClimbingStatsConfig.cmake для обеспечения этого. Макрос find_dependency из модуля CMakeFindDependencyMacro помогает в этом, распространяя, является ли пакет REQUIRED, или QUIET и т. д. Все зависимости REQUIRED пакета должны быть найдены в файле Config.cmake.

include(CMakeFindDependencyMacro)
find_dependency(Stats 2.6.4)

include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")
include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsMacros.cmake")

Макрос find_dependency также устанавливает ClimbingStats_FOUND в False если зависимость не найдена, а также выводит диагностическое сообщение, что пакет ClimbingStats не может быть использован без пакета Stats.

Если COMPONENTS указаны, когда downstream использует find_package(), они перечислены в переменной <PackageName>_FIND_COMPONENTS. Если конкретный компонент является необязательным, то <PackageName>_FIND_REQUIRED_<comp> будет истинным. Это можно проверить логикой в файле конфигурации пакета:

include(CMakeFindDependencyMacro)
find_dependency(Stats 2.6.4)

include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")
include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsMacros.cmake")

set(_supported_components Plot Table)

foreach(_comp ${ClimbingStats_FIND_COMPONENTS})
  if (NOT ";${_supported_components};" MATCHES _comp)
    set(ClimbingStats_FOUND False)
    set(ClimbingStats_NOT_FOUND_MESSAGE "Unsupported component: ${_comp}")
  endif()
  include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStats${_comp}Targets.cmake")
endforeach()

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

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

Команда export(EXPORT) создает файл определения целевых задач IMPORTED, специфичный для дерева сборки и непереносимый. Аналогично, это можно использовать с соответствующим файлом конфигурации пакета и файлом версии пакета для определения пакета для дерева сборки, который может быть использован без установки. Потребители дерева сборки могут просто убедиться, что CMAKE_PREFIX_PATH содержит каталог сборки или установить ClimbingStats_DIR в <build_dir>/ClimbingStats в кэше.

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

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

Пакеты, созданные с помощью install(EXPORT), разработаны для переносимости, используя пути, относительные к расположению самого пакета. При определении интерфейса целевой задачи для EXPORT, имейте в виду, что каталоги включаемых файлов должны быть указаны как относительные пути, которые являются относительными к 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:$<$<CONFIG:Debug>:$<INSTALL_PREFIX>/include/TgtName>>
)

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

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

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

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

target_link_libraries(ClimbingStats INTERFACE Foo::Foo Bar::Bar)

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

К сожалению, многие modules, поставляемые с CMake, пока не предоставляют IMPORTED цели, так как их разработка предшествовала этому подходу. Это может улучшаться постепенно со временем. Временные решения для создания переносимых пакетов, используя такие модули, включают:

• При построении пакета укажите каждую запись кэша Foo_LIBRARY как просто имя библиотеки, например -DFoo_LIBRARY=foo. Это сообщает соответствующему модулю поиска заполнить Foo_LIBRARIES только foo, чтобы попросить компоновщик найти библиотеку, вместо жёсткой привязки пути.
• Или, после установки содержимого пакета, но перед созданием двоичного файла установки пакета для распространения, вручную замените абсолютные пути на заглушки для подстановки инструментом установки при установке пакета.

Регистр пакетов

CMake предоставляет два центральных места для регистрации пакетов, которые были построены или установлены где-либо в системе:

• Регистр пользовательских пакетов
• Регистр системных пакетов

Регистры особенно полезны для помощи проектам в поиске пакетов в нестандартных местах установки или непосредственно в своих собственных дереве сборки. Проект может заполнить либо пользовательский, либо системный регистр (используя свои собственные средства, см. ниже), чтобы сослаться на своё расположение. В любом случае пакет должен хранить в зарегистрированном месте файл конфигурации пакета (Файл конфигурации пакета) (<PackageName>Config.cmake) и, необязательно, файл версии пакета (Файл версии пакета) (<PackageName>ConfigVersion.cmake).

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

Регистр пользовательских пакетов

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

В Windows регистр пользовательских пакетов хранится в реестре Windows в ключе HKEY_CURRENT_USER.

<PackageName> может появиться в ключе реестра:

HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\<PackageName>

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

В платформах UNIX регистр пользовательских пакетов хранится в домашнем каталоге пользователя в ~/.cmake/packages. <PackageName> может появиться в каталоге:

~/.cmake/packages/<PackageName>

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

Регистр системных пакетов

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

В Windows регистр системных пакетов хранится в реестре Windows в ключе HKEY_LOCAL_MACHINE . <PackageName> может появиться в ключе реестра:

HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<PackageName>

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

В не-Windows платформах регистра системных пакетов нет.

Отключение регистра пакетов

В некоторых случаях использование регистров пакетов нежелательно. CMake позволяет отключить их с помощью следующих переменных:

• Команда export(PACKAGE) не заполняет регистр пользовательских пакетов, когда CMP0090 установлена в NEW, если переменная CMAKE_EXPORT_PACKAGE_REGISTRY явно не включает её. Когда CMP0090 не установлена в NEW, тогда export(PACKAGE) заполняет регистр пользовательских пакетов, если переменная CMAKE_EXPORT_NO_PACKAGE_REGISTRY явно не отключает её.
• CMAKE_FIND_USE_PACKAGE_REGISTRY отключает Регистр пользовательских пакетов во всех вызовах find_package(), когда установлено значение FALSE.
• Устаревшая переменная CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY отключает Регистр пользовательских пакетов во всех вызовах find_package(), когда установлено значение TRUE. Эта переменная игнорируется, когда CMAKE_FIND_USE_PACKAGE_REGISTRY была установлена.
• CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY отключает регистр системных пакетов во всех вызовах find_package().

Пример регистра пакетов

Простой соглашение об именовании записей регистра пакетов — использовать хэши содержимого. Они детерминированы и вряд ли будут совпадать (export(PACKAGE) использует этот подход). Имя записи, ссылающейся на конкретный каталог, — это просто хэш содержимого самого пути каталога.

Если проект организует существование записей регистра пакетов, таких как:

> reg query HKCU\Software\Kitware\CMake\Packages\MyPackage
HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\MyPackage
 45e7d55f13b87179bb12f907c8de6fc4 REG_SZ c:/Users/Me/Work/lib/cmake/MyPackage
 7b4a9844f681c80ce93190d4e3185db9 REG_SZ c:/Users/Me/Work/MyPackage-build

или:

$ cat ~/.cmake/packages/MyPackage/7d1fb77e07ce59a81bed093bbee945bd
/home/me/work/lib/cmake/MyPackage
$ cat ~/.cmake/packages/MyPackage/f92c1db873a1937f3100706657c63e07
/home/me/work/MyPackage-build

то код %%%CODE_BLOCK_205%%:

find_package(MyPackage)

будет искать в зарегистрированных местоположениях файлы конфигурации пакетов (MyPackageConfig.cmake). Порядок поиска среди записей регистра пакетов для одного пакета не определён, а имена записей (хэши в этом примере) не имеют никакого значения. Зарегистрированные местоположения могут содержать файлы версии пакетов (MyPackageConfigVersion.cmake), чтобы сообщить find_package(), подходит ли конкретное местоположение для запрошенной версии.

Владение регистром пакетов

Записи регистра пакетов индивидуально принадлежат проектам установки, на которые они ссылаются. Установщик пакета отвечает за добавление своей собственной записи, а соответствующий удалитель — за её удаление.

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