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

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

NAMES

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

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

HINTS, PATHS

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

PATH_SUFFIXES

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

DOC

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

Если 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
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 параметр, чтобы включить файл.