Spec-Zone.ru › CMake 3.31

find_path

Краткая запись:

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

Общая запись:

find_path (
          <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. См. OLD для представления по умолчанию, когда политика NEW.

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_path (result NAMES ... VALIDATOR my_check)

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

DOC

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

NO_CACHE

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

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

Примечание

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

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

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

REQUIRED

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

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

Если 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_path (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
find_path (<VAR> NAMES name)

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

При поиске фреймворков, если файл задан как A/b.h, то поиск фреймворков будет осуществляться по A.framework/Headers/b.h. Если он найден, путь будет установлен на путь к фреймворку. CMake преобразует это в правильную опцию -F для включения файла.

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

Spec-Zone.ru

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