find_file

Краткая форма записи:

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

Общая форма записи:

find_file (
          <VAR>
          name | NAMES name1 [name2 ...]
          [HINTS [path | ENV var]... ]
          [PATHS [path | ENV var]... ]
          [PATH_SUFFIXES suffix1 [suffix2 ...]]
          [DOC "cache documentation string"]
          [NO_CACHE]
          [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]
         )

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

Опции включают:

NAMES

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

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

HINTS, PATHS

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

PATH_SUFFIXES

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

DOC

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

NO_CACHE

Новое в версии 3.21.

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

Примечание

Если переменная уже установлена перед вызовом (как обычная или кэш-переменная), поиск не произойдёт.

Предупреждение

Эту опцию следует использовать с осторожностью, так как она может значительно увеличить затраты при повторных шагах конфигурации.

REQUIRED

Новое в версии 3.18.

Остановить обработку с сообщением об ошибке, если ничего не найдено. В противном случае поиск будет повторён в следующий раз, когда find_file вызывается с той же переменной.

Если 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_file (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
find_file (<VAR> NAMES name)

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