find_path

Краткая форма записи:

find_path (<VAR> <name> [<path>...])

Общая форма записи:

find_path (
          <VAR>
          {<name> | NAMES <name>...}
          [HINTS {<path> | ENV <var>}...]
          [PATHS {<path> | ENV <var>}...]
          [REGISTRY_VIEW {64|32|64_32|32_64|HOST|TARGET|BOTH}]
          [PATH_SUFFIXES <suffix>...]
          [VALIDATOR <function>]
          [DOC "cache documentation string"]
          [NO_CACHE]
          [REQUIRED|OPTIONAL]
          [NO_DEFAULT_PATH]
          [NO_PACKAGE_ROOT_PATH]
          [NO_CMAKE_PATH]
          [NO_CMAKE_ENVIRONMENT_PATH]
          [NO_SYSTEM_ENVIRONMENT_PATH]
          [NO_CMAKE_SYSTEM_PATH]
          [NO_CMAKE_INSTALL_PREFIX]
          [CMAKE_FIND_ROOT_PATH_BOTH |
           ONLY_CMAKE_FIND_ROOT_PATH |
           NO_CMAKE_FIND_ROOT_PATH]
         )

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

Перед поиском find_path проверяет, определена ли переменная <VAR>. Если переменная не определена, поиск выполняется. Если переменная определена и её значение равно NOTFOUND или заканчивается на -NOTFOUND, поиск выполняется. Если переменная содержит любое другое значение, поиск не выполняется.

Результаты поиска сохраняются в записи кэша с именем <VAR>. При последующих вызовах find_path эта запись кэша проверяется, если указано то же значение <VAR>. Эта оптимизация позволяет не повторять успешный поиск, пока запись кэша не будет unset().

Если файл найден в каталоге, в записи кэша <VAR> сохраняется результат поиска. Если файл не найден, сохраняемое значение будет <VAR>-NOTFOUND.

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

NAMES

Указывает одно или несколько возможных имён файла в каталоге.

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

HINTS, PATHS

Указывает каталоги для поиска в дополнение к расположениям по умолчанию. Подпараметр ENV var считывает пути из системной переменной среды.

Изменено в версии 3.24: На платформе Windows в каталоги можно включать запросы к реестру, используя специальный синтаксис. Такие спецификации игнорируются на всех остальных платформах.

REGISTRY_VIEW

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

Указывает, какие представления реестра следует запрашивать. Этот параметр имеет смысл только на платформах Windows и игнорируется на остальных платформах. Если параметр не указан, используется представление TARGET, когда политика CMP0134 установлена в NEW. Сведения о представлении по умолчанию, когда политика установлена в OLD, см. в описании CMP0134.

64

Запрашивает 64-разрядный реестр. В 32-разрядной Windows всегда возвращает строку /REGISTRY-NOTFOUND.

32

Запрашивает 32-разрядный реестр.

64_32

Запрашивает оба представления (64 и 32) и формирует путь для каждого из них.

32_64

Запрашивает оба представления (32 и 64) и формирует путь для каждого из них.

HOST

Запрашивает реестр, соответствующий архитектуре хоста: 64 в 64-разрядной Windows и 32 в 32-разрядной Windows.

TARGET

Запрашивает реестр, соответствующий архитектуре, указанной переменной CMAKE_SIZEOF_VOID_P. Если переменная не определена, используется представление HOST.

BOTH

Запрашивает оба представления (32 и 64). Порядок определяется следующими правилами. Если переменная CMAKE_SIZEOF_VOID_P определена, используется представление, соответствующее значению этой переменной:

• 8: 64_32
• 4: 32_64

Если переменная CMAKE_SIZEOF_VOID_P не определена, используется архитектура хоста:

• 64-разрядная: 64_32
• 32-разрядная: 32

PATH_SUFFIXES

Указывает дополнительные подкаталоги для проверки внутри каждого рассматриваемого каталога.

VALIDATOR

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

Указывает function(), который вызывается для каждого найденного кандидата (указать macro() нельзя: это приведёт к ошибке). Функция-валидатор получает два аргумента: имя переменной результата и абсолютный путь к элементу-кандидату. Элемент будет принят и поиск завершится, если только функция не задаст для переменной результата значение false в вызывающей области видимости. При входе в функцию-валидатор переменная результата содержит значение true.

