Swift 库 - Gradle 构建系统

Swift 库插件为构建 Swift 库提供了任务、约定和惯例。特别是，Swift 库提供了可供消费者（即，使用此插件或 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 库的默认链接是共享链接，如图所示。

图 1. Swift 库插件默认任务图

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

图 2. Swift 库插件仅静态库任务图

变体相关的任务

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

图 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。 :: 聚合任务，用于组装项目中当前主机（如果存在）的共享库的 debug 变体。此任务由基础插件添加。
check - 任务 (生命周期): 聚合任务，用于执行验证任务，例如运行测试。一些插件将它们自己的验证任务添加到 check。例如，XCTest 插件将其测试任务附加到此生命周期任务。此任务由基础插件添加。
build - 任务 (生命周期): 依赖于：check、assemble :: 聚合任务，用于执行项目的完整构建。此任务由基础插件添加。
clean - 删除: 删除构建目录及其中的所有内容，即 layout.buildDirectory 项目属性指定的路径。此任务由基础插件添加。

依赖管理

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

图 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: 用于编译库。此配置包含库的编译 include 根，因此在调用 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 配置中的依赖关系将传递地暴露给库的消费者，因此将出现在消费者的编译 include 根和链接库中。另一方面，在 implementation 配置中找到的依赖关系将不会暴露给消费者，因此不会泄漏到消费者的编译 include 根和链接库中。这带来了几个好处

依赖关系不会泄漏到消费者的编译 include 根和链接库中，因此它们永远不会意外地依赖传递依赖关系
由于减少了 include 根和链接库，编译速度更快
当实现依赖关系发生更改时，重新编译次数更少，因为消费者不需要重新编译

约定

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

项目布局

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

src/main/swift: Swift 源代码，扩展名为 .swift

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

`compileVariantSwift` 任务

Swift 库插件为主组件的每个变体添加一个 SwiftCompile 实例以进行构建（例如 compileDebugSwift 和 compileReleaseSwift）。阅读构建变体介绍以获取更多信息。下面显示了一些最常见的配置选项。

compilerArgs	[]
debuggable	`true`
modules	`configurations.swiftCompileVariant`
macros	[]
objectFileDir	`layout.buildDirectory.dir("obj/main/$variant")`
optimized	`false` 用于 debug 构建类型，否则为 `true`
source	`library.swiftSource`
targetPlatform	派生自二进制文件的 `TargetMachine`
toolChain	根据目标机器自动选择

`linkVariant` 任务

Swift 库插件为主组件的每个包含共享链接作为维度的变体添加一个 LinkSharedLibrary 实例 - 例如 linkDebug 和 linkRelease。阅读构建变体介绍以获取更多信息。下面显示了一些最常见的配置选项。

debuggable	`true`
libs	`configurations.nativeLinkVariant`
linkedFile	`layout.buildDirectory.dir("lib/main/$variant/libModule[.so\|dylib]")`
linkerArgs	[]
source	`compileVariantSwift.objects`
targetPlatform	派生自二进制文件的 `TargetMachine`
toolChain	根据目标机器自动选择

`createVariant` 任务

Swift 库插件为主组件的每个包含静态链接作为维度的变体添加一个 CreateStaticLibrary 实例 - 例如 createDebug 和 createRelease。阅读构建变体介绍以获取更多信息。下面显示了一些最常见的配置选项。

outputFile	`layout.buildDirectory.dir("lib/main/$variant/libModule.a")`
source	`compileVariantSwift.objects`
staticLibArgs	[]
targetPlatform	派生自二进制文件的 `TargetMachine`
toolChain	根据目标机器自动选择

此页是否对您有帮助？