Spec-Zone.ru › CMake

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 политике 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/latest/command/find_file.html

Spec-Zone.ru

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