Spec-Zone.ru › CMake 3.29

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

Spec-Zone.ru

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