cmake_language

Вызов мета-операций для команд CMake.

Синтаксис

cmake_language(CALL <command> [<arg>...])
cmake_language(EVAL CODE <code>...)
cmake_language(DEFER <options>... CALL <command> [<arg>...])
cmake_language(SET_DEPENDENCY_PROVIDER <command> SUPPORTED_METHODS <methods>...)

Введение

Эта команда будет вызывать мета-операции для встроенных команд CMake или команд, созданных с помощью команд macro() или function().

cmake_language не вводит новую переменную или область политики.

Вызов команд

cmake_language(CALL <command> [<arg>...])

Вызывает команду с заданным именем <command> с указанными аргументами (если таковые имеются). Например, код:

set(message_command "message")
cmake_language(CALL ${message_command} STATUS "Hello World!")

эквивалентен

message(STATUS "Hello World!")

Вычисление кода

cmake_language(EVAL CODE <code>...)

Вычисляет <code>... как код CMake.

Например, код:

set(A TRUE)
set(B TRUE)
set(C TRUE)
set(condition "(A AND B) OR C")

cmake_language(EVAL CODE "
  if (${condition})
    message(STATUS TRUE)
  else()
    message(STATUS FALSE)
  endif()"
)

эквивалентен

set(A TRUE)
set(B TRUE)
set(C TRUE)
set(condition "(A AND B) OR C")

file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake "
  if (${condition})
    message(STATUS TRUE)
  else()
    message(STATUS FALSE)
  endif()"
)

include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake)

Отложенные вызовы

cmake_language(DEFER <options>... CALL <command> [<arg>...])

Планирует вызов команды с заданным именем <command> и аргументами (если таковые имеются) на более позднее время. По умолчанию, отложенные вызовы выполняются как если бы они были записаны в конце файла CMakeLists.txt текущего каталога, за исключением того, что они выполняются даже после вызова return(). Ссылок на переменные в аргументах вычисляются в момент выполнения отложенного вызова.

Опции:

DIRECTORY <dir>

Планирует вызов для конца заданного каталога вместо текущего каталога. Заданный каталог может ссылаться на каталог исходных файлов или соответствующий бинарный каталог. Относительные пути обрабатываются как относительные к текущему каталогу исходных файлов.

Заданный каталог должен быть известен CMake, будучи либо верхним каталогом, либо добавленным командой add_subdirectory(). Кроме того, заданный каталог не должен быть ещё завершён обработкой. Это означает, что он может быть текущим каталогом или одним из его предков.

ID <id>

Указывает идентификатор для отложенного вызова. Идентификатор <id> не может быть пустым и не может начинаться с заглавной буквы A-Z. Идентификатор <id> может начинаться с нижнего подчеркивания (_) только если он был сгенерирован автоматически предыдущим вызовом, который использовал ID_VAR для получения id.

ID_VAR <var>

Указывает переменную для хранения идентификатора отложенного вызова. Если ID <id> не указан, будет сгенерирован новый идентификатор, и сгенерированный id будет начинаться с нижнего подчеркивания (_).

Текущий список запланированных отложенных вызовов может быть получен:

cmake_language(DEFER [DIRECTORY <dir>] GET_CALL_IDS <var>)

Это сохранит в <var> список, разделённый точкой с запятой идентификаторов отложенных вызовов. Идентификаторы относятся к области каталога, в которую были отложены вызовы (т.е. где они будут выполнены), что может отличаться от области, в которой они были созданы. Опция DIRECTORY может быть использована для указания области, для которой необходимо получить идентификаторы вызовов. Если эта опция не указана, будут возвращены идентификаторы вызовов для текущей области каталога.

Подробная информация о конкретном вызове может быть получена по его идентификатору:

cmake_language(DEFER [DIRECTORY <dir>] GET_CALL <id> <var>)

