C++ 库 - Gradle 中文

C++ 库插件与配置缓存不兼容。

C++ 库插件提供了构建 C++ 库的任务、约定和约定。特别是，C++ 库提供了可供使用者（即使用此插件或 C++ 应用程序插件的其他项目）使用的功能。

用法

build.gradle.kts

plugins {
    `cpp-library`
}

build.gradle

plugins {
    id 'cpp-library'
}

构建变体

C++ 库插件理解以下维度。阅读构建变体简介以了解更多信息。

构建类型 - 始终设置为 debug 和 release

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

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

链接 - 默认设置为 shared

链接表示应该创建共享库还是静态库。库可以生成共享库、静态库或两者。

链接可以按如下方式配置

示例 2. 配置库链接

build.gradle.kts

library {
    linkage = listOf(Linkage.STATIC, Linkage.SHARED)
}

build.gradle

library {
    linkage = [Linkage.STATIC, Linkage.SHARED]
}

目标机器 - 默认值为构建主机: 目标机器表示应用程序预期运行的机器。目标机器由其操作系统和体系结构标识。Gradle 使用目标机器来决定根据主机上的可用性选择哪个工具链。

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

示例 3. 配置库目标机器

build.gradle.kts

library {
    targetMachines = listOf(machines.linux.x86_64,
        machines.windows.x86, machines.windows.x86_64,
        machines.macOS.x86_64)
}

build.gradle

library {
    targetMachines = [
        machines.linux.x86_64,
        machines.windows.x86, machines.windows.x86_64,
        machines.macOS.x86_64
    ]
}

任务

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

请注意，C++ 库的默认链接是共享链接，如图表所示。

图 1. C++ 库插件默认任务图

使用静态链接时，图表将更改为以下内容

图 2. C++ 库插件静态库仅任务图

变体相关任务

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

图 3. C++ 库插件变体相关任务图

根据链接属性

compileVariantCpp（例如 compileDebugCpp 和 compileReleaseCpp） - CppCompile: 依赖于：所有为编译贡献源文件的任务 :: 使用选定的编译器编译 C++ 源文件。
linkVariant（例如 linkDebug 和 linkRelease） - LinkSharedLibrary（共享链接）: 依赖于：所有为链接库做出贡献的任务，包括来自通过项目依赖项解析的项目的 linkVariant 和 createVariant 任务 :: 使用选定的链接器从编译后的目标文件链接共享库。
createVariant（例如 createDebug 和 createRelease） - CreateStaticLibrary（静态链接）: 使用选定的归档器从编译后的目标文件创建静态库
assembleVariant（例如 assembleDebug 和 assembleRelease） - 任务（生命周期）: 依赖于：linkVariant（共享链接）或 createVariant（静态链接） :: 聚合组装此库特定变体的任务。

生命周期任务

C++ 库插件将其某些任务附加到基本插件章节中记录的标准生命周期任务 - C++ 库插件会自动应用这些任务

assemble - 任务（生命周期）: 依赖于：当链接包含 shared 时为 linkDebug，否则为 createDebug。 :: 聚合任务，用于组装项目中当前主机（如果存在）的共享库的调试变体（如果可用）。此任务由基本插件添加。
check - 任务（生命周期）: 聚合任务，执行验证任务，例如运行测试。一些插件会向check添加自己的验证任务。例如，C++ 单元测试插件将其测试任务附加到此生命周期任务。此任务由基础插件添加。
build - 任务（生命周期）: 依赖于：check、assemble :: 聚合任务，执行项目的完整构建。此任务由基础插件添加。
clean - 删除: 删除构建目录及其中的所有内容，即由layout.buildDirectory项目属性指定的路径。此任务由基础插件添加。

依赖管理

与 C++ 库插件创建的任务类似，会根据库组件的变体创建多个配置。阅读构建变体简介以了解更多信息。以下图表描述了 C++ 库插件添加的配置

图 4. C++ 库插件配置

白色配置是用户应用来声明依赖项的配置
粉色配置，也称为可消费配置，用 (C) 表示，是在组件编译、链接或针对库运行时使用的配置
蓝色配置，也称为可解析配置，用 (R) 表示，是组件内部使用的配置

以下配置用于声明依赖项

