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_CMAKE_ENVIRONMENT_PATH]
          [NO_CMAKE_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. Поиск в каталогах, указанных в переменных кэша CMake. Они предназначены для использования в командной строке с -DVAR=value. Этот шаг можно пропустить, если передано NO_CMAKE_PATH.
   • <prefix>/[s]bin для каждого <prefix> в CMAKE_PREFIX_PATH
   • CMAKE_PROGRAM_PATH
   • CMAKE_APPBUNDLE_PATH
2. Поиск в каталогах, указанных в переменных окружения CMake. Они предназначены для установки в конфигурации пользовательской оболочки. Этот шаг можно пропустить, если передано NO_CMAKE_ENVIRONMENT_PATH.
   • <prefix>/[s]bin для каждого <prefix> в CMAKE_PREFIX_PATH
   • CMAKE_PROGRAM_PATH
   • CMAKE_APPBUNDLE_PATH
3. Поиск в каталогах, указанных опцией HINTS. Они должны быть путями, полученными путём интроспекции системы, например, подсказки, полученной из местоположения другого уже найденного элемента. Жестко заданные предположения должны быть указаны с помощью опции PATHS.
4. Поиск в стандартных переменных окружения. Этот шаг можно пропустить, если NO_SYSTEM_ENVIRONMENT_PATH является аргументом.
   • PATH
5. Поиск в переменных CMake, определённых в файлах платформы для текущей системы. Этот шаг можно пропустить, если передано NO_CMAKE_SYSTEM_PATH.
   • <prefix>/[s]bin для каждого <prefix> в CMAKE_SYSTEM_PREFIX_PATH
   • CMAKE_SYSTEM_PROGRAM_PATH
   • CMAKE_SYSTEM_APPBUNDLE_PATH
6. Поиск в каталогах, указанных опцией 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 сообщает этой команде рассматривать по одному каталогу за раз и искать во всех нём указанные имена.