构建 Swift 项目 - Gradle 构建系统

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

本章将详细介绍 Swift 项目，但大多数主题也适用于其他受支持的原生语言。

简介

最简单的 Swift 项目构建脚本应用 Swift 应用程序插件或 Swift 库插件，并可选地设置项目版本。

build.gradle.kts

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

version = "1.2.1"

build.gradle

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

version = '1.2.1'

通过应用 Swift 插件中的任何一个，您可以获得大量功能

compileDebugSwift 和 compileReleaseSwift 任务，分别用于编译 _src/main/swift_ 下的 Swift 源文件，针对知名的调试和发布构建类型。
linkDebug 和 linkRelease 任务，将编译后的 Swift 对象文件链接到可执行文件（对于应用程序）或共享库（对于具有共享链接的库），分别用于调试和发布构建类型。
createDebug 和 createRelease 任务，将编译后的 Swift 对象文件组装成静态库（对于具有静态链接的库），分别用于调试和发布构建类型。

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

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

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

引入构建变体

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

维度只是一个类别，每个类别都与其他类别正交。例如，“构建类型”维度是一个包含调试和发布的类别。“架构”维度涵盖了 x86-64 和 x86 等处理器架构。

变体是这些维度的值的组合，每个维度包含一个值。您可能有一个“调试 x86-64”或“发布 x86”变体。

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

声明源文件

Gradle 的 Swift 支持直接使用应用程序或库脚本块中的 ConfigurableFileCollection 来配置要编译的源文件集。

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

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

图 1. 源文件和 Swift 编译

管理依赖项

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

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

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

为 Swift 项目指定依赖项需要两个信息：

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

此信息在 Swift 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——用于编译、链接和运行时
swiftCompileVariant——用于编译生产代码所必需但不能作为链接或运行时过程一部分的依赖项
nativeLinkVariant——用于链接代码所必需但不能作为编译或运行时过程一部分的依赖项
nativeRuntimeVariant——用于运行组件所必需但不能作为编译或链接过程一部分的依赖项

您可以在原生插件参考章节中了解有关这些内容及其相互关系的更多信息。

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

我们这里只是浅尝辄止，因此我们建议您在熟悉使用 Gradle 构建 Swift 项目的基础知识后，阅读专门的依赖管理章节。

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

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

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

编译和链接代码

如果遵循约定，编译代码可以非常简单

将源代码放在 _src/main/swift_ 目录下
在 implementation 配置中声明编译依赖项（参见上一节）
运行 assemble 任务

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

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

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

支持的工具链

Gradle 支持 macOS 和 Linux 的官方 Swift 工具链。当您构建原生二进制文件时，Gradle 会尝试找到机器上安装的可以构建该二进制文件的工具链。Gradle 选择第一个可以为目标操作系统、架构和 Swift 语言支持进行构建的工具链。

对于 Linux 用户，Gradle 将使用系统 PATH 发现工具链。

自定义文件和目录位置

假设您正在迁移一个遵循 Swift Package Manager 布局（例如，生产代码的 Sources/_ModuleName_ 目录）的库项目。传统的目录结构将无法工作，因此您需要告诉 Gradle 在哪里找到源文件。您可以通过 application 或 library 脚本块来完成此操作。

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

示例 3. 设置 Swift 源集

build.gradle.kts

extensions.configure<SwiftLibrary> {
    source.from(file("Sources/Common"))
}

build.gradle

library {
    source.from file('src')
}

现在 Gradle 只会直接在 _Sources/Common_ 中搜索源文件。

更改编译器和链接器选项

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

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

示例 4. 为所有变体设置 Swift 编译器选项

build.gradle.kts

tasks.withType(SwiftCompile::class.java).configureEach {
    // Define a preprocessor macro for every binary
    macros.add("NDEBUG")

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

build.gradle

tasks.withType(SwiftCompile).configureEach {
    // Define a preprocessor macro for every binary
    macros.add("NDEBUG")

    // Define a compiler options
    compilerArgs.add '-O'
}

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

示例 5. 按变体设置 Swift 编译器选项

build.gradle.kts

application {
    binaries.configureEach(SwiftStaticLibrary::class.java) {
        // Define a preprocessor macro for every binary
        compileTask.get().macros.add("NDEBUG")

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

build.gradle

application {
    binaries.configureEach(SwiftStaticLibrary) {
        // Define a preprocessor macro for every binary
        compileTask.get().macros.add("NDEBUG")

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

选择目标机器

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

示例 6. 设置目标机器

build.gradle.kts

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

build.gradle

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

打包和发布

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

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

清理构建

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

构建 Swift 库

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

Gradle 通过 Swift 库插件管理这种区别，该插件除了本章介绍的 _implementation_ 配置外，还引入了 _api_ 配置。如果依赖项中的类型作为静态库的未解析符号或在公共头文件中出现，则该依赖项通过您的库的公共 API 公开，因此应添加到 _api_ 配置。否则，该依赖项是内部实现细节，应添加到 _implementation_。

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

构建 Swift 应用程序

有关更多详细信息，请参阅 Swift 应用程序插件章，但这里是您可以获得的功能的快速摘要

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

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

1. 不幸的是，Cocoapods 仓库尚未作为核心功能得到支持

此页面有帮助吗？