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_package(<PackageName>), ищутся префиксы каталогов, уникальные для текущего ищущегося пакета. В частности, ищутся в переменной CMake <PackageName>_ROOT и переменной среды <PackageName>_ROOT. Переменные корня пакета поддерживаются как стек, поэтому при вызове из вложенных модулей поиска корневые пути из родительского модуля поиска будут проверяться после путей из текущего модуля, т.е. <CurrentPackage>_ROOT, ENV{<CurrentPackage>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, и т.д. Это можно пропустить, если передать NO_PACKAGE_ROOT_PATH. См. политику 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.

   • <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.

   • <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 является аргументом.

   • Каталоги в INCLUDE. В Windows: <prefix>/include/<arch> если установлена CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/include для каждого <prefix>/[s]bin в PATH, и <entry>/include для других записей в PATH, и каталоги в PATH самих.

6. Проверяются переменные CMake, определённые в файлах платформы для текущей системы. Это можно пропустить, если передать NO_CMAKE_SYSTEM_PATH.

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