C++ 应用 - Gradle 构建系统

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

用法

build.gradle.kts

plugins {
    `cpp-application`
}

build.gradle

plugins {
    id 'cpp-application'
}

构建变体

C++ 应用插件理解以下维度。请阅读构建变体介绍以获取更多信息。

构建类型 - 始终是 debug 或 release

构建类型控制生成二进制文件的调试能力和优化级别。

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

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

目标机器表示应用预期在哪种机器上运行。目标机器通过其操作系统和架构标识。Gradle 根据主机上可用的工具链来决定选择哪个工具链。

目标机器可以如下配置

示例 2. 配置应用目标机器

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
    ]
}

任务

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

图 1. C++ 应用插件默认任务图

变体相关任务

C++ 应用插件根据应用组件的变体创建任务。请阅读构建变体介绍以获取更多信息。下图显示了变体相关任务之间的关系。

图 2. C++ 应用插件变体相关任务图

compileVariantCpp (例如 compileDebugCpp 和 compileReleaseCpp) - CppCompile: 依赖于：所有为编译提供源文件的任务 :: 使用选定的编译器编译 C++ 源文件。
linkVariant (例如 linkDebug 和 linkRelease) - LinkExecutable: 依赖于：所有有助于链接可执行文件的任务，包括通过项目依赖项解析的项目中的 linkVariant 和 createVariant 任务 :: 使用选定的链接器从已编译的目标文件链接生成可执行文件。
installVariant (例如 installDebug 和 installRelease) - InstallExecutable: 依赖于：linkVariant 和所有有助于可执行文件运行时的任务，包括通过项目依赖项解析的项目中的 linkVariant 任务 :: 安装可执行文件及其所有运行时依赖项，以便轻松执行。
assembleVariant (例如 assembleDebug 和 assembleRelease) - 任务 (生命周期): 依赖于：linkVariant :: 聚合了用于组装此应用特定变体的任务。

生命周期任务

C++ 应用插件将其部分任务附加到基础插件章节中记录的标准生命周期任务 - C++ 应用插件会自动应用基础插件

assemble - 任务 (生命周期): 依赖于：linkDebug :: 聚合任务，用于在项目中（如果存在）为当前主机组装应用的 debug 变体。此任务由基础插件添加。
check - 任务 (生命周期): 聚合任务，执行验证任务，例如运行测试。一些插件将自己的验证任务添加到 check 中。例如，C++ 单元测试插件将一个任务附加到此生命周期任务以运行测试。此任务由基础插件添加。
build - 任务 (生命周期): 依赖于：check, assemble :: 聚合任务，执行项目的完整构建。此任务由基础插件添加。
clean - 删除: 删除构建目录及其中的所有内容，即由项目属性 layout.buildDirectory 指定的路径。此任务由基础插件添加。

依赖管理

与 C++ 应用插件创建的任务类似，还会根据应用组件的变体创建多个配置。请阅读构建变体介绍以获取更多信息。下图描述了 C++ 应用插件添加的配置

图 3. C++ 应用插件配置

白色方框中的配置是用户应该用来声明依赖项的配置
粉色方框中的配置，也称为可消费配置，用 (C) 表示，用于组件依赖于此库时
蓝色方框中的配置，也称为可解析配置，用 (R) 表示，是组件内部使用，供其自身使用

以下配置用于声明依赖项

implementation: 用于声明主组件所有变体的实现依赖项。这是您应该声明任何变体依赖项的地方。
mainVariantImplementation (例如 mainDebugImplementation 和 mainReleaseImplementation) 扩展自 implementation: 用于声明主组件特定变体的实现依赖项。这是您应该声明特定变体依赖项的地方。

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

variantRuntimeElements (例如 debugRuntimeElements 和 releaseRuntimeElements) 扩展自 `mainVariantImplementation: 用于执行应用。此配置旨在供消费者使用，以获取运行应用所需的所有元素。

以下配置由应用自身使用

cppCompileVariant (例如 cppCompileDebug 和 cppCompileRelease) 扩展自 mainVariantImplementation: 用于编译应用。此配置包含应用的编译包含根目录，因此在调用 C++ 编译器编译应用时使用。
nativeLinkVariant (例如 nativeLinkDebug 和 nativeLinkRelease) 扩展自 mainVariantImplementation: 用于链接应用。此配置包含应用的库，因此在调用 C++ 链接器链接应用时使用。
nativeRuntimeVariant (例如 nativeRuntimeDebug 和 nativeRuntimeRelease) 扩展自 mainVariantImplementation: 用于执行应用。此配置包含应用的运行时库。

约定

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

项目布局

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

src/main/cpp: 后缀为 .cpp、.c++ 或 .cc 的 C++ 源代码
src/main/headers: 头文件 - 编译应用所需的头文件

您可以通过在 application 脚本块上分别配置 source 和 privateHeaders 来配置项目布局。

`compileVariantCpp` 任务

C++ 应用插件为要构建的应用组件的每个变体添加了一个 CppCompile 实例（例如 compileDebugCpp 和 compileReleaseCpp）。请阅读构建变体介绍以获取更多信息。下面显示了一些最常见的配置选项。

compilerArgs	[]
debuggable	`true`
includes	`configurations.cppCompileVariant` + `application.privateHeaders`
macros	[:]
objectFileDir	`layout.buildDirectory.dir("obj/main/$variant")`
optimized	debug 构建类型为 `false`，否则为 `true`
positionIndependentCode	`false`
source	`application.cppSource`
systemIncludes	从工具链派生
targetPlatform	从二进制文件的 `TargetMachine` 派生
toolChain	根据目标机器自动选择

`linkVariant` 任务

C++ 应用插件为应用的每个变体添加了一个 LinkExecutable 实例 — 例如 linkDebug 和 linkRelease。请阅读构建变体介绍以获取更多信息。下面显示了一些最常见的配置选项。

debuggable	`true`
libs	`configurations.nativeLinkVariant`
linkedFile	`layout.buildDirectory.dir("exe/main/$variant/baseName")` (*nix) 或 `layout.buildDirectory.dir("exe\main\$variant\baseName.exe")` (Windows)
linkerArgs	[]
source	`compileVariantCpp.objects`
targetPlatform	从二进制文件的 `TargetMachine` 派生
toolChain	根据目标机器自动选择

`installVariant` 任务

C++ 应用插件为测试组件的每个变体添加了一个 InstallExecutable 实例 — 例如 installDebug 和 installRelease。请阅读构建变体介绍以获取更多信息。无需在该任务上配置任何属性。

本页是否有帮助？