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"]
          [REQUIRED]
          [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. Опция REQUIRED останавливает обработку с сообщением об ошибке, если ничего не найдено, в противном случае поиск будет повторен при следующем вызове find_path с той же переменной.

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

NAMES

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

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

HINTS, PATHS

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

PATH_SUFFIXES

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

DOC

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

REQUIRED

Остановите обработку с сообщением об ошибке, если ничего не найдено.

Если 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

   Пути платформы, содержащиеся в этих переменных, представляют собой местоположения, которые обычно содержат установленное программное обеспечение. Например, /usr/local для платформ на базе UNIX.

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