開始使用 Kotlin/Native

在本教學中，您將學習如何建立 Kotlin/Native 應用程式。選擇最適合您的工具，並使用以下方式建立您的應用程式：

• IDE。在這裡，您可以從版本控制系統複製專案範本，並在 IntelliJ IDEA 中使用它。

• Gradle 建置系統。為了更好地理解底層運作方式，請手動為您的專案建立建置檔案。

• 命令列工具。您可以使用 Kotlin/Native 編譯器，它是標準 Kotlin 發行版的一部分，並直接在命令列工具中建立應用程式。

  主控台編譯可能看起來簡單明瞭，但對於包含數百個檔案和函式庫的大型專案而言，其擴展性不佳。對於此類專案，我們建議使用 IDE 或建置系統。

透過 Kotlin/Native，您可以為不同的目標平台編譯，包括 Linux、macOS 和 Windows。雖然跨平台編譯是可能的，這意味著使用一個平台來編譯另一個平台的程式碼，但在本教學中，您將針對您正在編譯的相同平台。

如果您使用 Mac，並且想要建立和執行適用於 macOS 或其他 Apple 目標平台的應用程式，您還需要先安裝 Xcode Command Line Tools，啟動它，並接受許可條款。

在 IDE 中

在本節中，您將學習如何使用 IntelliJ IDEA 建立 Kotlin/Native 應用程式。您可以同時使用 Community Edition 和 Ultimate Edition。

建立專案

1. 下載並安裝最新版本的 IntelliJ IDEA。

2. 在 IntelliJ IDEA 中選擇 File | New | Project from Version Control (檔案 | 新增 | 從版本控制建立專案) 並使用此 URL，複製專案範本：

   https://github.com/Kotlin/kmp-native-wizard

3. 開啟 gradle/libs.versions.toml 檔案，它是專案依賴項的版本目錄。要建立 Kotlin/Native 應用程式，您需要 Kotlin Multiplatform Gradle 外掛程式，其版本與 Kotlin 相同。請確保您使用最新的 Kotlin 版本：

   [versions]
   kotlin = "2.2.10"

4. 依照建議重新載入 Gradle 檔案：

   

有關這些設定的更多資訊，請參閱 Multiplatform Gradle DSL 參考。

建置並執行應用程式

開啟 src/nativeMain/kotlin/ 目錄中的 Main.kt 檔案：

• src 目錄包含 Kotlin 原始碼檔案。
• Main.kt 檔案包含使用 println() 函式列印「Hello, Kotlin/Native!」的程式碼。

按下側邊欄中的綠色圖示以執行程式碼：

IntelliJ IDEA 使用 Gradle 任務執行程式碼，並在 Run (執行) 分頁中輸出結果：

首次執行後，IDE 會在頂部建立對應的執行組態：

IntelliJ IDEA Ultimate 使用者可以安裝 Native Debugging Support 外掛程式，該外掛程式允許除錯已編譯的原生執行檔，並自動為匯入的 Kotlin/Native 專案建立執行組態。

您可以設定 IntelliJ IDEA 以自動建置您的專案：

1. 前往 Settings | Build, Execution, Deployment | Compiler (設定 | 建置、執行、部署 | 編譯器)。
2. 在 Compiler (編譯器) 頁面，選擇 Build project automatically (自動建置專案)。
3. 套用變更。

現在，當您在類別檔案中進行變更或儲存檔案 (/) 時，IntelliJ IDEA 會自動對專案執行增量建置。

更新應用程式

讓我們為您的應用程式新增一個功能，使其可以計算您姓名中的字母數量：

1. 在 Main.kt 檔案中，新增程式碼以讀取輸入。使用 readln() 函式讀取輸入值並將其指派給 name 變數：

   fun main() {
       // 讀取輸入值。
       println("Hello, enter your name:")
       val name = readln()
   }

