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, загруженного с помощью find_package(<PackageName>), ищутся префиксы, уникальные для текущего ищущегося пакета. В частности, просматривается переменная CMake <PackageName>_ROOT и переменная окружения <PackageName>_ROOT. Переменные корня пакета поддерживаются как стек, поэтому при вызове из вложенных модулей find корневые пути из модуля find родительского модуля будут проверяться после путей текущего модуля, т.е. <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, загруженного с помощью 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)

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