Spec-Zone.ru › CMake 3.27

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 политики 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_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.
    • В системах Windows дополнительных путей поиска не включено.

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

Spec-Zone.ru

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