find_program

Краткая запись:

find_program (<VAR> name1 [path1 path2 ...])

Общая запись:

find_program (
          <VAR>
          name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
          [HINTS path1 [path2 ... ENV var]]
          [PATHS path1 [path2 ... ENV var]]
          [PATH_SUFFIXES suffix1 [suffix2 ...]]
          [DOC "cache documentation string"]
          [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]
         )

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

Доступные параметры:

NAMES

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

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

HINTS, PATHS

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

PATH_SUFFIXES

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

DOC

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

REQUIRED

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

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

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

1. Новая в версии 3.12: Если вызвана из модуля find или любого другого скрипта, загруженного с помощью вызова find_package(<PackageName>), поиск префиксов, уникальных для текущего находимого пакета. В частности, поиск в переменной CMake <PackageName>_ROOT и переменной окружения <PackageName>_ROOT. Переменные корневого каталога пакета хранятся как стек, поэтому если вызвана из вложенных модулей find или конфигурационных пакетов, пути корней родительского модуля find или конфигурационного пакета будут проверяться после путей текущего модуля или пакета. Другими словами, порядок поиска будет <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, загруженного посредством 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 и в стиле 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 сообщает этой команде рассматривать один каталог за раз и искать во всех каталогах все имена.