api: 用于声明 API 依赖项（参见API 与实现部分）。您应该在此处声明传递给消费者的依赖项，用于编译和链接。
implementation 扩展 api: 用于声明主组件所有变体的实现依赖项（参见API 与实现部分）。您应该在此处声明纯粹的内部依赖项，这些依赖项不打算公开给任何变体的消费者。
mainVariantImplementation（例如 mainDebugImplementation 和 mainReleaseImplementation）扩展 implementation: 用于声明主组件特定变体的实现依赖项（参见 API 与实现部分）。这里应该声明纯粹的内部依赖项，这些依赖项不应暴露给此特定变体的使用者。

以下配置由使用者使用

cppApiElements 扩展 mainVariantImplementation: 用于针对库进行编译。此配置旨在供使用者使用，以检索编译库所需的所有元素。
variantLinkElements（例如 debugLinkElements 和 releaseLinkElements）扩展 mainVariantImplementation: 用于链接库。此配置旨在供使用者使用，以检索链接库所需的所有元素。
variantRuntimeElements（例如 debugRuntimeElements 和 releaseRuntimeElements）扩展 mainVariantImplementation: 用于执行库。此配置旨在供使用者使用，以检索运行库所需的所有元素。

以下配置由库本身使用

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

API 与实现

该插件公开了两种可用于声明依赖项的配置：api 和 implementation。 api 配置应用于声明库 API 导出的依赖项，而 implementation 配置应用于声明组件内部的依赖项。

示例 4. 添加依赖项

build.gradle.kts

library {
    dependencies {
        api("io.qt:core:5.1")
        implementation("io.qt:network:5.1")
    }
}

build.gradle

library {
    dependencies {
        api "io.qt:core:5.1"
        implementation "io.qt:network:5.1"
    }
}

在api配置中出现的依赖项将被传递性地暴露给库的使用者，因此将出现在使用者的编译包含根目录和链接库中。另一方面，在implementation配置中找到的依赖项不会暴露给使用者，因此不会泄漏到使用者的编译包含根目录和链接库中。这带来了一些好处。

依赖项不会泄漏到使用者的编译包含根目录和链接库中，因此它们永远不会意外地依赖于传递依赖项。
由于包含根目录和链接库减少，因此编译速度更快。
当实现依赖项发生变化时，重新编译次数更少，因为使用者不需要重新编译。

约定

C++ 库插件为源代码和任务添加了约定，如下所示。

项目布局

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

src/main/cpp: 具有.cpp、.C++或.cc扩展名的 C++ 源代码
src/main/headers: 私有头文件 - 编译库所需的但使用者不需要的头文件
src/main/public: 公共头文件 - 编译库所需的并且使用者需要的头文件

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

`compileVariantCpp` 任务

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

compilerArgs	[]
可调试	`true`
包含	`configurations.cppCompileVariant` + `library.publicHeaders` + `library.privateHeaders`
宏	[:]
目标文件目录	`layout.buildDirectory.dir("obj/main/$variant")`
优化	调试构建类型为`false`，其他情况为`true`
位置无关代码	共享链接为`true`，其他情况为`false`
源代码	`library.cppSource`
系统包含	从工具链派生
目标平台	从二进制文件的`TargetMachine`派生
工具链	根据目标机器自动选择

`linkVariant` 任务

C++ 库插件为库的每个变体添加了一个 LinkSharedLibrary 实例，其中包含共享链接作为维度 - 例如 linkDebug 和 linkRelease。有关更多信息，请阅读构建变体介绍。下面显示了一些最常见的配置选项。

可调试	`true`
库	`configurations.nativeLinkVariant`
链接文件	`layout.buildDirectory.dir("lib/main/$variant/libBaseName[.so\|dylib]")` (*nix) 或 `layout.buildDirectory.dir("lib\main\$variant\baseName.dll")` (Windows)
链接器参数	[]
源代码	`compileVariantCpp.objects`
目标平台	从二进制文件的`TargetMachine`派生
工具链	根据目标机器自动选择

`createVariant` 任务

C++ 库插件为库的每个变体添加了一个 CreateStaticLibrary 实例，其中包含静态链接作为维度 - 例如 createDebug 和 createRelease。有关更多信息，请阅读构建变体介绍。下面显示了一些最常见的配置选项。

输出文件	`layout.buildDirectory.dir("lib/main/variant/libBaseName.a")` (*nix) 或 `layout.buildDirectory.dir("lib\main\variant\baseName.lib")` (Windows)
源代码	`compileVariantCpp.objects`
静态库参数	[]
目标平台	从二进制文件的`TargetMachine`派生
工具链	根据目标机器自动选择

此页面对您有帮助吗？