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]... ]
          [PATH_SUFFIXES suffix1 [suffix2 ...]]
          [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]
          [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 считывает пути из системной переменной окружения.

PATH_SUFFIXES

Укажите дополнительные подкаталоги для проверки в каждом каталоге, который иначе рассматривается.

DOC

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

NO_CACHE

Новая версия 3.21.

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

Примечание

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

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

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

REQUIRED

Новая версия 3.18.

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

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

1. Новая версия 3.12: Если вызов производится из модуля поиска или любого другого скрипта, загруженного вызовом find_package(<PackageName>), будут использованы префиксы поиска, уникальные для текущего искомого пакета. В частности, см. переменную CMake <PackageName>_ROOT и переменную среды <PackageName>_ROOT. Переменные корня пакета хранятся в стеке, поэтому при вызове из вложенных модулей поиска или пакетов конфигурации, пути корней родительского модуля поиска или пакета конфигурации будут проверяться после путей текущего модуля или пакета. Другими словами, порядок поиска будет <CurrentPackage>_ROOT, ENV{<CurrentPackage>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, и т.д. Это можно пропустить, если передано NO_PACKAGE_ROOT_PATH или задать CMAKE_FIND_USE_PACKAGE_ROOT_PATH в значение FALSE. См. политику CMP0074.

   • <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, определённых в файлах платформы для текущей системы. Это можно пропустить, если передано 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 или в сокращённой форме команды. Как правило, это жёстко закодированные предположения.

В macOS переменные CMAKE_FIND_FRAMEWORK и CMAKE_FIND_APPBUNDLE определяют порядок приоритетов между компонентами пакетов Apple-style и unix-style.

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