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 или в сокращенной версии команды. Как правило, это жёстко закодированные предположения.

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