Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 36 ยท Getting Started

Your First Gradle Build: gradle init and Project Layout

Create a Gradle project with gradle init, understand every generated file, and learn the standard src/main and src/test layout and the build output folders.

The fastest way to learn Gradle is to create a project and read what it generates. Gradle ships with a project generator, the init task, which asks a few questions and writes a working build. In this lesson you will run it, walk through every file it creates, learn the standard folder layout, and run your first build. The commands are read-only on this site, but we recreate the layout with a runnable Bash stand-in so you can see the shape of the project.

Generating a project

Make an empty folder and run init:

Terminal
mkdir greeter
cd greeter
gradle init

The generator asks questions. A typical session for a small Java app:

TEXT
Select type of project to generate:
  1: basic
  2: application
  3: library
  4: Gradle plugin
Enter selection (default: basic) [1..4] 2

Select implementation language:
  1: Java
  2: Kotlin
  ...
Enter selection (default: Java) [1..7] 1

Enter target Java version (min: 7, default: 21): 21
Project name (default: greeter): greeter
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] 1

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

You can skip the questions with options, which is handy in scripts:

Terminal
gradle init --type java-application --dsl kotlin --test-framework junit-jupiter --project-name greeter --package com.example --no-incubating --use-defaults

The generated files

TEXT
greeter/
  gradlew
  gradlew.bat
  gradle/
    libs.versions.toml          # version catalog
    wrapper/
      gradle-wrapper.jar
      gradle-wrapper.properties
  settings.gradle.kts           # project name and included projects
  app/
    build.gradle.kts            # the build script
    src/
      main/java/com/example/App.java
      test/java/com/example/AppTest.java
  .gitignore
  .gitattributes

What each piece is for:

  • gradlew, gradlew.bat, gradle/wrapper/: the wrapper.
  • settings.gradle.kts: declares the root project's name and which subprojects exist. Every build has exactly one settings file.
  • app/build.gradle.kts: the build script of the app project: plugins, repositories, dependencies.
  • gradle/libs.versions.toml: a central list of dependency versions (a version catalog, see Repositories and Version Catalogs).
  • src/main/java and src/test/java: your production and test code.

The generated settings.gradle.kts is only a few lines:

Kotlin
rootProject.name = "greeter"
include("app")

And app/build.gradle.kts:

Kotlin
plugins {
    application
}

repositories {
    mavenCentral()
}

dependencies {
    testImplementation(libs.junit.jupiter)
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
    implementation(libs.guava)
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

application {
    mainClass = "com.example.App"
}

tasks.named<Test>("test") {
    useJUnitPlatform()
}

The standard layout

Gradle's Java plugin follows a convention shared with Maven. You do not need to configure source folders; you just put files in the right place.

Folder Contents
src/main/java Production Java sources
src/main/resources Files copied to the classpath (properties, templates)
src/test/java Test sources
src/test/resources Test-only resources
build/ Everything Gradle generates: classes, jars, reports

The build/ folder is output. Never commit it; the generated .gitignore already lists it. The folder .gradle/ in the project root holds Gradle's own caches and is ignored too.

Running the build

From the project root:

Terminal
./gradlew build

A first run prints something like this (timings vary):

TEXT
> Task :app:compileJava
> Task :app:processResources NO-SOURCE
> Task :app:classes
> Task :app:jar
> Task :app:startScripts
> Task :app:distTar
> Task :app:distZip
> Task :app:assemble
> Task :app:compileTestJava
> Task :app:test
> Task :app:check
> Task :app:build

BUILD SUCCESSFUL in 4s

Then start the program with ./gradlew run. Run build a second time and most lines gain UP-TO-DATE, because nothing changed. After a build you will find app/build/classes, app/build/libs/app.jar and app/build/reports/tests.

A runnable stand-in: the sample app

This is the kind of class init places in src/main/java. Here it runs as a normal single-file Java program on the site's runner (not through Gradle).

Java Stand-in: the generated App class

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The generated test would simply assert that getGreeting() is not null. Tests are covered in the Testing chapter.

A runnable stand-in: the project tree

This Bash script builds the same folder structure and prints it, so you can practice reading a layout. It is only an imitation of gradle init, not the real generator.

Bash Stand-in: recreate the layout

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Common first-day mistakes

  • Running gradle in the wrong folder. Gradle searches upward for settings.gradle(.kts). Run it from the project root so you know which build you are in.
  • Committing build/ or .gradle/. Both are generated; keep them in .gitignore.
  • Editing generated files by hand and forgetting the wrapper. Use ./gradlew, never a random global version.
  • Putting sources in the wrong folder. Files outside src/main/java are silently ignored by the Java plugin.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which file declares the name of the root project and which subprojects are included?

    settings.gradle(.kts) is evaluated first and defines rootProject.name and include(...) entries.
  2. 2. Where do production Java sources go by convention?

    The Java plugin expects src/main/java for main code and src/test/java for tests.
  3. 3. Which folder should NOT be committed to version control?

    build/ contains generated output. The wrapper files and sources should be committed.
  4. 4. What is the benefit of running ./gradlew build twice in a row?

    Incremental build support lets Gradle skip work it already did.

Summary

  • gradle init generates a working project: wrapper, settings file, build script, sources and a test.
  • settings.gradle.kts names the build; build.gradle.kts configures a project.
  • Conventions: src/main/java, src/test/java, output in build/.
  • ./gradlew build compiles, tests and packages; ./gradlew run starts an application.
  • Do not commit build/ or .gradle/.

Next: The Build Lifecycle