find_program

Краткая форма записи:

find_program (<VAR> <name> [<path>...])

Общая форма записи:

find_program (
          <VAR>
          {<name> | NAMES <name>... [NAMES_PER_DIR]}
          [HINTS {<path> | ENV <var>}...]
          [PATHS {<path> | ENV <var>}...]
          [REGISTRY_VIEW {64|32|64_32|32_64|HOST|TARGET|BOTH}]
          [PATH_SUFFIXES <suffix>...]
          [VALIDATOR <function>]
          [DOC "cache documentation string"]
          [NO_CACHE]
          [REQUIRED|OPTIONAL]
          [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]
         )

Эта команда используется для поиска программы.

Перед поиском find_program проверяет, определена ли переменная <VAR>. Если переменная не определена, выполняется поиск. Если переменная определена и ее значение равно NOTFOUND или заканчивается на -NOTFOUND, выполняется поиск. Если переменная содержит любое другое значение, поиск не выполняется.

Результаты поиска будут сохранены в записи кэша с именем <VAR>. При последующих вызовах find_program будет проверяться эта запись кэша, если указано то же <VAR>. Эта оптимизация гарантирует, что успешный поиск не будет выполняться повторно, пока запись кэша не будет unset().

Если программа найдена, в записи кэша <VAR> будет сохранено значение, полученное в результате поиска. Если ничего не найдено, будет сохранено значение <VAR>-NOTFOUND.

Доступны следующие параметры:

NAMES

Указывает одно или несколько возможных имен программы.

При указании имен с суффиксом версии и без него рекомендуется сначала указать имя без версии, чтобы пакеты, собранные локально, находились раньше пакетов, предоставляемых дистрибутивами.

HINTS, PATHS

Указывает каталоги для поиска в дополнение к расположениям по умолчанию. Подпараметр ENV var считывает пути из системной переменной среды.

Изменено в версии 3.24: На платформе Windows в качестве каталогов можно указывать запросы к реестру, используя специальный синтаксис. Такие спецификации будут игнорироваться на всех остальных платформах.

REGISTRY_VIEW

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

Указывает, какие представления реестра следует запрашивать. Этот параметр имеет смысл только на платформах Windows и игнорируется на остальных. Если параметр не указан, используется представление BOTH, когда политика CMP0134 имеет значение NEW. Сведения о представлении по умолчанию, используемом, когда политика имеет значение OLD, см. в описании политики CMP0134.

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_program (result NAMES ... VALIDATOR my_check)

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

DOC

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

NO_CACHE

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

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

Примечание

find_program по-прежнему будет проверять <VAR> как обычно: сначала переменную, а затем запись кэша. Если любая из них указывает на успешный предыдущий поиск, поиск выполняться не будет.

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

Используйте этот параметр с осторожностью, поскольку он может значительно увеличить затраты на повторные этапы конфигурирования.

REQUIRED

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

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

Добавлено в версии 4.1: Каждая команда find_program будет считаться REQUIRED, если включена переменная CMAKE_FIND_REQUIRED.

OPTIONAL

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

Игнорирует значение CMAKE_FIND_REQUIRED и продолжает работу без сообщения об ошибке, если ничего не найдено. Несовместим с REQUIRED.

Если указан параметр NO_DEFAULT_PATH, дополнительные пути к поиску не добавляются. Если параметр NO_DEFAULT_PATH не указан, поиск выполняется следующим образом:

1. Если команда вызвана из модуля поиска или любого другого скрипта, загруженного вызовом find_package(<PackageName>), выполняется поиск префиксов, уникальных для текущего искомого пакета. См. политику CMP0074.

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

   В частности, выполняется поиск путей, указанных следующими переменными, в указанном порядке:

   1. переменная CMake <PackageName>_ROOT, где <PackageName> — имя пакета с сохранением регистра.

   2. переменная CMake <PACKAGENAME>_ROOT, где <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 также могут привести к игнорированию некоторых из перечисленных выше расположений.

В 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})