Spec-Zone.ru › CMake 3.29

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(), это приведёт к ошибке). Функции-валидатора будут переданы два аргумента: имя переменной результата и абсолютный путь к кандидату. Элемент будет принят, и поиск завершится, если функция не установит значение в переменную результата в вызывающей области в значение false. Переменная результата будет содержать значение true, когда функция-валидатор будет запущена.

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.29/command/find_file.html

Spec-Zone.ru

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