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)

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