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]... ]
          [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
          [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]
          [NO_CMAKE_INSTALL_PREFIX]
          [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 считывает пути из системной переменной окружения.

Изменено в версии 3.24: На платформах Windows возможно включение запросов к реестру в качестве части каталогов, используя специальный синтаксис посвящённый синтаксис. Такие указания будут проигнорированы на всех остальных платформах.

REGISTRY_VIEW

Добавлена в версии 3.24.

Укажите, какие представления реестра необходимо запросить. Эта опция имеет смысл только на платформах Windows и будет проигнорирована на других. Если не указано, используется представление BOTH при NEW политике CMP0134. См. CMP0134 для представления по умолчанию, когда политика OLD.

64

Запрос к 64-битному реестру. В 32-битной Windows всегда возвращает строку /REGISTRY-NOTFOUND.

32

Запрос к 32-битному реестру.

64_32

Запрос обоих представлений (64 и 32) и генерация пути для каждого.

32_64

Запрос обоих представлений (32 и 64) и генерация пути для каждого.

HOST

Запрос к реестру, соответствующему архитектуре хоста: 64 в 64-битной Windows и 32 в 32-битной Windows.

TARGET

Запрос к реестру, соответствующему архитектуре, указанной в переменной CMAKE_SIZEOF_VOID_P. Если не определена, используется представление HOST.

BOTH

Запрос обоих представлений (32 и 64). Порядок зависит от следующих правил: если переменная CMAKE_SIZEOF_VOID_P определена, используется представление в зависимости от её содержимого:

• 8: 64_32
• 4: 32_64

Если переменная CMAKE_SIZEOF_VOID_P не определена, используется архитектура хоста:

• 64-разрядная: 64_32
• 32-разрядная: 32

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, определённые в файлах платформы для текущей системы. Поиск CMAKE_INSTALL_PREFIX и CMAKE_STAGING_PREFIX можно пропустить, если передать NO_CMAKE_INSTALL_PREFIX или установить CMAKE_FIND_USE_INSTALL_PREFIX в значение FALSE. Все эти места могут быть пропущены, если передать 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 сообщает этой команде рассматривать один каталог за раз и искать все имена в нём.