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。 :: 聚合任務，用於組裝專案中目前主機（如果存在）的共享函式庫的除錯變體（如果可用）。此任務由基礎外掛程式新增。
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) extends `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）。請閱讀建置變體簡介以取得更多資訊。下面顯示了一些最常見的配置選項。

compilerArgs	[]
debuggable	`true`
modules	`configurations.swiftCompileVariant`
macros	[]
objectFileDir	`layout.buildDirectory.dir("obj/main/$variant")`
optimized	`false` 用於除錯建置類型，否則為 `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	根據目標機器自動選取

此頁面是否對您有幫助？