find_file

Краткая запись:

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

Общая запись:

find_file (
          <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_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_file с той же переменной.

Доступны следующие опции:

NAMES

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

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

HINTS, PATHS

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

PATH_SUFFIXES

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

DOC

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

Если NO_DEFAULT_PATH указано, дополнительные пути к каталогам не добавляются в поиск. Если NO_DEFAULT_PATH не указано, процесс поиска выполняется следующим образом:

1. Поиск по путям, указанным в переменных кэша CMake. Они предназначены для использования в командной строке с -DVAR=value. Значения интерпретируются как списки с разделителем «;». Это можно пропустить, если передано NO_CMAKE_PATH.
   • <prefix>/include/<arch> если установлена CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/include для каждого <prefix> в CMAKE_PREFIX_PATH
   • CMAKE_INCLUDE_PATH
   • CMAKE_FRAMEWORK_PATH
2. Поиск по путям, указанным в переменных среды 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
3. Поиск по путям, указанным опцией HINTS. Эти пути должны быть получены путём системного анализа, например, указаны в результате поиска другого элемента. Зашитые предположения должны быть указаны опцией PATHS.
4. Поиск по стандартным переменным среды. Это можно пропустить, если NO_SYSTEM_ENVIRONMENT_PATH аргумент.
   • Каталоги в INCLUDE. В системах Windows: <prefix>/include/<arch> если установлена CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/include для каждого <prefix>/[s]bin в PATH, и <entry>/include для других записей в PATH, и каталоги в PATH самом.
5. Поиск переменных 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
6. Поиск путей, указанных в опции PATHS или в сокращённой форме команды. Обычно это жёстко заданные предположения.

В macOS порядок предпочтения между компонентами пакетов в стиле Apple и в стиле Unix определяется переменными CMAKE_FIND_FRAMEWORK и CMAKE_FIND_APPBUNDLE.

Переменная 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_file (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
find_file (<VAR> NAMES name)

После успешного выполнения одного из вызовов переменная результата будет установлена и сохранена в кэше, чтобы избежать повторного поиска при последующих вызовах.