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"]
          [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]
         )

Эта команда используется для поиска программы. В кэше создается запись с именем <VAR>, чтобы сохранить результат этой команды. Если программа найдена, результат сохраняется в переменной, и поиск не будет повторён, пока переменная не будет очищена. Если ничего не найдено, результат будет <VAR>-NOTFOUND. Опция REQUIRED останавливает обработку с сообщением об ошибке, если ничего не найдено; в противном случае поиск будет повторён в следующий раз, когда find_program вызывается с той же переменной.

Доступны следующие опции:

NAMES

Указывает одно или несколько возможных имён программы.

При указании имён с и без суффикса версии рекомендуется сначала указать имя без версии, чтобы локально скомпилированные пакеты находились перед пакетами, предоставленными дистрибутивами.

HINTS, PATHS

Указывает каталоги для поиска помимо стандартных. Опция ENV var считывает пути из системной переменной окружения.

PATH_SUFFIXES

Указывает дополнительные подкаталоги для проверки в каждом каталоге, который в противном случае рассматривается.

DOC

Указывает строку документации для записи кэша <VAR>.

REQUIRED

Останавливает обработку с сообщением об ошибке, если ничего не найдено.

Если NO_DEFAULT_PATH указана, дополнительные пути к поиску не добавляются. Если NO_DEFAULT_PATH не указана, процесс поиска выполняется следующим образом:

1. Если вызов происходит внутри модуля find или любого другого сценария, загруженного с помощью вызова find_package(<PackageName>), проверяются уникальные префиксы путей для текущего искомого пакета. В частности, ищутся в переменной CMake <PackageName>_ROOT и переменной окружения <PackageName>_ROOT. Переменные корня пакета хранятся как стек, поэтому при вызове из вложенных модулей find или пакетов конфигурации пути корня из родительского модуля find или пакета конфигурации будут просматриваться после путей из текущего модуля или пакета. Другими словами, порядок поиска будет <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, загруженного с помощью 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 порядок предпочтения между компонентами пакета в стиле Apple и unix-стиле определяется переменными CMAKE_FIND_FRAMEWORK и CMAKE_FIND_APPBUNDLE.

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