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_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, и поиск будет повторён в следующий раз, когда команда find_program будет вызвана с той же переменной.

Доступные опции:

NAMES

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

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

HINTS, PATHS

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

PATH_SUFFIXES

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

DOC

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

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

1. Если вызов происходит внутри модуля поиска или любого другого скрипта, загруженного с помощью вызова 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
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, затем в 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 сообщает этой команде рассматривать один каталог за раз и искать в нём все имена.