function(my_check validator_result_var item)
  if(NOT item MATCHES ...)
    set(${validator_result_var} FALSE PARENT_SCOPE)
  endif()
endfunction()

find_path (result NAMES ... VALIDATOR my_check)

Обратите внимание: если используется результат из кэша, поиск пропускается, а любой параметр VALIDATOR игнорируется. Результат из кэша не обязан проходить проверку функции-валидатора.

DOC

Указывает строку документации для записи кэша <VAR>.

NO_CACHE

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

Результат поиска сохраняется в обычной переменной, а не в записи кэша.

Примечание

find_path по-прежнему проверяет <VAR> обычным образом: сначала переменную, а затем запись кэша. Если любой из этих элементов указывает на предыдущий успешный поиск, новый поиск выполняться не будет.

Предупреждение

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

REQUIRED

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

Останавливает обработку и выводит сообщение об ошибке, если ничего не найдено; в противном случае поиск будет предпринят снова при следующем вызове find_path с той же переменной.

Добавлено в версии 4.1: Каждая команда find_path будет рассматриваться как REQUIRED, если включена переменная CMAKE_FIND_REQUIRED.

OPTIONAL

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

Игнорирует значение CMAKE_FIND_REQUIRED и продолжает работу без сообщения об ошибке, если ничего не найдено. Несовместим с REQUIRED.

Если указан параметр NO_DEFAULT_PATH, дополнительные пути для поиска не добавляются. Если параметр NO_DEFAULT_PATH не указан, поиск выполняется следующим образом:

1. Если команда вызвана из модуля поиска или другого скрипта, загруженного вызовом find_package(<PackageName>), поиск выполняется по префиксам, уникальным для текущего искомого пакета. См. политику CMP0074.

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

   В частности, поиск выполняется по путям, заданным следующими переменными, в указанном порядке:

   1. Переменная CMake <PackageName>_ROOT, где <PackageName> — имя пакета с сохранением регистра.

   2. Переменная CMake <PACKAGENAME>_ROOT, где <PACKAGENAME> — имя пакета в верхнем регистре. См. политику CMP0144.

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

   3. Переменная среды <PackageName>_ROOT, где <PackageName> — имя пакета с сохранением регистра.

   4. Переменная среды <PACKAGENAME>_ROOT, где <PACKAGENAME> — имя пакета в верхнем регистре. См. политику CMP0144.

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

   Корневые переменные пакета хранятся в стеке, поэтому при вызове из вложенных модулей поиска или пакетов конфигурации корневые пути родительского модуля поиска или пакета конфигурации проверяются после путей текущего модуля или пакета. Иными словами, порядок поиска будет таким: <CurrentPackage>_ROOT, ENV{<CurrentPackage>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT} и т. д. Этот этап можно пропустить, передав NO_PACKAGE_ROOT_PATH или установив переменную CMAKE_FIND_USE_PACKAGE_ROOT_PATH в FALSE.

   • <prefix>/include/<arch>, если задана CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/include для каждого <prefix> в переменной CMake <PackageName>_ROOT и переменной среды <PackageName>_ROOT, если вызов выполняется из модуля поиска, загруженного командой find_package(<PackageName>)

2. Пути, указанные в переменных кэша, специфичных для CMake. Предполагается, что они задаются в командной строке с помощью -DVAR=value. Значения интерпретируются как списки, разделённые точками с запятой. Этот этап можно пропустить, передав NO_CMAKE_PATH или установив переменную CMAKE_FIND_USE_CMAKE_PATH в FALSE.

   • <prefix>/include/<arch>, если задана CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/include для каждого <prefix> в CMAKE_PREFIX_PATH
   • CMAKE_INCLUDE_PATH
   • CMAKE_FRAMEWORK_PATH

3. Пути, указанные в переменных среды, специфичных для CMake. Предполагается, что они задаются в конфигурации оболочки пользователя, поэтому в них используется собственный для хоста разделитель путей (; в Windows и : в UNIX). Этот этап можно пропустить, передав NO_CMAKE_ENVIRONMENT_PATH или установив переменную CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH в FALSE.

   • <prefix>/include/<arch>, если задана CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/include для каждого <prefix> в CMAKE_PREFIX_PATH
   • CMAKE_INCLUDE_PATH
   • CMAKE_FRAMEWORK_PATH
