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. Проверяются стандартные переменные среды.

   • Каталоги в 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 опцию для включения файла.