find_file

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

find_file (<VAR> <name> [<path>...])

Общая форма записи:

find_file (
          <VAR>
          {<name> | NAMES <name>...}
          [HINTS {<path> | ENV <var>}...]
          [PATHS {<path> | ENV <var>}...]
          [REGISTRY_VIEW {64|32|64_32|32_64|HOST|TARGET|BOTH}]
          [PATH_SUFFIXES <suffix>...]
          [VALIDATOR <function>]
          [DOC "cache documentation string"]
          [NO_CACHE]
          [REQUIRED|OPTIONAL]
          [NO_DEFAULT_PATH]
          [NO_PACKAGE_ROOT_PATH]
          [NO_CMAKE_PATH]
          [NO_CMAKE_ENVIRONMENT_PATH]
          [NO_SYSTEM_ENVIRONMENT_PATH]
          [NO_CMAKE_SYSTEM_PATH]
          [NO_CMAKE_INSTALL_PREFIX]
          [CMAKE_FIND_ROOT_PATH_BOTH |
           ONLY_CMAKE_FIND_ROOT_PATH |
           NO_CMAKE_FIND_ROOT_PATH]
         )

Эта команда используется для поиска полного пути к файлу с заданным именем.

Перед поиском find_file проверяет, определена ли переменная <VAR>. Если переменная не определена, выполняется поиск. Если переменная определена, а её значение равно NOTFOUND или оканчивается на -NOTFOUND, выполняется поиск. Если переменная содержит любое другое значение, поиск не выполняется.

Результаты поиска будут сохранены в записи кэша с именем <VAR>. При последующих вызовах find_file для того же <VAR> будет проверяться эта запись кэша. Такая оптимизация позволяет не повторять успешный поиск, если только запись кэша не была unset().

Если полный путь к файлу найден, в записи кэша <VAR> будет сохранён результат поиска. Если ничего не найдено, будет сохранено значение <VAR>-NOTFOUND.

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

NAMES

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

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

HINTS, PATHS

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

Изменено в версии 3.24: На платформе Windows в качестве каталогов можно указывать запросы к реестру, используя специальный синтаксис. Такие спецификации игнорируются на всех остальных платформах.

REGISTRY_VIEW

Добавлено в версии 3.24.

Задаёт представления реестра, в которых следует выполнять поиск. Этот параметр имеет смысл только на платформах Windows и игнорируется на остальных. Если параметр не задан, используется представление TARGET, когда политика CMP0134 установлена в значение NEW. Сведения о представлении по умолчанию, если политика установлена в значение OLD, см. в описании CMP0134.

64

Выполняет поиск в 64-разрядном реестре. В 32-разрядной Windows всегда возвращает строку /REGISTRY-NOTFOUND.

32

Выполняет поиск в 32-разрядном реестре.

64_32

Выполняет поиск в обоих представлениях (64 и 32) и формирует путь для каждого.

32_64

Выполняет поиск в обоих представлениях (32 и 64) и формирует путь для каждого.

HOST

Выполняет поиск в реестре, соответствующем архитектуре хоста: 64 в 64-разрядной Windows и 32 в 32-разрядной Windows.

TARGET

Выполняет поиск в реестре, соответствующем архитектуре, заданной переменной CMAKE_SIZEOF_VOID_P. Если она не определена, используется представление HOST.

BOTH

Выполняет поиск в обоих представлениях (32 и 64). Порядок определяется следующими правилами. Если переменная CMAKE_SIZEOF_VOID_P определена, используется представление в зависимости от её значения:

• 8: 64_32
• 4: 32_64

Если переменная CMAKE_SIZEOF_VOID_P не определена, используется архитектура хоста:

• 64-разрядная: 64_32
• 32-разрядная: 32

PATH_SUFFIXES

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

VALIDATOR

Добавлено в версии 3.25.

Задаёт function(), которая будет вызываться для каждого найденного кандидата (указать macro() нельзя — это приведёт к ошибке). Функции-валидатору будут переданы два аргумента: имя переменной результата и абсолютный путь к кандидату. Кандидат будет принят, и поиск завершится, если только функция не присвоит переменной результата в вызывающей области видимости значение false. При входе в функцию-валидатор переменная результата будет содержать значение true.

function(my_check validator_result_var item)
  if(NOT item MATCHES ...)
    set(${validator_result_var} FALSE PARENT_SCOPE)
  endif()
endfunction()

find_file (result NAMES ... VALIDATOR my_check)

Обратите внимание: если используется кэшированный результат, поиск пропускается, а любые VALIDATOR игнорируются. Кэшированный результат не обязан проходить проверку функции-валидатора.

DOC

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

NO_CACHE

Добавлено в версии 3.21.

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

Примечание

find_file по-прежнему проверяет <VAR> обычным образом: сначала переменную, затем запись кэша. Если любая из них указывает на предыдущий успешный поиск, новый поиск выполняться не будет.

Предупреждение

Используйте этот параметр с осторожностью, поскольку он может значительно увеличить стоимость повторных этапов конфигурирования.

