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. См. политику CMP0074.

   • <prefix>/[s]bin для каждого <prefix> в переменной CMake <PackageName>_ROOT и переменной среды <PackageName>_ROOT, если вызов происходит из модуля поиска, загруженного с помощью find_package(<PackageName>)

2. Пути поиска, указанные в переменных кэша, специфичных для CMake. Они предназначены для использования в командной строке со значением -DVAR=value. Значения интерпретируются как списки, разделенные точкой с запятой. Это можно пропустить, если передано значение NO_CMAKE_PATH.

   • <prefix>/[s]bin для каждого <prefix> в CMAKE_PREFIX_PATH
   • CMAKE_PROGRAM_PATH
   • CMAKE_APPBUNDLE_PATH

3. Пути поиска, указанные в переменных среды, специфичных для CMake. Они предназначены для установки в конфигурации оболочки пользователя, поэтому используют системный разделитель путей хоста (; в Windows и : в UNIX). Это можно пропустить, если передано значение NO_CMAKE_ENVIRONMENT_PATH.

   • <prefix>/[s]bin для каждого <prefix> в CMAKE_PREFIX_PATH
   • CMAKE_PROGRAM_PATH
   • CMAKE_APPBUNDLE_PATH
4. Поиск путей, указанных параметром HINTS. Эти пути должны быть вычислены путем анализа системы, например, в виде подсказки, полученной из расположения другого найденного элемента. Жестко заданные предположения должны быть указаны с помощью параметра PATHS.

5. Поиск по стандартным переменным среды системы. Это можно пропустить, если NO_SYSTEM_ENVIRONMENT_PATH является аргументом.

   • PATH

6. Поиск переменных CMake, определенных в файлах платформы для текущей системы. Это можно пропустить, если передано значение NO_CMAKE_SYSTEM_PATH.

   • <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_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 указывает команде рассматривать один каталог за раз и искать в нем все имена.