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

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

NAMES

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

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

HINTS, PATHS

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

PATH_SUFFIXES

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

DOC

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

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

1. Если вызов осуществляется изнутри модуля поиска или любого другого скрипта, загруженного с помощью вызова 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.

   • Каталоги в PATH и INCLUDE.
   • В 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
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)

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