REQUIRED

Добавлено в версии 3.18.

Останавливает обработку и выводит сообщение об ошибке, если ничего не найдено; в противном случае поиск будет повторён при следующем вызове find_file с той же переменной.

Добавлено в версии 4.1: Каждая команда find_file будет считаться командой REQUIRED, если включена переменная CMAKE_FIND_REQUIRED.

OPTIONAL

Добавлено в версии 4.1.

Игнорирует значение CMAKE_FIND_REQUIRED и продолжает работу без сообщения об ошибке, если ничего не найдено. Несовместим с REQUIRED.

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

1. Если вызов выполнен из модуля поиска или любого другого скрипта, загруженного вызовом find_package(<PackageName>), выполняется поиск по префиксам, уникальным для текущего искомого пакета. См. политику CMP0074.

   Добавлено в версии 3.12.

   В частности, выполняется поиск по путям, заданным следующими переменными, в указанном порядке:

   1. переменная CMake <PackageName>_ROOT, где <PackageName> — имя пакета с сохранением регистра.

   2. переменная CMake <PACKAGENAME>_ROOT, где <PACKAGENAME> — имя пакета в верхнем регистре. См. политику CMP0144.

      Добавлено в версии 3.27.

   3. переменная окружения <PackageName>_ROOT, где <PackageName> — имя пакета с сохранением регистра.

   4. переменная окружения <PACKAGENAME>_ROOT, где <PACKAGENAME> — имя пакета в верхнем регистре. См. политику CMP0144.

      Добавлено в версии 3.27.

   Переменные корневых каталогов пакетов хранятся в виде стека, поэтому при вызове из вложенных модулей поиска или пакетов конфигурации пути из родительского модуля поиска или пакета конфигурации будут просматриваться после путей текущего модуля или пакета. Иными словами, порядок поиска будет таким: <CurrentPackage>_ROOT, ENV{<CurrentPackage>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT} и т. д. Этот этап можно пропустить, передав NO_PACKAGE_ROOT_PATH или задав для CMAKE_FIND_USE_PACKAGE_ROOT_PATH значение FALSE.

   • <prefix>/include/<arch>, если задана переменная CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/include для каждого <prefix> в переменной CMake <PackageName>_ROOT и переменной окружения <PackageName>_ROOT, если вызов выполнен из модуля поиска, загруженного командой find_package(<PackageName>)

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

   • <prefix>/include/<arch>, если задана переменная CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/include для каждого <prefix> в CMAKE_PREFIX_PATH
   • CMAKE_INCLUDE_PATH
   • CMAKE_FRAMEWORK_PATH

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

   • <prefix>/include/<arch>, если задана переменная CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/include для каждого <prefix> в CMAKE_PREFIX_PATH
   • CMAKE_INCLUDE_PATH
   • CMAKE_FRAMEWORK_PATH
4. Поиск по путям, заданным параметром HINTS. Это должны быть пути, полученные в результате анализа системы, например подсказка на основе расположения другого уже найденного элемента. Жёстко заданные предполагаемые пути следует указывать с помощью параметра PATHS.

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

   • Каталоги из INCLUDE и PATH.

   На хостах Windows в CMake версий с 3.3 по 3.27 выполнялся поиск и по дополнительным путям: <prefix>/include/<arch>, если задана переменная CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/include для каждого <prefix>/[s]bin в PATH, а также <entry>/include для остальных записей в PATH. Это поведение было удалено в CMake 3.28.

6. Поиск по переменным CMake, определённым в файлах платформы для текущей системы. Поиск по CMAKE_INSTALL_PREFIX и CMAKE_STAGING_PREFIX можно пропустить, передав NO_CMAKE_INSTALL_PREFIX или задав для CMAKE_FIND_USE_INSTALL_PREFIX значение FALSE. Все эти расположения можно пропустить, передав NO_CMAKE_SYSTEM_PATH или задав для CMAKE_FIND_USE_CMAKE_SYSTEM_PATH значение FALSE.

   • <prefix>/include/<arch>, если задана переменная CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/include для каждого <prefix> в CMAKE_SYSTEM_PREFIX_PATH
   • CMAKE_SYSTEM_INCLUDE_PATH
   • CMAKE_SYSTEM_FRAMEWORK_PATH

   Пути платформы, содержащиеся в этих переменных, указывают на расположения, в которых обычно установлено программное обеспечение. Например, /usr/local для платформ на базе UNIX.

7. Поиск по путям, заданным параметром PATHS или в краткой форме команды. Обычно это жёстко заданные предполагаемые пути.

Переменные CMAKE_IGNORE_PATH, CMAKE_IGNORE_PREFIX_PATH, CMAKE_SYSTEM_IGNORE_PATH и CMAKE_SYSTEM_IGNORE_PREFIX_PATH также могут привести к игнорированию некоторых из перечисленных выше расположений.

В 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_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_file (<VAR> NAMES name PATHS <paths>... NO_DEFAULT_PATH)
find_file (<VAR> NAMES name)

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