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"]
          [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]
         )

Эта команда используется для поиска каталога, содержащего указанный файл. В кэш помещается запись, обозначенная <VAR>, для хранения результата этой команды. Если файл в каталоге найден, результат сохраняется в переменной, и поиск не будет повторяться, если переменная не очищена. Если ничего не найдено, результат будет <VAR>-NOTFOUND.

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

NAMES

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

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

HINTS, PATHS

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

PATH_SUFFIXES

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

DOC

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

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