find_path

Краткая форма записи:

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

Общая форма записи:

find_path (
          <VAR>
          name | NAMES name1 [name2 ...]
          [HINTS [path | ENV var]... ]
          [PATHS [path | ENV var]... ]
          [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
          [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]
          [NO_CMAKE_INSTALL_PREFIX]
          [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 считывает пути из системной переменной окружения.

Изменено в версии 3.24: На платформе Windows возможно включить запросы к реестру в качестве части директорий, используя специальный синтаксис. Такие указания будут игнорироваться на всех остальных платформах.

REGISTRY_VIEW

Новое в версии 3.24.

Укажите, какие представления реестра должны быть запрошены. Этот параметр имеет смысл только на платформах Windows и будет игнорироваться на других. При отсутствии указаний используется представление TARGET при политике CMP0134 NEW. Обратитесь к CMP0134 для получения значения по умолчанию при политике OLD.

64

Запрос к 64-битному реестру. На 32-битных Windows всегда возвращает строку /REGISTRY-NOTFOUND.

32

Запрос к 32-битному реестру.

64_32

Запрос обоих представлений (64 и 32) и генерация пути для каждого.

32_64

Запрос обоих представлений (32 и 64) и генерация пути для каждого.

HOST

Запрос к реестру, соответствующему архитектуре хоста: 64 на 64-битных Windows и 32 на 32-битных Windows.

TARGET

Запрос к реестру, соответствующему архитектуре, указанной переменной CMAKE_SIZEOF_VOID_P. Если не определена, используется представление HOST.

BOTH

Запрос обоих представлений (32 и 64). Порядок зависит от следующих правил: если переменная CMAKE_SIZEOF_VOID_P определена, используется следующее представление в зависимости от её значения:

• 8: 64_32
• 4: 32_64

Если переменная CMAKE_SIZEOF_VOID_P не определена, используется архитектура хоста:

• 64-бит: 64_32
• 32-бит: 32

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, определённые в файлах платформы для текущей системы. Поиск CMAKE_INSTALL_PREFIX и CMAKE_STAGING_PREFIX можно пропустить, если передано NO_CMAKE_INSTALL_PREFIX или установив CMAKE_FIND_USE_INSTALL_PREFIX в значение FALSE. Все эти местоположения можно пропустить, если передано 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 для включения файла.