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_package(<PackageName>), выполняется поиск префиксов, уникальных для текущего искомого пакета. В частности, проверяется переменная CMake <PackageName>_ROOT и переменная среды <PackageName>_ROOT. Переменные корня пакета сохраняются как стек, поэтому если вызов осуществляется из вложенных модулей поиска, пути корня из родительского модуля поиска будут проверяться после путей текущего модуля, т.е. <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_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 или в сокращённой версии команды. Обычно это жёстко закодированные предположения.

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