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_ENVIRONMENT_PATH]
          [NO_CMAKE_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 переменных среды. Они предназначены для настройки в конфигурации командной оболочки пользователя. Это можно пропустить, если 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 для включения файла.