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"]
          [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, и поиск будет повторён в следующий раз при вызове find_program с той же переменной.

Доступные опции:

NAMES

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

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

HINTS, PATHS

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

PATH_SUFFIXES

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

DOC

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

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

1. Если вызов происходит изнутри модуля поиска, загруженного с помощью find_package(<PackageName>), ищется в префиксах, уникальных для текущего находимого пакета. В частности, проверяется переменная CMake <PackageName>_ROOT и переменная среды <PackageName>_ROOT. Переменные корня пакета сохраняются как стек, поэтому, если вызов происходит из вложенных модулей поиска, пути корней из родительского модуля поиска будут проверены после путей текущего модуля, т.е. <CurrentPackage>_ROOT, ENV{<CurrentPackage>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, и т.д. Это можно пропустить, если передано NO_PACKAGE_ROOT_PATH. См. политику CMP0074.
   • <prefix>/[s]bin для каждой <prefix> в переменной CMake <PackageName>_ROOT и переменной среды <PackageName>_ROOT, если вызов происходит изнутри модуля поиска, загруженного с помощью find_package(<PackageName>)
2. Проверяются пути, указанные в переменных кэша, специфичных для CMake. Они предназначены для использования в командной строке с -DVAR=value. Значения интерпретируются как ;-списки. Это можно пропустить, если передано NO_CMAKE_PATH.
   • <prefix>/[s]bin для каждой <prefix> в CMAKE_PREFIX_PATH
   • CMAKE_PROGRAM_PATH
   • CMAKE_APPBUNDLE_PATH
3. Проверяются пути, указанные в переменных среды, специфичных для CMake. Они предназначены для установки в конфигурации оболочки пользователя и поэтому используют стандартный разделитель путей системы (; в Windows и : в UNIX). Это можно пропустить, если передано NO_CMAKE_ENVIRONMENT_PATH.
   • <prefix>/[s]bin для каждой <prefix> в CMAKE_PREFIX_PATH
   • CMAKE_PROGRAM_PATH
   • CMAKE_APPBUNDLE_PATH
4. Проверяются пути, указанные опцией HINTS. Они должны быть путями, вычисленными путём анализа системы, такими как подсказка, предоставленная местоположением другого уже найденного элемента. Заданные заранее предположения должны быть указаны опцией PATHS.
5. Проверяются стандартные переменные окружения. Это можно пропустить, если NO_SYSTEM_ENVIRONMENT_PATH является аргументом.
   • PATH
6. Проверяются переменные cmake, определённые в файлах платформы для текущей системы. Это можно пропустить, если передано NO_CMAKE_SYSTEM_PATH.
   • <prefix>/[s]bin для каждой <prefix> в CMAKE_SYSTEM_PREFIX_PATH
   • CMAKE_SYSTEM_PROGRAM_PATH
   • CMAKE_SYSTEM_APPBUNDLE_PATH
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 сообщает этой команде рассматривать один каталог за раз и искать все имена в нём.