您可以在支持 Gradle 的 IDE 中打开此示例。

本指南演示了如何使用 gradle init 命令通过 Gradle 创建 Kotlin 应用程序。您可以按照本指南的步骤从零开始创建新项目，或使用上面的链接下载完整的示例项目。

您将构建什么

您将生成一个遵循 Gradle 约定的 Kotlin 应用程序。

您将需要什么

创建项目文件夹

Gradle 提供了一个内置的 Task，名为 init，用于在空文件夹中初始化新的 Gradle 项目。init Task 使用（同样内置的）wrapper Task 创建一个 Gradle wrapper 脚本 gradlew。

第一步是为新项目创建一个文件夹并进入该目录。

$ mkdir demo
$ cd demo

运行 init Task

在新项目目录中，在终端中使用以下命令运行 init Task：gradle init。出现提示时，选择项目类型 1: application 和实现语言 2: Kotlin。接下来，您可以选择编写构建脚本的 DSL - 1 : Kotlin 或 2: Groovy。对于其他问题，按 Enter 键使用默认值。

输出将如下所示

$ gradle init

Select type of build to generate:
  1: Application
  2: Library
  3: Gradle plugin
  4: Basic (build structure only)
Enter selection (default: Application) [1..4] 1

Select implementation language:
  1: Java
  2: Kotlin
  3: Groovy
  4: Scala
  5: C++
  6: Swift
Enter selection (default: Java) [1..6] 2

Enter target Java version (min: 7, default: 21):

Project name (default: demo):

Select application structure:
  1: Single application project
  2: Application and library project
Enter selection (default: Single application project) [1..2] 1

Select build script DSL:
  1: Kotlin
  2: Groovy
Enter selection (default: Kotlin) [1..2]

Select test framework:
  1: JUnit 4
  2: TestNG
  3: Spock
  4: JUnit Jupiter
Enter selection (default: JUnit Jupiter) [1..4]

Generate build using new APIs and behavior (some features may change in the next minor release)? (default: no) [yes, no]

BUILD SUCCESSFUL
1 actionable task: 1 executed

init Task 生成的新项目具有以下结构

├── gradle (1)
│   ├── libs.versions.toml (2)
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew (3)
├── gradlew.bat (3)
├── settings.gradle.kts (4)
└── app
    ├── build.gradle.kts (5)
    └── src
        ├── main
        │   └── kotlin (6)
        │       └── demo
        │           └── App.kt
        └── test
            └── kotlin (7)
                └── demo
                    └── AppTest.kt
├── gradle (1)
│   ├── libs.versions.toml (2)
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew (3)
├── gradlew.bat (3)
├── settings.gradle (4)
└── app
    ├── build.gradle (5)
    └── src
        ├── main
        │   └── kotlin (6)
        │       └── demo
        │           └── App.kt
        └── test
            └── kotlin (7)
                └── demo
                    └── AppTest.kt
1 生成的 wrapper 文件文件夹
2 生成的版本目录
3 Gradle wrapper 启动脚本
4 Settings 文件，用于定义构建名称和子项目
5 app 项目的构建脚本
6 默认 Kotlin 源代码文件夹
7 默认 Kotlin 测试源代码文件夹

现在您已经设置好项目来构建 Kotlin 应用程序。

查看项目文件

settings.gradle(.kts) 文件中有两行值得注意

settings.gradle.kts
rootProject.name = "demo"
include("app")
settings.gradle
rootProject.name = 'demo'
include('app')

  • rootProject.name 为构建分配一个名称，这会覆盖默认的以目录名称作为构建名称的行为。建议设置一个固定的名称，因为如果项目被共享（例如作为 Git 仓库的根目录），文件夹名称可能会改变。

  • include("app") 定义了构建包含一个名为 app 的子项目，该子项目包含实际的代码和构建逻辑。可以通过额外的 include(…​) 语句添加更多子项目。

我们的构建包含一个名为 app 的子项目，它代表了我们正在构建的 Kotlin 应用程序。它在 app/build.gradle(.kts) 文件中配置。

app/build.gradle.kts
plugins {
    alias(libs.plugins.kotlin.jvm) (1)
    application (2)
}

repositories {
    mavenCentral() (3)
}

