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