find_path

Короткая запись:

find_path (<VAR> name1 [path1 path2 ...])

Общая запись:

find_path (
          <VAR>
          name | NAMES name1 [name2 ...]
          [HINTS path1 [path2 ... ENV var]]
          [PATHS path1 [path2 ... ENV var]]
          [PATH_SUFFIXES suffix1 [suffix2 ...]]
          [DOC "cache documentation string"]
          [NO_DEFAULT_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_path с той же переменной.

Доступны следующие параметры:

NAMES

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

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

HINTS, PATHS

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

PATH_SUFFIXES

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

DOC

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

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

1. Поиск путей, указанных в переменных кэша CMake. Они предназначены для использования в командной строке с -DVAR=value. Значения интерпретируются как ;-списки. Этот этап можно пропустить, если передан параметр NO_CMAKE_PATH.
   • <prefix>/include/<arch> если установлена CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/include для каждого <prefix> в CMAKE_PREFIX_PATH
   • CMAKE_INCLUDE_PATH
   • CMAKE_FRAMEWORK_PATH
2. Поиск путей, указанных в переменных окружения CMake. Они предназначены для настройки оболочки пользователя и поэтому используют системный разделитель путей (; в Windows и : в UNIX). Этот этап можно пропустить, если передан параметр NO_CMAKE_ENVIRONMENT_PATH.
   • <prefix>/include/<arch> если установлена CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/include для каждого <prefix> в CMAKE_PREFIX_PATH
   • CMAKE_INCLUDE_PATH
   • CMAKE_FRAMEWORK_PATH
3. Поиск путей, указанных параметром HINTS. Эти пути должны быть вычислены с помощью анализа системы, например, подсказка, полученная из расположения другого уже найденного элемента. Заданные «предположения» должны быть указаны параметром PATHS.
4. Поиск в стандартных системных переменных окружения. Этот этап можно пропустить, если NO_SYSTEM_ENVIRONMENT_PATH является аргументом.
   • Директории в INCLUDE. В Windows: <prefix>/include/<arch> если установлена CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/include для каждого <prefix>/[s]bin в PATH, и <entry>/include для других элементов в PATH, и директории в PATH.
5. Поиск переменных CMake, определённых в файлах платформы для текущей системы. Этот этап можно пропустить, если передан параметр NO_CMAKE_SYSTEM_PATH.
   • <prefix>/include/<arch> если установлена CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/include для каждого <prefix> в CMAKE_SYSTEM_PREFIX_PATH
   • CMAKE_SYSTEM_INCLUDE_PATH
   • CMAKE_SYSTEM_FRAMEWORK_PATH
6. Поиск путей, указанных параметром PATHS или в короткой форме команды. Как правило, это заранее заданные предположения.

В OS X порядок предпочтения между компонентами пакетов 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_INCLUDE. Это поведение может быть переопределено на основе вызова с помощью параметров:

CMAKE_FIND_ROOT_PATH_BOTH

Поиск в описанном выше порядке.

NO_CMAKE_FIND_ROOT_PATH

Не использовать переменную CMAKE_FIND_ROOT_PATH.

ONLY_CMAKE_FIND_ROOT_PATH

Искать только в переустановленных корневых директориях и в директориях ниже CMAKE_STAGING_PREFIX.

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

find_path (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
find_path (<VAR> NAMES name)

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

При поиске фреймворков, если файл указан как A/b.h, то поиск фреймворков будет искать A.framework/Headers/b.h. Если он найден, путь будет установлен к пути к фреймворку. CMake преобразует это в правильный параметр -F для включения файла.