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 или установив CMAKE_FIND_USE_PACKAGE_ROOT_PATH в значение FALSE. Смотрите политику 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 или установив 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.

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

6. Искать переменные cmake, определённые в файлах платформы для текущей системы. Это можно пропустить, если передать 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
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 для включения файла.