dependencies {
    testImplementation("org.jetbrains.kotlin:kotlin-test-junit5") (4)

    testImplementation(libs.junit.jupiter.engine) (5)

    testRuntimeOnly("org.junit.platform:junit-platform-launcher")

    implementation(libs.guava) (6)
}

application {
    mainClass = "demo.AppKt" (7)
}

tasks.named<Test>("test") {
    useJUnitPlatform() (8)
}
app/build.gradle
plugins {
    alias(libs.plugins.kotlin.jvm) (1)
    id 'application' (2)
}

repositories {
    mavenCentral() (3)
}

dependencies {
    testImplementation 'org.jetbrains.kotlin:kotlin-test-junit5' (4)

    testImplementation libs.junit.jupiter.engine (5)

    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'

    implementation libs.guava (6)
}

application {
    mainClass = 'demo.AppKt' (7)
}

tasks.named('test') {
    useJUnitPlatform() (8)
}
1 应用 org.jetbrains.kotlin.jvm Plugin 以添加对 Kotlin 的支持。
2 应用 application plugin 以添加对构建 Java 命令行应用程序的支持。
3 使用 Maven Central 解析依赖。
4 使用 Kotlin JUnit 5 集成。
5 使用 JUnit 5 集成。
6 应用程序使用了这个依赖。
7 为应用程序定义主类。
8 使用 JUnit Platform 进行单元测试。

文件 src/main/kotlin/demo/App.kt 显示如下

生成的 src/main/kotlin/demo/App.kt
/*
 * This source file was generated by the Gradle 'init' task
 */
package demo

class App {
    val greeting: String
        get() {
            return "Hello World!"
        }
}

fun main() {
    println(App().greeting)
}

生成的测试文件 src/test/kotlin/demo/App.kt 显示如下

生成的 src/test/kotlin/demo/AppTest.kt
/*
 * This source file was generated by the Gradle 'init' task
 */
package demo

import kotlin.test.Test
import kotlin.test.assertNotNull

class AppTest {
    @Test fun appHasAGreeting() {
        val classUnderTest = App()
        assertNotNull(classUnderTest.greeting, "app should have a greeting")
    }
}

生成的测试类有一个单独的 kotlin.test 测试。该测试实例化 App 类，调用其方法，并检查它是否返回期望的值。

运行应用程序

多亏了 application plugin，您可以直接从命令行运行应用程序。run Task 告诉 Gradle 执行分配给 mainClass 属性的类中的 main 方法。

$ ./gradlew run

> Task :app:run
Hello world!

BUILD SUCCESSFUL
2 actionable tasks: 2 executed
第一次运行 wrapper 脚本 gradlew 时，可能会有延迟，因为该版本的 gradle 需要下载并本地存储在您的 ~/.gradle/wrapper/dists 文件夹中。

打包应用程序

application plugin 还会为您打包应用程序及其所有依赖项。生成的归档文件中还将包含一个脚本，用于通过一个命令启动应用程序。

$ ./gradlew build

BUILD SUCCESSFUL in 0s
8 actionable tasks: 8 executed

如果您运行如上所示的完整构建，Gradle 将为您生成两种格式的归档文件：app/build/distributions/app.tar 和 app/build/distributions/app.zip。

发布构建扫描

了解构建在幕后做了什么最好的方法是发布一个构建扫描。为此，只需使用 --scan 标志运行 Gradle。

$ ./gradlew build --scan

BUILD SUCCESSFUL in 0s
8 actionable tasks: 8 executed

Publishing a build scan to scans.gradle.com requires accepting the Gradle Terms of Service defined at https://gradle.com/terms-of-service.
Do you accept these terms? [yes, no] yes

Gradle Terms of Service accepted.

Publishing build scan...
https://gradle.com/s/5u4w3gxeurtd2

点击链接，探索执行了哪些 Task，下载了哪些依赖，以及更多详细信息！

总结

就是这样！您现在已经成功使用 Gradle 配置和构建了一个 Kotlin 应用程序项目。您已经学会了如何：

  • 初始化一个生成 Kotlin 应用程序的项目

  • 运行构建并查看测试报告

  • 使用 application plugin 的 run Task 执行 Kotlin 应用程序

  • 将应用程序打包到归档文件中

下一步

要了解如何进一步自定义 Kotlin 应用程序项目，请查看以下用户手册章节：