find_path

Краткая подпись:

find_path (<VAR> name1 [path1 path2 ...])

Общая подпись:

find_path (
          <VAR>
          name | NAMES name1 [name2 ...]
          [HINTS path1 [path2 ... ENV var]]
          [PATHS path1 [path2 ... ENV var]]
          [PATH_SUFFIXES suffix1 [suffix2 ...]]
          [DOC "cache documentation string"]
          [NO_DEFAULT_PATH]
          [NO_PACKAGE_ROOT_PATH]
          [NO_CMAKE_PATH]
          [NO_CMAKE_ENVIRONMENT_PATH]
          [NO_SYSTEM_ENVIRONMENT_PATH]
          [NO_CMAKE_SYSTEM_PATH]
          [CMAKE_FIND_ROOT_PATH_BOTH |
           ONLY_CMAKE_FIND_ROOT_PATH |
           NO_CMAKE_FIND_ROOT_PATH]
         )

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

Доступные опции:

NAMES

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

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

HINTS, PATHS

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

PATH_SUFFIXES

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

DOC

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

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

1. Если вызов происходит внутри модуля find, загруженного с помощью find_package(<PackageName>), поиск префиксов уникальных для текущего находимого пакета. Конкретно, поиск в переменной CMake <PackageName>_ROOT и переменной среды <PackageName>_ROOT. Переменные корня пакета хранятся как стек, поэтому, если вызов происходит из вложенных модулей find, пути корня из модуля find родительского модуля будут проверяться после путей из текущего модуля, т.е. <CurrentPackage>_ROOT, ENV{<CurrentPackage>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, и т.д. Это можно пропустить, если передано NO_PACKAGE_ROOT_PATH. См. политику CMP0074.

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

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

   • <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.

   • <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 является аргументом.

   • Директории в INCLUDE. В Windows: <prefix>/include/<arch> если установлена CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/include для каждого <prefix>/[s]bin в PATH, и <entry>/include для других записей в PATH, и директории в PATH сами по себе.

6. Проверяются переменные CMake, определённые в файлах платформы для текущей системы. Это можно пропустить, если передано NO_CMAKE_SYSTEM_PATH.

   • <prefix>/include/<arch> если установлена CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/include для каждого <prefix> в CMAKE_SYSTEM_PREFIX_PATH
   • CMAKE_SYSTEM_INCLUDE_PATH
   • CMAKE_SYSTEM_FRAMEWORK_PATH
7. Проверяются пути, указанные в опции PATHS или в короткой версии команды. Это, как правило, жёстко заданные предположения.

В 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 для включения файла.