构建 C++ 项目 - Gradle 构建系统

Gradle 在构建原生项目时采用“约定优于配置”的方法。如果您来自另一个原生构建系统，这些概念起初可能不太熟悉，但它们旨在简化构建脚本的编写。

在本章中，我们将详细介绍 C++ 项目，但大多数主题也适用于其他受支持的原生语言。如果您在使用 Gradle 构建原生项目方面没有太多经验，请查看 C++ 教程，其中包含关于如何构建各种类型的基本 C++ 项目以及一些常见用例的分步说明。

本章介绍的 C++ 插件是在 2018 年引入的，我们建议用户使用这些插件，而不是您可能找到引用的较旧的 Native 插件。

介绍

C++ 项目最简单的构建脚本是应用 C++ 应用程序插件或 C++ 库插件，并可选择性地设置项目版本

build.gradle.kts

plugins {
    `cpp-application` // or `cpp-library`
}

version = "1.2.1"

build.gradle

plugins {
    id 'cpp-application' // or 'cpp-library'
}

version = '1.2.1'

通过应用任一 C++ 插件，您将获得一系列功能

compileDebugCpp 和 compileReleaseCpp 任务，分别用于为众所周知的 debug 和 release 构建类型编译 src/main/cpp 下的 C++ 源文件。
linkDebug 和 linkRelease 任务，用于将编译后的 C++ 目标文件链接到可执行文件（用于应用程序）或共享库（用于具有共享链接的库），分别对应 debug 和 release 构建类型。
createDebug 和 createRelease 任务，用于将编译后的 C++ 目标文件组装成静态库（用于具有静态链接的库），分别对应 debug 和 release 构建类型。

对于任何非平凡的 C++ 项目，您可能需要一些文件依赖项和特定于您的项目的额外配置。

C++ 插件还将上述任务集成到标准的生命周期任务中。生成开发二进制文件的任务附加到 assemble。默认情况下，开发二进制文件是 debug 变体。

本章的其余部分解释了在构建库和应用程序时，根据您的需求自定义构建的不同方法。

介绍构建变体

原生项目通常可以生成几种不同的二进制文件，例如 debug 或 release 版本，或者针对特定平台和处理器架构的版本。Gradle 通过维度和变体的概念来管理这一点。

维度只是一个类别，其中每个类别都与其他类别正交。例如，“构建类型”维度是一个包含 debug 和 release 的类别。“架构”维度涵盖处理器架构，如 x86-64 和 PowerPC。

变体是这些维度的值的组合，每个维度恰好包含一个值。您可能有一个“debug x86-64”或一个“release PowerPC”变体。

Gradle 内置支持多个维度和每个维度内的多个值。您可以在原生插件参考章节中找到它们的列表。

声明你的源文件

Gradle 的 C++ 支持直接从 application 或 library 脚本块使用 ConfigurableFileCollection 来配置要编译的源文件集。

库区分私有（实现细节）和公共（导出给消费者）头文件。

您还可以为每个二进制构建配置源文件，以用于仅在某些目标机器上编译源文件的情况。

图 1. 源文件和 C++ 编译

测试源文件在每个测试套件脚本块上配置。请参阅测试 C++ 项目章节。

管理你的依赖

绝大多数项目都依赖于其他项目，因此管理项目的依赖项是构建任何项目的重要组成部分。依赖管理是一个很大的主题，因此我们在这里只关注 C++ 项目的基础知识。如果您想深入了解细节，请查看依赖管理介绍。

Gradle 提供支持，用于从 Gradle 发布的 Maven 仓库中消费预构建的二进制文件 ^[1]。

我们将介绍如何在多构建项目中的项目之间添加依赖项。

为您的 C++ 项目指定依赖项需要两条信息

依赖项的标识信息（项目路径、Maven GAV）
需要它的目的，例如编译、链接、运行时或以上所有。

此信息在 C++ application 或 library 脚本块的 dependencies {} 块中指定。例如，要告诉 Gradle 您的项目需要库 common 来编译和链接您的生产代码，您可以使用以下代码片段

示例 2. 声明依赖

build.gradle.kts

application {
    dependencies {
        implementation(project(":common"))
    }
}

build.gradle

application {
    dependencies {
        implementation project(':common')
    }
}

Gradle 对这三个元素的术语如下

配置 (例如：implementation) - 依赖项的命名集合，为了特定目标（例如编译或链接模块）而分组在一起
项目引用 (例如：project(':common')) - 由指定路径引用的项目

您可以在此处找到更全面的依赖管理术语表。

就配置而言，主要关注的是

implementation - 用于编译、链接和运行时
cppCompileVariant - 用于编译生产代码所必需但 *不应* 成为链接或运行时过程一部分的依赖项
nativeLinkVariant - 用于链接代码所必需但 *不应* 成为编译或运行时过程一部分的依赖项
nativeRuntimeVariant - 用于运行组件所必需但 *不应* 成为编译或链接过程一部分的依赖项

