Spec-Zone.ru › CMake 3.28

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.28/command/find_program.html

Spec-Zone.ru

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