Spec-Zone.ru › CMake 3.29

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 сообщает этой команде рассматривать один каталог за раз и искать все имена в нём.

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

Spec-Zone.ru

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