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_ENVIRONMENT_PATH]
          [NO_CMAKE_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. Они предназначены для установки в конфигурации оболочки пользователя. Этот шаг можно пропустить, если передана 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. Поиск в стандартных переменных среды.
   • Каталоги в INCLUDE, <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)

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