find_path

Краткая запись:

find_path (<VAR> name1 [path1 path2 ...])

Общая запись:

find_path (
          <VAR>
          name | NAMES name1 [name2 ...]
          [HINTS [path | ENV var]... ]
          [PATHS [path | ENV var]... ]
          [PATH_SUFFIXES suffix1 [suffix2 ...]]
          [DOC "cache documentation string"]
          [NO_CACHE]
          [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]
         )

Эта команда используется для поиска директории, содержащей указанный файл. В кэш, или в обычную переменную, если указано NO_CACHE, с именем <VAR> записывается результат этой команды. Если файл в директории найден, результат записывается в переменную, и поиск не будет повторён, если переменная не очищена. Если ничего не найдено, результатом будет <VAR>-NOTFOUND.

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

NAMES

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

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

HINTS, PATHS

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

PATH_SUFFIXES

Укажите дополнительные поддиректории для проверки в каждой из указанных директорий.

DOC

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

NO_CACHE

Новая функция в версии 3.21.

Результат поиска будет сохранён в обычной переменной, а не в записи кэша.

Примечание

Если переменная уже установлена перед вызовом (как обычная или кэшированная переменная), то поиск не произойдёт.

Предупреждение

Эту опцию следует использовать с осторожностью, так как она может значительно увеличить затраты на повторные этапы конфигурации.

REQUIRED

Новая функция в версии 3.18.

Прекратить выполнение с сообщением об ошибке, если ничего не найдено. В противном случае поиск будет повторён в следующий раз, когда find_path будет вызван с той же переменной.

Если NO_DEFAULT_PATH указано, дополнительные пути к поиску не добавляются. Если NO_DEFAULT_PATH не указано, процесс поиска выполняется следующим образом:

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

   • Директории в INCLUDE и PATH.
   • В системах 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 или в сокращённой версии команды. Обычно это заранее заданные догадки.

Переменные CMAKE_IGNORE_PATH, CMAKE_IGNORE_PREFIX_PATH, CMAKE_SYSTEM_IGNORE_PATH и CMAKE_SYSTEM_IGNORE_PREFIX_PATH также могут привести к игнорированию некоторых из вышеперечисленных расположений.

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