Spec-Zone.ru › CMake 3.30

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

Spec-Zone.ru

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