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 или в короткой форме команды. Это обычно зашитые догадки.

На 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 указывает этой команде рассматривать по одному каталогу за раз и искать во всех именах в нём.