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_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. Поиск путей, указанных в переменных кэша CMake. Они предназначены для использования в командной строке с -DVAR=value. Значения интерпретируются как ;-списки. Это можно пропустить, если передано NO_CMAKE_PATH.
   • <prefix>/include/<arch> если установлено CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/include для каждого <prefix> в CMAKE_PREFIX_PATH
   • CMAKE_INCLUDE_PATH
   • CMAKE_FRAMEWORK_PATH
2. Поиск путей, указанных в переменных окружения 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
3. Поиск путей, указанных опцией HINTS. Они должны быть путями, вычисленными с помощью системного анализа, например, подсказка, полученная из расположения другого уже найденного элемента. Запрограммированные догадки должны быть указаны с помощью опции PATHS.
4. Поиск стандартных системных переменных окружения. Это можно пропустить, если NO_SYSTEM_ENVIRONMENT_PATH является аргументом.
   • Директории в INCLUDE. В Windows: <prefix>/include/<arch> если установлено CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/include для каждого <prefix>/[s]bin в PATH, и <entry>/include для других записей в PATH, и директории в PATH.
5. Поиск переменных 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
6. Поиск путей, указанных опцией PATHS или в короткой версии команды. Как правило, это запрограммированные догадки.

В OS X переменные 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 для включения файла.