Spec-Zone.ru › CMake 3.30

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> в переменной 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 в 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.30/command/find_file.html

    Spec-Zone.ru

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