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

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