Это сохранит в <var> список, разделённый точкой с запятой, в котором первым элементом является имя вызываемой команды, а оставшиеся элементы - её неуточнённые аргументы (любые содержащиеся символы ; включаются буквально и не могут быть отличимы от нескольких аргументов). Если несколько вызовов запланированы с одним и тем же id, это извлекает первый. Если ни один вызов не запланирован с заданным id в указанной области DIRECTORY (или в текущей области каталога, если опция DIRECTORY не указана), в переменную записывается пустая строка.

Отложенные вызовы могут быть отменены по их id:

cmake_language(DEFER [DIRECTORY <dir>] CANCEL_CALL <id>...)

Это отменяет все отложенные вызовы, соответствующие любым из заданных идентификаторов в указанной области DIRECTORY (или в текущей области каталога, если опция DIRECTORY не указана). Неизвестные идентификаторы игнорируются.

Примеры отложенных вызовов

Например, код:

cmake_language(DEFER CALL message "${deferred_message}")
cmake_language(DEFER ID_VAR id CALL message "Canceled Message")
cmake_language(DEFER CANCEL_CALL ${id})
message("Immediate Message")
set(deferred_message "Deferred Message")

выводит:

Immediate Message
Deferred Message

Переменная Cancelled Message никогда не выводится, потому что её команда отменена. Ссылка на переменную deferred_message не вычисляется до места вызова, поэтому она может быть установлена после планирования отложенного вызова.

Для немедленного вычисления ссылок на переменные при планировании отложенного вызова, оберните его в cmake_language(EVAL). Однако обратите внимание, что аргументы будут повторно вычисляться в отложенном вызове, хотя этого можно избежать с помощью квадратных скобок. Например:

set(deferred_message "Deferred Message 1")
set(re_evaluated [[${deferred_message}]])
cmake_language(EVAL CODE "
  cmake_language(DEFER CALL message [[${deferred_message}]])
  cmake_language(DEFER CALL message \"${re_evaluated}\")
")
message("Immediate Message")
set(deferred_message "Deferred Message 2")

также выводит:

Immediate Message
Deferred Message 1
Deferred Message 2

Поставщики зависимостей

cmake_language(SET_DEPENDENCY_PROVIDER <command>
               SUPPORTED_METHODS <methods>...)

Когда вызывается find_package() или FetchContent_MakeAvailable(), вызов может быть перенаправлен поставщику зависимостей, который затем имеет возможность выполнить запрос. Если запрос относится к одному из <methods> указанных при установке поставщика, CMake вызывает метод <command> поставщика с набором аргументов, специфичных для метода. Если поставщик не выполняет запрос, или если поставщик не поддерживает метод запроса, или поставщик не установлен, встроенная реализация find_package() или FetchContent_MakeAvailable() используется для выполнения запроса обычным способом.

Один или несколько из следующих значений могут быть указаны для <methods> при установке поставщика:

FIND_PACKAGE

Команда поставщика принимает запросы find_package().

FETCHCONTENT_MAKEAVAILABLE_SERIAL

Команда поставщика принимает запросы FetchContent_MakeAvailable(). Она ожидает, что каждая зависимость будет подаваться команде поставщика по одной, а не весь список сразу.

Только один поставщик может быть установлен в любой момент времени. Если поставщик уже установлен при вызове cmake_language(SET_DEPENDENCY_PROVIDER), новый поставщик заменит ранее установленный. Указанный <command> должен уже существовать при вызове cmake_language(SET_DEPENDENCY_PROVIDER). В качестве специального случая, предоставление пустой строки для <command> и отсутствие <methods> отбросит любого ранее установленного поставщика.

Поставщик зависимостей может быть установлен только во время обработки одного из файлов, указанных в переменной CMAKE_PROJECT_TOP_LEVEL_INCLUDES. Таким образом, поставщики зависимостей могут быть установлены только в рамках первого вызова project(). Вызов cmake_language(SET_DEPENDENCY_PROVIDER) вне этого контекста приведёт к ошибке.

Команды поставщика

Поставщики определяют единственную <command> для обработки запросов. Имя команды должно быть специфичным для данного поставщика, а не слишком общим, которое может использовать и другой поставщик. Это позволяет пользователям комбинировать различные поставщики в своих собственных пользовательских поставщиках. Рекомендуемая форма - xxx_provide_dependency(), где xxx - специфическая часть поставщика (например, vcpkg_provide_dependency(), conan_provide_dependency(), ourcompany_provide_dependency(), и так далее).

xxx_provide_dependency(<method> [<method-specific-args>...])

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

Аргументы, которые CMake передаёт поставщику зависимостей, зависят от типа запроса. Первый аргумент всегда является методом, и он будет только одним из <methods> указанных при установке поставщика.

FIND_PACKAGE

Переменные <method-specific-args> будут содержать все, что передано в вызов find_package(), который запросил зависимость. Первым из этих <method-specific-args> всегда будет имя зависимости. Имена зависимостей чувствительны к регистру в этом методе, так как find_package() также обрабатывает их как чувствительные к регистру.

Если команда-поставщик выполняет запрос, она должна установить ту же переменную, которую ожидает find_package(). Для зависимости с именем depName, поставщик должен установить depName_FOUND в значение true, если выполнил запрос. Если поставщик вернётся без установки этой переменной, CMake предположит, что запрос не был выполнен, и вернётся к встроенной реализации.

Если поставщику необходимо вызвать встроенную реализацию find_package() в рамках своей обработки, он может сделать это, включив ключевое слово BYPASS_PROVIDER в качестве одного из аргументов.

FETCHCONTENT_MAKEAVAILABE_SERIAL

Переменные <method-specific-args> будут содержать всё, что передано в вызов FetchContent_Declare(), соответствующий запрошенной зависимости, за исключением следующих пунктов:

• Если SOURCE_DIR или BINARY_DIR не были частью исходных аргументов, они будут добавлены со значениями по умолчанию.
• Если FETCHCONTENT_TRY_FIND_PACKAGE_MODE установлено в значение NEVER, любые FIND_PACKAGE_ARGS будут опущены.
• Ключевое слово OVERRIDE_FIND_PACKAGE всегда опускается.

Первым из <method-specific-args> всегда будет имя зависимости. Имена зависимостей нечувствительны к регистру в этом методе, так как FetchContent также обрабатывает их как нечувствительные к регистру.

Если поставщик выполняет запрос, он должен вызвать FetchContent_SetPopulated(), передавая имя зависимости в качестве первого аргумента. Аргументы SOURCE_DIR и BINARY_DIR к этой команде должны быть переданы только в том случае, если поставщик делает доступными каталоги исходных файлов и сборки зависимости точно так же, как и встроенная команда FetchContent_MakeAvailable().

Если поставщик вернётся без вызова FetchContent_SetPopulated() для указанной зависимости, CMake предположит, что запрос не был выполнен, и вернётся к встроенной реализации.

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

Если FETCHCONTENT_SOURCE_DIR_<uppercaseDepName> установлено, поставщик зависимостей никогда не увидит запросы для зависимости <depName> для этого метода. Когда пользователь устанавливает такую переменную, он явно переопределяет источник получения этой зависимости и несёт ответственность за то, что его переопределённая версия отвечает всем требованиям этой зависимости и совместима со всем остальным в проекте, использующим её. В зависимости от значения FETCHCONTENT_TRY_FIND_PACKAGE_MODE и того, был ли указан параметр OVERRIDE_FIND_PACKAGE в FetchContent_Declare(), установка FETCHCONTENT_SOURCE_DIR_<uppercaseDepName> также может предотвратить получение поставщиком зависимостей запросов для вызова find_package(depName).

Примеры поставщиков

В первом примере перехватываются только вызовы find_package(). Команда поставщика запускает внешнюю утилиту, которая копирует соответствующие артефакты в каталог, специфичный для поставщика, если эта утилита знает о зависимости. Затем она полагается на встроенную реализацию для поиска этих артефактов. Вызовы FetchContent_MakeAvailable() не будут проходить через поставщика.

# Always ensure we have the policy settings this provider expects
cmake_minimum_required(VERSION 3.24)

set(MYCOMP_PROVIDER_INSTALL_DIR ${CMAKE_BINARY_DIR}/mycomp_packages
  CACHE PATH "The directory this provider installs packages to"
)
# Tell the built-in implementation to look in our area first, unless
# the find_package() call uses NO_..._PATH options to exclude it
list(APPEND CMAKE_MODULE_PATH ${MYCOMP_PROVIDER_INSTALL_DIR}/cmake)
list(APPEND CMAKE_PREFIX_PATH ${MYCOMP_PROVIDER_INSTALL_DIR})

macro(mycomp_provide_dependency method package_name)
  execute_process(
    COMMAND some_tool ${package_name} --installdir ${MYCOMP_PROVIDER_INSTALL_DIR}
    COMMAND_ERROR_IS_FATAL ANY
  )
endmacro()

cmake_language(
  SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
  SUPPORTED_METHODS FIND_PACKAGE
)

Пользователь обычно будет использовать вышеуказанный файл следующим образом:

cmake -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=/path/to/mycomp_provider.cmake ...

Следующий пример демонстрирует поставщика, который принимает оба метода, но обрабатывает только одну конкретную зависимость. Он обеспечивает предоставление Google Test с помощью FetchContent, но оставляет все остальные зависимости для выполнения встроенной реализацией CMake. Он принимает несколько разных имён, что демонстрирует один способ работы с проектами, которые жёстко задают необычный или нежелательный способ добавления этой конкретной зависимости в сборку. Пример также демонстрирует, как использовать команду list() для сохранения переменных, которые могут быть перезаписаны вызовом FetchContent_MakeAvailable().

cmake_minimum_required(VERSION 3.24)

# Because we declare this very early, it will take precedence over any
# details the project might declare later for the same thing
include(FetchContent)
FetchContent_Declare(
  googletest
  GIT_REPOSITORY https://github.com/google/googletest.git
  GIT_TAG        e2239ee6043f73722e7aa812a459f54a28552929 # release-1.11.0
)

# Both FIND_PACKAGE and FETCHCONTENT_MAKEAVAILABLE_SERIAL methods provide
# the package or dependency name as the first method-specific argument.
macro(mycomp_provide_dependency method dep_name)
  if("${dep_name}" MATCHES "^(gtest|googletest)$")
    # Save our current command arguments in case we are called recursively
    list(APPEND mycomp_provider_args ${method} ${dep_name})

    # This will forward to the built-in FetchContent implementation,
    # which detects a recursive call for the same thing and avoids calling
    # the provider again if dep_name is the same as the current call.
    FetchContent_MakeAvailable(googletest)

    # Restore our command arguments
    list(POP_BACK mycomp_provider_args dep_name method)

    # Tell the caller we fulfilled the request
    if("${method}" STREQUAL "FIND_PACKAGE")
      # We need to set this if we got here from a find_package() call
      # since we used a different method to fulfill the request.
      # This example assumes projects only use the gtest targets,
      # not any of the variables the FindGTest module may define.
      set(${dep_name}_FOUND TRUE)
    elseif(NOT "${dep_name}" STREQUAL "googletest")
      # We used the same method, but were given a different name to the
      # one we populated with. Tell the caller about the name it used.
      FetchContent_SetPopulated(${dep_name}
        SOURCE_DIR "${googletest_SOURCE_DIR}"
        BINARY_DIR "${googletest_BINARY_DIR}"
      )
    endif()
  endif()
endmacro()

cmake_language(
  SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
  SUPPORTED_METHODS
    FIND_PACKAGE
    FETCHCONTENT_MAKEAVAILABLE_SERIAL
)

Последний пример демонстрирует, как изменить аргументы вызова find_package(). Он принудительно добавляет ключевое слово QUIET ко всем таким вызовам. Он использует ключевое слово BYPASS_PROVIDER для предотвращения рекурсивного вызова команды поставщика для той же зависимости.

cmake_minimum_required(VERSION 3.24)

macro(mycomp_provide_dependency method)
  find_package(${ARGN} BYPASS_PROVIDER QUIET)
endmacro()

cmake_language(
  SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
  SUPPORTED_METHODS FIND_PACKAGE
)