您可以在原生插件参考章节中了解更多关于这些以及它们之间如何关联的信息。

请注意，C++ 库插件创建了一个额外的配置 — api — 用于编译和链接模块以及任何依赖于它的模块所需的依赖项。

我们在这里只触及了表面，因此我们建议您在熟悉使用 Gradle 构建 C++ 项目的基础知识后，阅读专门的依赖管理章节。

一些需要进一步阅读的常见场景包括

定义自定义的 Maven 兼容仓库
声明具有 changing（例如 SNAPSHOT）和 dynamic（范围）版本的依赖项
声明同级项目作为依赖项
控制传递依赖及其版本
通过复合构建测试您对第三方依赖项的修复（比发布到和消费来自 Maven Local 更好的替代方案）

您将发现 Gradle 拥有丰富的 API 用于处理依赖项 — 掌握它需要时间，但对于常见场景来说使用起来很简单。

编译和链接你的代码

如果您遵循约定，编译代码可以非常容易

将您的源代码放在 src/main/cpp 目录下
在 implementation 配置中声明您的编译依赖项（请参阅上一节）
运行 assemble 任务

我们建议您尽可能遵循这些约定，但这不是强制性的。

接下来您将看到，有几种自定义选项。

所有 CppCompile 任务都是增量且可缓存的。

支持的工具链

Gradle 提供了使用不同工具链执行相同构建的能力。当您构建原生二进制文件时，Gradle 将尝试在您的机器上找到一个可以构建该二进制文件的工具链。Gradle 选择第一个可以为目标操作系统和架构构建的工具链。未来，Gradle 在选择工具链时将考虑源代码和 ABI 兼容性。

Gradle 通用支持主要操作系统上的三个主要工具链：Clang ^[2]、GCC ^[3] 和 Visual C++ ^[4]（仅限 Windows）。据报告，使用 Macports 和 Homebrew 安装的 GCC 和 Clang 可以正常工作，但这并未持续测试。

Windows

要在 Windows 上构建，请安装兼容版本的 Visual Studio。C++ 插件将发现 Visual Studio 安装并选择最新版本。如果自动发现不起作用，您可以使用 toolChains 块配置 Visual Studio。

示例 3. 手动配置 Visual Studio

build.gradle.kts

toolChains{
    withType<VisualCpp>().configureEach {
        setInstallDir("C:\\Program Files (x86)\\Microsoft Visual Studio\\2022\\BuildTools")
    }
}

build.gradle

toolChains{
    withType(VisualCpp).configureEach {
        setInstallDir('C:\\Program Files (x86)\\Microsoft Visual Studio\\2022\\BuildTools')
    }
}

或者，您可以安装带有 GCC 的 Cygwin 或 MinGW。目前不支持 Clang。

macOS

要在 macOS 上构建，您应该安装 Xcode。C++ 插件将使用系统 PATH 发现 Xcode 安装。

C++ 插件也适用于使用 Macports 或 Homebrew 安装的 GCC 和 Clang ^[5]。要使用 Macports 或 Homebrew 之一，您需要将 Macports/Homebrew 添加到系统 PATH 中。

Linux

要在 Linux 上构建，请安装兼容版本的 GCC 或 Clang。C++ 插件将使用系统 PATH 发现 GCC 或 Clang。

自定义文件和目录位置

假设您有一个遗留库项目，该项目使用 src 目录用于生产代码和私有头文件，使用 include 目录用于导出的头文件。传统的目录结构不起作用，因此您需要告诉 Gradle 在哪里可以找到源文件和头文件。您可以通过 application 或 library 脚本块来做到这一点。

每个组件脚本块以及每个二进制文件都定义了其源代码所在的位置。您可以使用以下语法覆盖约定值

示例 4. 设置 C++ 源文件集

build.gradle.kts

library {
    source.from(file("src"))
    privateHeaders.from(file("src"))
    publicHeaders.from(file("include"))
}

build.gradle

library {
    source.from file('src')
    privateHeaders.from file('src')
    publicHeaders.from file('include')
}

现在 Gradle 将仅直接在 src 中搜索源文件和私有头文件，并在 include 中搜索公共头文件。

更改编译器和链接器选项

大多数编译器和链接器选项都可以通过相应的任务访问，例如 compileVariantCpp、linkVariant 和 createVariant。这些任务分别是 CppCompile、LinkSharedLibrary 和 CreateStaticLibrary 类型。请阅读任务参考以获取最新且全面的选项列表。

例如，如果您想更改编译器为所有变体生成的警告级别，您可以使用此配置

示例 5. 为所有变体设置 C++ 编译器选项

build.gradle.kts

