Spec-Zone.ru › CMake 3.31

find_file

Краткая форма записи:

find_file (<VAR> name1 [path1 path2 ...])

Общая форма записи:

find_file (
          <VAR>
          name | NAMES name1 [name2 ...]
          [HINTS [path | ENV var]... ]
          [PATHS [path | ENV var]... ]
          [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
          [PATH_SUFFIXES suffix1 [suffix2 ...]]
          [VALIDATOR function]
          [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]
          [NO_CMAKE_INSTALL_PREFIX]
          [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 считывает пути из системной переменной окружения.

Изменено в версии 3.24: В среде Windows возможно включить запросы к реестру в качестве части каталогов, используя специальный синтаксис специальный синтаксис. Такие указания будут проигнорированы во всех остальных средах.

REGISTRY_VIEW

Добавлена в версии 3.24.

Укажите, какие представления реестра необходимо запросить. Эта опция имеет смысл только в средах Windows и будет проигнорирована в других. Если не указано, используется представление TARGET , когда политика CMP0134 установлена в NEW. Обратитесь к CMP0134 за сведениями о стандартном представлении, когда политика установлена в OLD.

64

Запрос 64-разрядного реестра. В 32-разрядных системах Windows всегда возвращает строку /REGISTRY-NOTFOUND.

32

Запрос 32-разрядного реестра.

64_32

Запрос обоих представлений (64 и 32) и создание пути для каждого.

32_64

Запрос обоих представлений (32 и 64) и создание пути для каждого.

HOST

Запрос реестра, соответствующего архитектуре хоста: 64 в 64-разрядных системах Windows и 32 в 32-разрядных системах Windows.

TARGET

Запрос реестра, соответствующего архитектуре, заданной переменной CMAKE_SIZEOF_VOID_P. Если не определена, использует представление HOST.

BOTH

Запрос обоих представлений (32 и 64). Порядок зависит от следующих правил: если переменная CMAKE_SIZEOF_VOID_P определена, используйте следующее представление, в зависимости от значения этой переменной:

  • 8: 64_32
  • 4: 32_64

Если переменная CMAKE_SIZEOF_VOID_P не определена, используйте архитектуру хоста:

  • 64-разрядная: 64_32
  • 32-разрядная: 32
PATH_SUFFIXES

Укажите дополнительные подкаталоги для проверки под каждым каталогом, который в противном случае рассматривается.

VALIDATOR

Добавлена в версии 3.25.

Укажите function() для вызова для каждого найденного кандидата (нельзя указать macro(), это приведёт к ошибке). В функцию-валидатор будут переданы два аргумента: имя переменной результата и абсолютный путь к кандидату. Элемент будет принят, и поиск завершится, если функция в области вызова установит значение в переменной результата в ложь. Переменная результата будет содержать истинное значение при входе в функцию-валидатор.

function(my_check validator_result_var item)
  if(NOT item MATCHES ...)
    set(${validator_result_var} FALSE PARENT_SCOPE)
  endif()
endfunction()

find_file (result NAMES ... VALIDATOR my_check)

Обратите внимание, что если используется кэшированный результат, поиск пропускается, и любые VALIDATOR игнорируются. Кэшированный результат не обязан проходить функцию-валидатор.

DOC

Укажите строку документации для записи кэша <VAR>.

NO_CACHE

Добавлена в версии 3.21.

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

Примечание

Если переменная уже установлена до вызова (как обычная или кэш-переменная), поиск не выполняется.

Предупреждение

Эта опция должна использоваться с осторожностью, так как она может значительно увеличить затраты при повторных шагах конфигурации.

REQUIRED

Добавлена в версии 3.18.

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

Если NO_DEFAULT_PATH указан, дополнительные пути к поиску не добавляются. Если NO_DEFAULT_PATH не указан, процесс поиска происходит следующим образом:

  1. Если вызывается из модуля поиска или любого другого скрипта, загруженного с помощью вызова find_package(<PackageName>), ищутся префиксы поиска, уникальные для текущего ищущегося пакета. См. политику CMP0074.

    Добавлена в версии 3.12.

    В частности, ищутся пути, заданные следующими переменными, в порядке:

    1. <PackageName>_ROOT Переменная CMake, где <PackageName> — это имя пакета, сохраняющее регистр.

    2. <PACKAGENAME>_ROOT Переменная CMake, где <PACKAGENAME> — это имя пакета в верхнем регистре. См. политику CMP0144.

      Добавлена в версии 3.27.

    3. <PackageName>_ROOT Переменная среды, где <PackageName> — это имя пакета, сохраняющее регистр.

    4. <PACKAGENAME>_ROOT Переменная среды, где <PACKAGENAME> — это имя пакета в верхнем регистре. См. политику CMP0144.

      Добавлена в версии 3.27.

    Переменные корня пакета хранятся в виде стека, поэтому, если вызываются вложенные модули поиска или пакеты конфигурации, пути корня из родительского модуля поиска или пакета конфигурации будут просматриваться после путей из текущего модуля или пакета. Другими словами, порядок поиска будет <CurrentPackage>_ROOT, ENV{<CurrentPackage>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, и т. д. Это можно пропустить, если передать NO_PACKAGE_ROOT_PATH или установив CMAKE_FIND_USE_PACKAGE_ROOT_PATH в FALSE.

    • <prefix>/include/<arch> если CMAKE_LIBRARY_ARCHITECTURE установлена, и <prefix>/include для каждого <prefix> в <PackageName>_ROOT переменной CMake и <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 хостах CMake 3.3 до 3.27 искались дополнительные пути: <prefix>/include/<arch> если CMAKE_LIBRARY_ARCHITECTURE установлена, и <prefix>/include для каждого <prefix>/[s]bin в PATH, и <entry>/include для других элементов в PATH. Это поведение было удалено в CMake 3.28.

  6. Просмотр переменных cmake, определённых в файлах платформы для текущей системы. Поиск CMAKE_INSTALL_PREFIX и CMAKE_STAGING_PREFIX можно пропустить, если передать NO_CMAKE_INSTALL_PREFIX или установив CMAKE_FIND_USE_INSTALL_PREFIX в FALSE. Все эти местоположения можно пропустить, если передать 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 или в сокращённой версии команды. Обычно это жёстко заданные угадывания.

Переменные CMAKE_IGNORE_PATH, CMAKE_IGNORE_PREFIX_PATH, CMAKE_SYSTEM_IGNORE_PATH и CMAKE_SYSTEM_IGNORE_PREFIX_PATH также могут привести к игнорированию некоторых вышеуказанных местоположений.

Добавлена в версии 3.16: Добавлены переменные CMAKE_FIND_USE_<CATEGORY>_PATH для глобального отключения различных мест поиска.

В 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)

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

© 2000–2024 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/v3.31/command/find_file.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API