4. Пути, указанные параметром HINTS. Это должны быть пути, вычисленные на основе сведений о системе, например подсказка, полученная из расположения другого уже найденного элемента. Жёстко заданные предположительные пути следует указывать параметром PATHS.

5. Стандартные системные переменные среды. Этот этап можно пропустить, передав NO_SYSTEM_ENVIRONMENT_PATH или установив переменную CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH в FALSE.

   • Каталоги из INCLUDE и PATH.

   На хостах Windows версии CMake с 3.3 по 3.27 выполняли поиск также в дополнительных путях: <prefix>/include/<arch>, если задана CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/include для каждого <prefix>/[s]bin в PATH, а также <entry>/include для остальных записей в PATH. Это поведение удалено в CMake 3.28.

6. Переменные CMake, определённые в файлах Platform для текущей системы. Поиск по CMAKE_INSTALL_PREFIX и CMAKE_STAGING_PREFIX можно пропустить, передав NO_CMAKE_INSTALL_PREFIX или установив переменную CMAKE_FIND_USE_INSTALL_PREFIX в FALSE. Все эти расположения можно пропустить, передав NO_CMAKE_SYSTEM_PATH или установив переменную CMAKE_FIND_USE_CMAKE_SYSTEM_PATH в FALSE.

   • <prefix>/include/<arch>, если задана CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/include для каждого <prefix> в CMAKE_SYSTEM_PREFIX_PATH
   • CMAKE_SYSTEM_INCLUDE_PATH
   • CMAKE_SYSTEM_FRAMEWORK_PATH

   Пути платформы, содержащиеся в этих переменных, указывают на расположения, где обычно установлено программное обеспечение. Например, /usr/local для платформ на базе UNIX.

7. Пути, указанные параметром PATHS или в краткой форме команды. Обычно это жёстко заданные предположительные пути.

Переменные CMAKE_IGNORE_PATH, CMAKE_IGNORE_PREFIX_PATH, CMAKE_SYSTEM_IGNORE_PATH и CMAKE_SYSTEM_IGNORE_PREFIX_PATH также могут приводить к исключению некоторых из перечисленных выше расположений из поиска.

В macOS переменные CMAKE_FIND_FRAMEWORK и CMAKE_FIND_APPBUNDLE определяют порядок предпочтения между компонентами пакета в стиле Apple и в стиле Unix.

Переменная CMake CMAKE_FIND_ROOT_PATH задаёт один или несколько каталогов, добавляемых в начало всех остальных каталогов поиска. Это фактически «переносит корень» всего поиска в указанные расположения. Пути, являющиеся потомками CMAKE_STAGING_PREFIX, исключаются из этого переноса корня, поскольку эта переменная всегда указывает путь в системе хоста. По умолчанию переменная CMAKE_FIND_ROOT_PATH пуста.

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

Эти переменные особенно полезны при кросс-компиляции: они позволяют указать корневой каталог целевого окружения, где CMake также будет выполнять поиск. По умолчанию сначала выполняется поиск в каталогах, перечисленных в CMAKE_FIND_ROOT_PATH, затем в каталоге CMAKE_SYSROOT, а после этого — в каталогах без переноса корня. Поведение по умолчанию можно изменить, задав CMAKE_FIND_ROOT_PATH_MODE_INCLUDE. Это поведение можно вручную переопределить для отдельного вызова с помощью параметров:

CMAKE_FIND_ROOT_PATH_BOTH

Выполняет поиск в описанном выше порядке.

NO_CMAKE_FIND_ROOT_PATH

Не использует переменную CMAKE_FIND_ROOT_PATH.

ONLY_CMAKE_FIND_ROOT_PATH

Выполняет поиск только в каталогах с перенесённым корнем и каталогах внутри CMAKE_STAGING_PREFIX.

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

find_path (<VAR> NAMES name PATHS <paths>... NO_DEFAULT_PATH)
find_path (<VAR> NAMES name)

Как только один из вызовов завершится успешно, переменной результата будет присвоено найденное значение, которое сохранится в кэше, поэтому повторный поиск выполняться не будет.

При поиске во фреймворках, если файл указан как A/b.h, поиск во фреймворках будет искать A.framework/Headers/b.h. Если он найден, в качестве пути будет задан путь к фреймворку. CMake преобразует его в правильный параметр -F для включения файла.