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. См. политику 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.
   • <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 параметр для включения файла.