Swift 库插件提供了用于构建 Swift 库的任务、约定和惯例。具体来说，Swift 库提供可供消费者（即，使用此插件或其他Swift 应用程序插件的项目）使用的功能。

用法

示例 1. 应用 Swift 库插件
build.gradle.kts
plugins {
    `swift-library`
}
build.gradle
plugins {
    id 'swift-library'
}

构建变体

Swift 库插件理解以下维度。有关更多信息，请阅读构建变体简介。

构建类型 - 始终设置为 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.macOS.x86_64)
}
build.gradle
library {
    targetMachines = [
        machines.linux.x86_64,
        machines.macOS.x86_64
    ]
}

任务

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

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

swift shared library task graph
图 1. Swift 库插件默认任务图

使用静态链接，图示更改为以下内容

swift static library task graph
图 2. Swift 库插件仅静态库任务图

依赖于变体的任务

Swift 库插件根据库组件的变体创建任务。有关更多信息，请阅读构建变体简介。以下图表显示了依赖于变体的任务之间的关系。

swift library variant task graph
图 3. Swift 库插件依赖于变体的任务图
取决于链接属性
compileVariantSwift (例如 compileDebugSwift 和 compileReleaseSwift) - SwiftCompile

依赖于：所有为编译提供源文件的任务:: 使用选定的编译器编译 Swift 源文件。

linkVariant (例如 linkDebug 和 linkRelease) - LinkSharedLibrary (共享链接)

依赖于：所有有助于链接库的任务，包括通过项目依赖项解析的项目中的 linkVariant 和 createVariant 任务::使用选定的链接器从已编译的目标文件链接共享库。

createVariant (例如 createDebug 和 createRelease) - CreateStaticLibrary (静态链接)

使用选定的归档器从已编译的目标文件创建静态库

assembleVariant（例如 assembleDebug 和 assembleRelease）- 任务（生命周期）

依赖于：linkVariant（共享链接）或 createVariant（静态链接）::聚合组装此库的特定变体的任务。

生命周期任务

Swift 库插件将其一些任务附加到基本插件章节中记录的标准生命周期任务——Swift 库插件会自动应用这些任务。

assemble - 任务（生命周期）

依赖于：当链接包含 shared 时为 linkDebug，否则为 createDebug。::聚合任务，用于组装项目中的当前主机（如果存在）的共享库的调试变体（如果可用）。此任务由基本插件添加。

check - 任务（生命周期）

聚合任务，执行验证任务，例如运行测试。一些插件将自己的验证任务添加到 check 中。例如，XCTest 插件将其测试任务附加到此生命周期任务。此任务由基本插件添加。

build - 任务（生命周期）

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

clean - 删除

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

依赖管理

就像 Swift 库插件创建的任务一样，根据库组件的变体创建了多个配置。有关更多信息，请阅读构建变体简介。下图描述了 Swift 库插件添加的配置。

swift library configurations
图 4. Swift 库插件配置

  • 白色配置是用户应该用来声明依赖项的配置

  • 粉红色框中的配置，也称为可消费配置（用 (C) 表示），是组件编译、链接或针对库运行时使用的配置。

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

以下配置用于声明依赖项

api

用于声明 API 依赖项（请参阅API 与实现部分）。您应该在此处声明要传递导出给消费者进行编译和链接的依赖项。

implementation 扩展 api

用于声明主组件所有变体的实现依赖项（请参阅API 与实现部分）。您应该在此处声明纯粹内部且不应暴露给任何变体消费者的依赖项。

mainVariantImplementation（例如 mainDebugImplementation 和 mainReleaseImplementation）扩展 implementation

用于声明主组件特定变体的实现依赖项（请参阅API 与实现部分）。您应该在此处声明纯粹内部且不应暴露给此特定变体消费者的依赖项。

以下配置由消费者使用

variantSwiftApiElements (例如 debugSwiftApiElements 和 releaseSwiftApiElements) 扩展 mainVariantImplementation

用于针对库进行编译。此配置旨在供消费者使用，以检索针对库编译所需的所有元素。

variantLinkElements (例如 debugLinkElements 和 releaseLinkElements) 扩展 mainVariantImplementation

用于针对库进行链接。此配置旨在供消费者使用，以检索针对库链接所需的所有元素。

variantRuntimeElements（例如 debugRuntimeElements 和 releaseRuntimeElements）扩展 mainVariantImplementation

用于执行库。此配置旨在供消费者使用，以检索针对库运行所需的所有元素。

以下配置由库本身使用

swiftCompileVariant (例如 swiftCompileDebug 和 swiftCompileRelease) 扩展 mainVariantImplementation

用于编译库。此配置包含库的编译包含根，因此在调用 Swift 编译器编译它时使用。

nativeLinkVariant（例如 nativeLinkDebug 和 nativeLinkRelease）扩展 mainVariantImplementation

仅用于链接共享库。此配置包含库的库，因此在调用 Swift 链接器链接它时使用。

nativeRuntimeVariant（例如 nativeRuntimeDebug 和 nativeRuntimeRelease）扩展 mainVariantImplementation

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

API 与实现

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

示例 4. 添加依赖项
build.gradle.kts
library {
    dependencies {
        // FIXME: Put real deps here.
        api("io.qt:core:5.1")
        implementation("io.qt:network:5.1")
    }
}
build.gradle
library {
    dependencies {
        // FIXME: Write better deps here.
        api "io.qt:core:5.1"
        implementation "io.qt:network:5.1"
    }
}

出现在 api 配置中的依赖项将传递地暴露给库的消费者，因此将出现在消费者的编译包含根和链接库中。相反，在 implementation 配置中找到的依赖项将不会暴露给消费者，因此不会泄露到消费者的编译包含根和链接库中。这带来了几个好处：

  • 依赖项不会泄露到消费者的编译包含根和链接库中，因此它们永远不会意外地依赖于传递依赖项

  • 由于减少了包含根和链接库，编译速度更快

  • 当实现依赖项发生变化时，重新编译次数减少，因为消费者不需要重新编译

约定

Swift 库插件为源和任务添加了约定，如下所示。

项目布局

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

src/main/swift

带有 .swift 扩展名的 Swift 源

您通过配置 library 脚本块上的 source 来配置项目布局。

compileVariantSwift 任务

Swift 库插件为要构建的库组件的每个变体添加一个 SwiftCompile 实例（例如 compileDebugSwift 和 compileReleaseSwift）。有关更多信息，请阅读构建变体简介。一些最常见的配置选项如下所示。

编译器参数

[]
可调试

true
模块

configurations.swiftCompileVariant
宏

[]
objectFileDir

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

调试构建类型为 false，否则为 true
源

library.swiftSource
目标平台

从二进制文件的 TargetMachine 派生
工具链

根据目标机器自动选择

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

可调试

true
库

configurations.nativeLinkVariant
链接文件

layout.buildDirectory.dir("lib/main/$variant/libModule[.so|dylib]")
链接器参数

[]
源

compileVariantSwift.objects
目标平台

从二进制文件的 TargetMachine 派生
工具链

根据目标机器自动选择

createVariant 任务

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

输出文件

layout.buildDirectory.dir("lib/main/$variant/libModule.a")
源

compileVariantSwift.objects
静态库参数

[]
目标平台

从二进制文件的 TargetMachine 派生
工具链

根据目标机器自动选择