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

Переменные CMAKE_IGNORE_PATH, CMAKE_IGNORE_PREFIX_PATH, CMAKE_SYSTEM_IGNORE_PATH и CMAKE_SYSTEM_IGNORE_PREFIX_PATH также могут привести к игнорированию некоторых из вышеперечисленных расположений.

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