C++ 应用程序插件提供用于构建 C++ 应用程序的任务、配置和约定。

用法

build.gradle.kts
plugins {
    `cpp-application`
}
build.gradle
plugins {
    id 'cpp-application'
}

构建变体

C++ 应用程序插件理解以下维度。有关更多信息,请阅读构建变体介绍

构建类型 - 始终为 debugrelease

构建类型控制生成二进制文件的可调试性以及优化。

  • debug - 生成调试符号且不优化二进制文件

  • release - 生成调试符号并优化,但从二进制文件中提取调试符号

目标机器 - 默认为构建主机

目标机器表示应用程序期望运行的机器。目标机器由其操作系统和架构标识。Gradle 根据主机机器上的可用性选择工具链。

目标机器可以按如下方式配置

build.gradle.kts
application {
    targetMachines = listOf(machines.linux.x86_64,
        machines.windows.x86, machines.windows.x86_64,
        machines.macOS.x86_64)
}
build.gradle
application {
    targetMachines = [
        machines.linux.x86_64,
        machines.windows.x86, machines.windows.x86_64,
        machines.macOS.x86_64
    ]
}

任务

下图显示了此插件添加的任务之间的关系。

cpp application task graph
图 1. C++ 应用程序插件默认任务图

依赖于变体的任务

C++ 应用程序插件根据应用程序组件的变体创建任务。有关更多信息,请阅读构建变体介绍。下图显示了依赖于变体的任务之间的关系。

cpp application variant task graph
图 2. C++ 应用程序插件依赖于变体的任务图
compileVariantCpp (例如 compileDebugCppcompileReleaseCpp) - CppCompile

依赖于:所有为编译贡献源文件的任务 :: 使用选定的编译器编译 C++ 源文件。

linkVariant (例如 linkDebuglinkRelease) - LinkExecutable

依赖于:所有有助于链接可执行文件的任务,包括通过项目依赖项解析的项目中的 linkVariantcreateVariant 任务 :: 使用选定的链接器从编译的对象文件链接可执行文件。

installVariant (例如 installDebuginstallRelease) - InstallExecutable

依赖于:linkVariant 和所有有助于可执行文件运行时的任务,包括通过项目依赖项解析的项目中的 linkVariant 任务 :: 安装可执行文件及其所有运行时依赖项,以便于执行。

assembleVariant(例如 assembleDebugassembleRelease)- 任务(生命周期)

依赖于:linkVariant :: 聚合组装此应用程序特定变体的任务。

生命周期任务

C++ 应用程序插件将其一些任务附加到 Base Plugin 章中记录的标准生命周期任务 - C++ 应用程序插件会自动应用该插件

assemble - 任务(生命周期)

依赖于:linkDebug :: 聚合任务,用于组装项目中当前主机(如果存在)的应用程序调试变体。此任务由 Base Plugin 添加。

check - 任务(生命周期)

聚合任务,执行验证任务,例如运行测试。一些插件将其自己的验证任务添加到 check。例如,C++ 单元测试插件将一个任务附加到此生命周期任务以运行测试。此任务由 Base Plugin 添加。

build - 任务(生命周期)

依赖于:check, assemble :: 执行项目完整构建的聚合任务。此任务由 Base 插件添加。

clean - 删除

删除构建目录及其中的所有内容,即 layout.buildDirectory 项目属性指定的路径。此任务由 Base 插件添加。

依赖管理

就像 C++ 应用程序插件创建的任务一样,根据应用程序组件的变体创建多个配置。有关更多信息,请阅读构建变体介绍。下图描述了 C++ 应用程序插件添加的配置。

cpp application configurations
图 3. C++ 应用程序插件配置
  • 白色配置是用户应该用来声明依赖项的配置

  • 粉色配置,也称为可消费配置(用 (C) 表示),是当组件针对库运行时使用的配置。

  • 蓝色配置,也称为可解析配置,用 (R) 表示,是组件内部使用的配置

以下配置用于声明依赖项

实现

用于声明主组件所有变体的实现依赖项。您应该在此处声明任何变体的依赖项。

mainVariantImplementation(例如 mainDebugImplementationmainReleaseImplementation)扩展 implementation

用于声明主组件特定变体的实现依赖项。您应该在此处声明特定变体的依赖项。

以下配置由依赖于应用程序组件的下游消费者使用

variantRuntimeElements(例如 debugRuntimeElementsreleaseRuntimeElements)扩展 mainVariantImplementation

用于执行应用程序。此配置旨在供消费者使用,以检索运行应用程序所需的所有元素。

以下配置由应用程序本身使用

cppCompileVariant (例如 cppCompileDebugcppCompileRelease) 扩展 mainVariantImplementation

用于编译应用程序。此配置包含应用程序的编译包含根,因此在调用 C++ 编译器编译时使用。

nativeLinkVariant(例如 nativeLinkDebugnativeLinkRelease)扩展 mainVariantImplementation

用于链接应用程序。此配置包含应用程序的库,因此在调用 C++ 链接器链接时使用。

nativeRuntimeVariant(例如 nativeRuntimeDebugnativeRuntimeRelease)扩展 mainVariantImplementation

用于执行应用程序。此配置包含应用程序的运行时库。

约定

C++ 应用程序插件添加了源代码和任务的约定,如下所示。

项目布局

C++ 应用程序插件假定以下项目布局。这些目录都不需要存在或包含任何内容。C++ 应用程序插件将编译它找到的任何内容并忽略任何缺失的内容。

src/main/cpp

扩展名为 .cpp.c++.cc 的 C++ 源文件

src/main/headers

头文件 - 编译应用程序所需的头文件

您可以通过在 application 脚本块上分别配置 sourceprivateHeaders配置项目布局

compileVariantCpp 任务

C++ 应用程序插件为要构建的应用程序组件的每个变体(例如 compileDebugCppcompileReleaseCpp)添加一个 CppCompile 实例。有关更多信息,请阅读构建变体介绍。下面显示了一些最常见的配置选项。

编译器参数

[]

可调试

true

包含

configurations.cppCompileVariant + application.privateHeaders

[:]

目标文件目录

layout.buildDirectory.dir("obj/main/$variant")

优化

调试构建类型为 false,否则为 true

位置独立代码

false

application.cppSource

系统包含

从工具链派生

目标平台

从二进制文件的 TargetMachine 派生

工具链

根据目标机器自动选择

C++ 应用程序插件为应用程序的每个变体(例如 linkDebuglinkRelease)添加一个 LinkExecutable 实例。有关更多信息,请阅读构建变体介绍。下面显示了一些最常见的配置选项。

可调试

true

configurations.nativeLinkVariant

链接文件

layout.buildDirectory.dir("exe/main/$variant/baseName") (Unix) 或 layout.buildDirectory.dir("exe\main\$variant\baseName.exe") (Windows)

链接器参数

[]

compileVariantCpp.objects

目标平台

从二进制文件的 TargetMachine 派生

工具链

根据目标机器自动选择

installVariant 任务

C++ 应用程序插件为测试组件的每个变体(例如 installDebuginstallRelease)添加一个 InstallExecutable 实例。有关更多信息,请阅读构建变体介绍。无需配置任务上的任何属性。