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. Смотрите политику 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.

   • <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_file (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
find_file (<VAR> NAMES name)

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