Gradle basics for Kotlin projects

Everything so far has been single files and scratch experiments. A real Kotlin project — the kind you will join at RizTech, and the capstone you build next — is managed by Gradle, the build tool that compiles your code, runs your tests, and pulls in libraries. You do not need to master Gradle to be productive, but you must understand what it does and be able to read the one file that matters.

What a build tool does

A build tool automates the steps between "source files on disk" and "a running, tested program":

• Compiling your Kotlin into bytecode (calling the compiler you would otherwise run by hand).
• Managing dependencies — downloading the libraries your project uses (coroutines, a JSON parser, a test framework) and putting them on the classpath.
• Running tests — compiling and executing your test suite.
• Packaging — producing a runnable jar or, for Android, an APK.

Doing all this by hand for a project of more than a couple of files is unmanageable — the classpath alone, once you have a few libraries each with their own dependencies, is hopeless to assemble manually. Gradle does it from a short description of what your project needs. Every real Kotlin and Android project uses Gradle, so reading its build file is a day-one skill.

The project layout

A Gradle Kotlin project has a conventional structure, and Gradle relies on it:

trip-splitter/
├── settings.gradle.kts       the project's name and modules
├── build.gradle.kts          the build script — plugins, dependencies, config
├── gradle/                   the Gradle wrapper's files
├── gradlew                   the wrapper script (run Gradle without installing it)
└── src/
    ├── main/kotlin/          your production code
    └── test/kotlin/          your tests

The convention that matters: production code lives in src/main/kotlin, tests in src/test/kotlin. Gradle finds them by location, not by configuration — put a file in the wrong place and it will not be compiled or run. This "convention over configuration" is deliberate: because every Gradle project uses the same layout, you can open any of them and know where things are.

build.gradle.kts — the one file to read

The build script is written in Kotlin itself (the .kts — Kotlin script — you met with scratch files). Here is a complete, real one, from the capstone project:

plugins {
    kotlin("jvm") version "2.1.0"      // compile Kotlin for the JVM
    application                         // make it a runnable application
}

repositories {
    mavenCentral()                      // where to download libraries from
}

dependencies {
    testImplementation(kotlin("test"))  // the test framework, only for tests
}

tasks.test {
    useJUnitPlatform()                  // run tests on JUnit 5
}

application {
    mainClass.set("splitter.MainKt")    // the entry point when you run the app
}

Read it block by block, because these blocks are 90% of every build file you will meet:

• plugins { } — what capabilities the project has. kotlin("jvm") enables Kotlin compilation; application makes it runnable. Android projects add the Android plugins here.

• repositories { } — where to fetch libraries. mavenCentral() is the main public repository, where almost every Kotlin/Java library lives.

• dependencies { } — the libraries you use, and when each is needed:

  • implementation(...) — needed to build and run the app.
  • testImplementation(...) — needed only to compile and run tests (like the test framework).

  This distinction matters: your test framework should not ship inside your production app, and testImplementation keeps it out. Declaring a dependency is one line — Gradle downloads it, and everything it depends on, automatically.

• tasks / application — configuration: run tests on JUnit, and where main is.

You will edit dependencies most often (adding a library), occasionally plugins, and rarely the rest. Being able to read this file — to answer "what does this project use and how do I run it?" — is the goal.

Running Gradle

You invoke Gradle with tasks — named units of work:

./gradlew build      # compile everything and run the tests
./gradlew test       # just run the tests
./gradlew run        # run the application (uses application { mainClass })
./gradlew clean      # delete build outputs, for a fresh start

Note ./gradlew, not gradle. That is the Gradle wrapper — a small script committed into the project that downloads and runs the exact Gradle version the project expects. This is important: it means everyone on the team, and the build server, uses the same Gradle version, so "it builds on my machine" problems disappear. Always use ./gradlew (or gradlew.bat on Windows), never a globally-installed gradle, so the version is the project's, not whatever you happen to have. In IntelliJ, the run and test buttons invoke Gradle for you.

When Gradle frustrates you

Two honest notes, because Gradle has a reputation:

• The first build is slow — it downloads Gradle (via the wrapper), the Kotlin compiler, and every dependency. This is one-time; later builds are fast, and Gradle caches aggressively.
• Error messages can be verbose. When a build fails, scroll to the line that says > What went wrong: — that is the actual error, buried in the noise. Most build failures are a missing dependency, a version mismatch, or a typo in the build file, and the "What went wrong" section names which.

You do not need to be a Gradle expert. You need to read the build file, run the tasks, add a dependency, and find the real error when a build fails. That is enough to be productive on any Kotlin project, and the rest you learn when you need it.

Check your work

What a build tool does. Compiles, manages dependencies, runs tests, and packages — automating the path from source to a tested, running program.

Why you cannot do it by hand. The classpath, once you have libraries with their own dependencies, is unmanageable manually.

The conventional layout. Production code in src/main/kotlin, tests in src/test/kotlin — found by location, not configuration.

The one file to read. build.gradle.kts, written in Kotlin.

The four blocks that matter. plugins (capabilities), repositories (where libraries come from), dependencies (what you use), and task/application config.

implementation versus testImplementation. Needed to build/run the app, versus needed only for tests — keeping the test framework out of production.

What a task is, and four common ones. A named unit of work: build, test, run, clean.

Why ./gradlew, not gradle. The wrapper pins the exact Gradle version for everyone, avoiding "works on my machine".

Where to look when a build fails. The > What went wrong: section.

Practice

1. Create a Kotlin project in IntelliJ (or with gradle init) and find build.gradle.kts. Read it and identify the four blocks.
2. Locate src/main/kotlin and src/test/kotlin. Put a file in the wrong place and confirm it is not compiled.
3. Run ./gradlew build and watch it compile and test. Run it again and note it is much faster (caching).
4. Add a dependency (for example, implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")) and use it in a file. Confirm Gradle downloads it.
5. Change a dependency to testImplementation and try to use it in src/main — read the error, and explain what the two scopes mean.
6. Break the build file (a typo) and find the > What went wrong: line in the output.
7. Run ./gradlew run and confirm it starts your main. Then ./gradlew clean and rebuild.

Official documentation

• Kotlin — Gradle — Setting up Kotlin with Gradle.
• Gradle — Build script basics — Tasks and the build lifecycle.
• Gradle — Dependency management basics — implementation, testImplementation, and repositories.
• Gradle — The Gradle wrapper — Why ./gradlew and how it pins the version.

Next: unit testing — proving your code works, and the bugs tests find.