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_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. Поиск путей, указанных в переменных кэша, специфичных для CMake. Они предназначены для использования в командной строке с -DVAR=value. Значения интерпретируются как ;-списки. Это можно пропустить, если передано NO_CMAKE_PATH.
   • <prefix>/include/<arch> если CMAKE_LIBRARY_ARCHITECTURE установлена, и <prefix>/include для каждого <prefix> в CMAKE_PREFIX_PATH
   • CMAKE_INCLUDE_PATH
   • CMAKE_FRAMEWORK_PATH
2. Поиск путей, указанных в переменных среды, специфичных для 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
3. Поиск путей, указанных в опции HINTS. Эти пути должны быть вычислены с помощью системного анализа, например, подсказка, предоставленная расположением другого уже найденного элемента. Жестко закодированные предположения должны быть указаны в опции PATHS.
4. Поиск стандартных переменных среды системы. Это можно пропустить, если NO_SYSTEM_ENVIRONMENT_PATH является аргументом.
   • Каталоги в INCLUDE. На хостах Windows: <prefix>/include/<arch> если CMAKE_LIBRARY_ARCHITECTURE установлена, и <prefix>/include для каждого <prefix>/[s]bin в PATH, и <entry>/include для других записей в PATH, и каталоги в PATH самом.
5. Поиск переменных 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
6. Поиск путей, указанных в опции PATHS или в сокращенной версии команды. Как правило, это жестко закодированные догадки.

В OS X переменные 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)

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