Swift 函式庫 - Gradle 繁體中文

Swift 函式庫外掛與設定快取不相容。

Swift 函式庫外掛提供建置 Swift 函式庫的工作、慣例和約定。特別是，Swift 函式庫提供消費者（即使用此外掛或Swift 應用程式外掛的其他專案）可使用的功能。

用法

build.gradle.kts

plugins {
    `swift-library`
}

build.gradle

plugins {
    id 'swift-library'
}

建置變異

Swift 函式庫外掛了解下列面向。請閱讀建置變異簡介以取得更多資訊。

建置類型 - 永遠設為偵錯和發行

建置類型控制產生的二進位檔的可除錯性和最佳化。

偵錯 - 產生偵錯符號，且不最佳化二進位檔
發行 - 產生偵錯符號並最佳化，但從二進位檔中萃取偵錯符號

連結 - 預設為共用

連結表示應建立共用函式庫或靜態函式庫。函式庫可以產生共用函式庫、靜態函式庫或兩者。

連結可設定如下

範例 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 (靜態連結): 使用所選檔案庫從已編譯的物件檔案建立靜態函式庫
assemble變數（例如 assembleDebug 和 assembleRelease）- 任務（生命週期）: 依賴於：link變數（共用連結）或 create變數（靜態連結）:: 彙總組裝此函式庫特定變數的任務。

生命週期任務

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) 延伸 `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")`
已最佳化	`false`（偵錯建置類型）或 `true`（其他類型）
來源	`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	[]
來源	`compileVariantSwift.objects`
targetPlatform	衍生自二進位檔的 `TargetMachine`
toolChain	根據目標機器自動選取

`createVariant` 任務

Swift 函式庫外掛程式會針對每個含有靜態連結維度的函式庫變異新增 CreateStaticLibrary 執行個體，例如 createDebug 和 createRelease。請參閱建置變異簡介以取得更多資訊。下列顯示一些最常見的設定選項。

outputFile	`layout.buildDirectory.dir("lib/main/$variant/libModule.a")`
來源	`compileVariantSwift.objects`
staticLibArgs	[]
targetPlatform	衍生自二進位檔的 `TargetMachine`
toolChain	根據目標機器自動選取

此頁面有幫助嗎？