建立 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 發佈的 Maven 儲存庫中預先建置的二進位檔 ^[1]。

我們將介紹如何在多重建置專案中新增專案之間的相依性。

為 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 套件管理員配置 (例如 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 中直接搜尋來源。

變更編譯器和連結器選項

大部分的編譯器和連結器選項都可透過對應的任務存取，例如 compileVariantSwift、linkVariant 和 createVariant。這些任務分別為 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 存放庫尚未支援為核心功能

此頁面有幫助嗎？