tasks.withType(CppCompile::class.java).configureEach {
    // Define a preprocessor macro for every binary
    macros.put("NDEBUG", null)

    // Define a compiler options
    compilerArgs.add("-W3")

    // Define toolchain-specific compiler options
    compilerArgs.addAll(toolChain.map { toolChain ->
        when (toolChain) {
            is Gcc, is Clang -> listOf("-O2", "-fno-access-control")
            is VisualCpp -> listOf("/Zi")
            else -> listOf()
        }
    })
}

build.gradle

tasks.withType(CppCompile).configureEach {
    // Define a preprocessor macro for every binary
    macros.put("NDEBUG", null)

    // Define a compiler options
    compilerArgs.add '-W3'

    // Define toolchain-specific compiler options
    compilerArgs.addAll toolChain.map { toolChain ->
        if (toolChain in [ Gcc, Clang ]) {
            return ['-O2', '-fno-access-control']
        } else if (toolChain in VisualCpp) {
            return ['/Zi']
        }
        return []
    }
}

也可以通过 application 或 library 脚本块上的 BinaryCollection 找到特定变体的实例。

示例 6. 为每个变体设置 C++ 编译器选项

build.gradle.kts

application {
    binaries.configureEach(CppStaticLibrary::class.java) {
        // Define a preprocessor macro for every binary
        compileTask.get().macros.put("NDEBUG", null)

        // Define a compiler options
        compileTask.get().compilerArgs.add("-W3")

        // Define toolchain-specific compiler options
        when (toolChain) {
            is Gcc, is Clang -> compileTask.get().compilerArgs.addAll(listOf("-O2", "-fno-access-control"))
            is VisualCpp -> compileTask.get().compilerArgs.add("/Zi")
        }
    }
}

build.gradle

application {
    binaries.configureEach(CppStaticLibrary) {
        // Define a preprocessor macro for every binary
        compileTask.get().macros.put("NDEBUG", null)

        // Define a compiler options
        compileTask.get().compilerArgs.add '-W3'

        // Define toolchain-specific compiler options
        if (toolChain in [ Gcc, Clang ]) {
            compileTask.get().compilerArgs.addAll(['-O2', '-fno-access-control'])
        } else if (toolChain in VisualCpp) {
            compileTask.get().compilerArgs.add('/Zi')
        }
    }
}

选择目标机器

默认情况下，Gradle 将尝试为主机操作系统和架构创建一个 C++ 二进制变体。可以通过在 application 或 library 脚本块上指定 TargetMachine 集来覆盖此默认行为。

示例 7. 设置目标机器

build.gradle.kts

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

build.gradle

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

打包和发布

在原生世界中，您如何打包和可能发布您的 C++ 项目差异很大。Gradle 带有默认设置，但自定义打包可以毫无问题地实现。

可执行文件直接发布到 Maven 仓库。
共享库和静态库文件直接发布到 Maven 仓库，并附带公共头文件的 zip 文件。
对于应用程序，Gradle 还支持在已知位置安装和运行可执行文件及其所有共享库依赖项。

清理构建

C++ 应用程序和库插件通过使用 base 插件向您的项目添加 clean 任务。此任务只是删除 layout.buildDirectory 目录中的所有内容，因此您应该始终将构建生成的文件放在那里。该任务是 Delete 的一个实例，您可以通过设置其 dir 属性来更改它删除的目录。

构建 C++ 库

库项目的一个独特方面是它们被其他 C++ 项目使用（或“消费”）。这意味着与二进制文件和头文件一起发布的依赖项元数据 — 以 Gradle 模块元数据的形式 — 至关重要。特别是，您的库的消费者应该能够区分两种不同类型的依赖项：仅编译您的库所需的依赖项和编译消费者也需要的依赖项。

Gradle 通过 C++ 库插件管理这种区别，该插件除了本章前面介绍的 implementation 配置之外，还引入了 api 配置。如果来自依赖项的类型在静态库的未解析符号或公共头文件中出现，则该依赖项通过库的公共 API 公开，因此应将其添加到 api 配置中。否则，该依赖项是内部实现细节，应添加到 implementation 中。

如果您不确定 API 和实现依赖项之间的区别，C++ 库插件章节有详细的解释。此外，您可以在相应的示例中看到构建 C++ 库的基本实用示例。

构建 C++ 应用程序

有关更多详细信息，请参阅 C++ 应用程序插件章节，但这里简要概述了您获得的内容

install 创建一个目录，其中包含运行它所需的一切
用于启动应用程序的 Shell 和 Windows 批处理脚本

您可以在相应的示例中看到构建 C++ 应用程序的基本示例。

1. 遗憾的是，Conan 和 Nuget 仓库尚不支持作为核心功能。

2. 与 macOS 上的 Xcode 一起安装

3. 通过 Cygwin 和 MinGW 安装，用于 Windows 上 32 位和 64 位架构

4. 与 Visual Studio 2010 至 2019 一起安装

5. Macports 和 Homebrew 安装的 GCC 和 Clang 未获得官方支持

此页是否对您有帮助？