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)

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