2. 要使用 Gradle 執行此應用程式，請在 build.gradle.kts 檔案中指定 System.in 作為要使用的輸入，並載入 Gradle 變更：

   kotlin {
       //...
       nativeTarget.apply {
           binaries {
               executable {
                   entryPoint = "main"
                   runTask?.standardInput = System.`in`
               }
           }
       }
       //...
   }

3. 消除空白字元並計算字母數量：

   • 使用 replace() 函式移除姓名中的空白。
   • 使用作用域函式 let 在物件上下文 (object context) 中執行函式。
   • 使用字串範本將您姓名的長度插入字串中，方法是新增錢號並將其括在花括號中 – ${it.length}。it 是lambda 參數的預設名稱。

   fun main() {
       // 讀取輸入值。
       println("Hello, enter your name:")
       val name = readln()
       // 計算姓名中的字母數。
       name.replace(" ", "").let {
           println("您的姓名包含 ${it.length} 個字母")
       }
   }

4. 執行應用程式。

5. 輸入您的姓名並享受結果：

   

現在讓我們只計算您姓名中的唯一字母：

1. 在 Main.kt 檔案中，為 String 宣告新的擴充函式 .countDistinctCharacters()：

   • 使用 .lowercase() 函式將姓名轉換為小寫。
   • 使用 toList() 函式將輸入字串轉換為字元清單。
   • 使用 distinct() 函式選取姓名中所有唯一的字元。
   • 使用 count() 函式計算唯一字元的數量。

   fun String.countDistinctCharacters() = lowercase().toList().distinct().count()

2. 使用 .countDistinctCharacters() 函式計算您姓名中的唯一字母：

   fun String.countDistinctCharacters() = lowercase().toList().distinct().count()
   
   fun main() {
       // 讀取輸入值。
       println("Hello, enter your name:")
       val name = readln()
       // 計算姓名中的字母數。
       name.replace(" ", "").let {
           println("您的姓名包含 ${it.length} 個字母")
           // 列印唯一字母的數量。
           println("您的姓名包含 ${it.countDistinctCharacters()} 個唯一字母")
       }
   }

3. 執行應用程式。

4. 輸入您的姓名並查看結果：

   

使用 Gradle

在本節中，您將學習如何使用 Gradle 手動建立 Kotlin/Native 應用程式。它是 Kotlin/Native 和 Kotlin Multiplatform 專案的預設建置系統，也常用於 Java、Android 和其他生態系統。

建立專案檔案

1. 首先，安裝相容的 Gradle 版本。請參閱相容性表格以檢查 Kotlin Gradle 外掛程式 (KGP) 與可用 Gradle 版本的相容性。

2. 建立一個空的專案目錄。在其中，建立一個包含以下內容的 build.gradle(.kts) 檔案：

   KotlinGroovy

   // build.gradle.kts
   plugins {
       kotlin("multiplatform") version "2.2.10"
   }
   
   repositories {
       mavenCentral()
   }
   
   kotlin {
       macosArm64("native") {  // 在 macOS 上
       // linuxArm64("native") // 在 Linux 上
       // mingwX64("native")   // 在 Windows 上
           binaries {
               executable()
           }
       }
   }
   
   tasks.withType<Wrapper> {
       gradleVersion = "8.14"
       distributionType = Wrapper.DistributionType.BIN
   }

   // build.gradle
   plugins {
       id 'org.jetbrains.kotlin.multiplatform' version '2.2.10'
   }
   
   repositories {
       mavenCentral()
   }
   
   kotlin {
       macosArm64('native') {  // 在 macOS 上
       // linuxArm64('native') // 在 Linux 上
       // mingwX64('native')   // 在 Windows 上
           binaries {
               executable()
           }
       }
   }
   
   wrapper {
       gradleVersion = '8.14'
       distributionType = 'BIN'
   }

   您可以使用不同的目標名稱，例如 macosArm64、iosArm64、linuxArm64 和 mingwX64 來定義您要編譯程式碼的目標平台。這些目標名稱可以選擇性地將平台名稱作為參數，在本例中為 native。平台名稱用於在專案中產生原始碼路徑和任務名稱。

