Spec-Zone.ru › CMake 3.31

find_program

Сокращенная сигнатура:

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

Общая сигнатура:

find_program (
          <VAR>
          name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
          [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 и будет проигнорирован на других. Если не указано, используется представление BOTH, когда политика 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_program (result NAMES ... VALIDATOR my_check)

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

DOC

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

NO_CACHE

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

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

Примечание

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

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

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

REQUIRED

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

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

Если 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>/[s]bin для каждого <prefix> в переменной CMake <PackageName>_ROOT и переменной среды <PackageName>_ROOT, если вызов производится из модуля поиска, загруженного с помощью find_package(<PackageName>)

  2. Пути поиска, указанные в переменных кэша, специфичных для CMake. Они предназначены для использования в командной строке с -DVAR=value. Значения интерпретируются как списки, разделённые точкой с запятой. Это можно пропустить, если передано NO_CMAKE_PATH или путем установки CMAKE_FIND_USE_CMAKE_PATH на FALSE.

    • <prefix>/[s]bin для каждого <prefix> в CMAKE_PREFIX_PATH
    • CMAKE_PROGRAM_PATH
    • CMAKE_APPBUNDLE_PATH

  3. Пути поиска, указанные в переменных среды, специфичных для CMake. Они предназначены для установки в конфигурации оболочки пользователя и поэтому используют разделитель путей хоста (; в Windows и : в UNIX). Это можно пропустить, если передано NO_CMAKE_ENVIRONMENT_PATH или путем установки CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH на FALSE.

    • <prefix>/[s]bin для каждого <prefix> в CMAKE_PREFIX_PATH
    • CMAKE_PROGRAM_PATH
    • CMAKE_APPBUNDLE_PATH
  4. Искать пути, указанные в опции HINTS. Это обычно пути, вычисленные путём анализа системы, например, подсказка, предоставленная местоположением другого уже найденного элемента. Зашифрованные догадки должны быть указаны с помощью опции PATHS.

  5. Искать стандартные переменные среды системы. Это можно пропустить, если передано NO_SYSTEM_ENVIRONMENT_PATH или путём установки CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH на FALSE.

    • Каталоги в самом PATH.

  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>/[s]bin для каждого <prefix> в CMAKE_SYSTEM_PREFIX_PATH
    • CMAKE_SYSTEM_PROGRAM_PATH
    • CMAKE_SYSTEM_APPBUNDLE_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_PROGRAM. Это поведение можно переопределить вручную для каждого вызова с помощью параметров:

CMAKE_FIND_ROOT_PATH_BOTH

Поиск в указанном выше порядке.

NO_CMAKE_FIND_ROOT_PATH

Не использовать переменную CMAKE_FIND_ROOT_PATH.

ONLY_CMAKE_FIND_ROOT_PATH

Искать только переустановленные каталоги и каталоги ниже CMAKE_STAGING_PREFIX.

Порядок поиска по умолчанию разработан как наиболее конкретный к наименее конкретному для распространённых случаев использования. Проекты могут переопределить порядок, просто вызвав команду несколько раз и используя NO_* параметры:

find_program (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
find_program (<VAR> NAMES name)

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

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

Набор файлов, которые считаются программами, зависит от платформы:

  • В Windows, расширения имён файлов рассматриваются в порядке .com, .exe, и без расширения.
  • В системах, отличных от Windows, расширение имени файла не учитывается, но файлы должны иметь разрешение на выполнение (см. политику CMP0109).

Чтобы искать скрипты, явно укажите расширение:

if(WIN32)
  set(_script_suffix .bat)
else()
  set(_script_suffix .sh)
endif()

find_program(MY_SCRIPT NAMES my_script${_script_suffix})

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

Spec-Zone.ru

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