3. 在專案目錄中建立一個空的 settings.gradle(.kts) 檔案。

4. 建立 src/nativeMain/kotlin 目錄，並在其中放置一個包含以下內容的 hello.kt 檔案：

   fun main() {
       println("Hello, Kotlin/Native!") // 列印 "Hello, Kotlin/Native!"
   }

按照慣例，所有原始碼都位於 src/<target name>[Main|Test]/kotlin 目錄中，其中 Main 用於原始碼，Test 用於測試。<target name> 對應於目標平台 (在本例中為 native)，如建置檔案中所指定。

建置並執行專案

1. 從根專案目錄執行建置命令：

   ./gradlew nativeBinaries

   此命令會建立 build/bin/native 目錄，其中包含兩個子目錄：debugExecutable 和 releaseExecutable。它們包含對應的二進位檔案。

   預設情況下，二進位檔案的名稱與專案目錄相同。

2. 要執行專案，請執行以下命令：

   build/bin/native/debugExecutable/<project_name>.kexe

終端機將列印「Hello, Kotlin/Native!」。

在 IDE 中開啟專案

現在，您可以在任何支援 Gradle 的 IDE 中開啟您的專案。如果您使用 IntelliJ IDEA：

1. 選擇 File | Open (檔案 | 開啟)。
2. 選取專案目錄並點擊 Open (開啟)。IntelliJ IDEA 會自動偵測它是否為 Kotlin/Native 專案。

如果您遇到專案問題，IntelliJ IDEA 會在 Build (建置) 分頁中顯示錯誤訊息。

使用命令列編譯器

在本節中，您將學習如何使用命令列工具中的 Kotlin 編譯器建立 Kotlin/Native 應用程式。

下載並安裝編譯器

要安裝編譯器：

1. 前往 Kotlin 的 GitHub 發佈 頁面，然後向下捲動到 Assets (資產) 區段。

2. 尋找名稱中包含 kotlin-native 的檔案，並下載適用於您作業系統的檔案，例如 kotlin-native-prebuilt-linux-x86_64-2.2.10.tar.gz。

3. 將壓縮檔解壓縮到您選擇的目錄。

4. 開啟您的 shell 設定檔，並將編譯器 /bin 目錄的路徑新增到 PATH 環境變數中：

   export PATH="/<path to the compiler>/kotlin-native/bin:$PATH"

雖然編譯器輸出沒有依賴項或虛擬機器要求，但編譯器本身需要 Java 1.8 或更高版本的執行環境。它由 JDK 8 (JAVA SE 8) 或更高版本支援。

建立程式

選擇一個工作目錄，並建立一個名為 hello.kt 的檔案。使用以下程式碼更新它：

fun main() {
    println("Hello, Kotlin/Native!") // 列印 "Hello, Kotlin/Native!"
}

從主控台編譯程式碼

要編譯應用程式，請使用下載的編譯器執行以下命令：

kotlinc-native hello.kt -o hello

-o 選項的值指定輸出檔案的名稱，因此此呼叫會在 macOS 和 Linux 上產生 hello.kexe 二進位檔案 (在 Windows 上則為 hello.exe)。

有關可用選項的完整列表，請參閱 Kotlin 編譯器選項。

執行程式

要執行程式，在您的命令列工具中，導覽至包含二進位檔案的目錄並執行以下命令：

macOS 和 LinuxWindows

./hello.kexe

./hello.exe

應用程式會將「Hello, Kotlin/Native」列印到標準輸出。

下一步是什麼？

• 完成使用 C 互通性與 libcurl 建立應用程式教學，其中解釋了如何建立原生 HTTP 用戶端以及與 C 函式庫互通。
• 學習如何為實際的 Kotlin/Native 專案編寫 Gradle 建置指令碼。
• 在文件中閱讀更多關於 Gradle 建置系統的資訊。