# Building Java Applications with libraries Sample

version 7.3

- Groovy DSL

- Kotlin DSL

| You can open this sample inside an IDE using the IntelliJ native importer or Eclipse Buildship.

To prepare your software project for growth, you can organize a Gradle project into multiple subprojects to modularize the software you are building. In this guide, you’ll learn how to structure such a project on the example of a Java application. However, the general concepts apply for any software you are building with Gradle. You can follow the guide step-by-step to create a new project from scratch or download the complete sample project using the links above.

## What you’ll build

You’ll build a Java application that consists of an application and multiple library projects.

## What you’ll need

- A text editor or IDE - for example IntelliJ IDEA

- A Java Development Kit (JDK), version 8 or higher - for example AdoptOpenJDK

- The latest Gradle distribution

## Create a project folder

Gradle comes with a built-in task, called `init`, that initializes a new Gradle project in an empty folder. The `init` task uses the (also built-in) `wrapper` task to create a Gradle wrapper script, `gradlew`.

The first step is to create a folder for the new project and change directory into it.

    $ mkdir demo
    $ cd demo

## Run the init task

From inside the new project directory, run the `init` task using the following command in a terminal: `gradle init`. When prompted, select the `2: application` project type and `3: Java` as implementation language. Afterwards, select `2: Add library projects`. Next you can choose the DSL for writing buildscripts - `1 : Groovy` or `2: Kotlin`. For the other questions, press enter to use the default values.

The output will look like this:

    $ gradle init

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

    Split functionality across multiple subprojects?:
       1: no - only one application project
       2: yes - application and library projects
    Enter selection (default: no - only one application project) [1..2] 2

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

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

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

    Project name (default: demo):
    Source package (default: demo):

    BUILD SUCCESSFUL
    2 actionable tasks: 2 executed

The `init` task generates the new project with the following structure:

    ├── gradle (1)
    │   └── wrapper
    │       ├── gradle-wrapper.jar
    │       └── gradle-wrapper.properties
    ├── gradlew (2)
    ├── gradlew.bat (2)
    ├── settings.gradle (3)
    ├── buildSrc
    │   ├── build.gradle (4)
    │   └── src
    │       └── main
    │           └── groovy (5)
    │               ├── demo.java-application-conventions.gradle
    │               ├── demo.java-common-conventions.gradle
    │               └── demo.java-library-conventions.gradle
    ├── app
    │   ├── build.gradle (6)
    │   └── src
    │       ├── main (7)
    │       │   └── java
    │       │       └── demo
    │       │           └── app
    │       │               ├── App.java
    │       │               └── MessageUtils.java
    │       └── test (8)
    │           └── java
    │               └── demo
    │                   └── app
    │                       └── MessageUtilsTest.java
    ├── list
    │   ├── build.gradle (6)
    │   └── src
    │       ├── main (7)
    │       │   └── java
    │       │       └── demo
    │       │           └── list
    │       │               └── LinkedList.java
    │       └── test (8)
    │           └── java
    │               └── demo
    │                   └── list
    │                       └── LinkedListTest.java
    └── utilities
        ├── build.gradle (6)
        └── src
            └── main (7)
                └── java
                    └── demo
                        └── utilities
                            ├── JoinUtils.java
                            ├── SplitUtils.java
                            └── StringUtils.java

    ├── gradle (1)
    │   └── wrapper
    │       ├── gradle-wrapper.jar
    │       └── gradle-wrapper.properties
    ├── gradlew (2)
    ├── gradlew.bat (2)
    ├── settings.gradle.kts (3)
    ├── buildSrc
    │   ├── build.gradle.kts (4)
    │   └── src
    │       └── main
    │           └── kotlin (5)
    │               ├── demo.java-application-conventions.gradle.kts
    │               ├── demo.java-common-conventions.gradle.kts
    │               └── demo.java-library-conventions.gradle.kts
    ├── app
    │   ├── build.gradle.kts (6)
    │   └── src
    │       ├── main (7)
    │       │   └── java
    │       │       └── demo
    │       │           └── app
    │       │               ├── App.java
    │       │               └── MessageUtils.java
    │       └── test (8)
    │           └── java
    │               └── demo
    │                   └── app
    │                       └── MessageUtilsTest.java
    ├── list
    │   ├── build.gradle.kts (6)
    │   └── src
    │       ├── main (7)
    │       │   └── java
    │       │       └── demo
    │       │           └── list
    │       │               └── LinkedList.java
    │       └── test (8)
    │           └── java
    │               └── demo
    │                   └── list
    │                       └── LinkedListTest.java
    └── utilities
        ├── build.gradle.kts (6)
        └── src
            └── main (7)
                └── java
                    └── demo
                        └── utilities
                            ├── JoinUtils.java
                            ├── SplitUtils.java
                            └── StringUtils.java

1 | Generated folder for wrapper files
2 | Gradle wrapper start scripts
3 | Settings file to define build name and subprojects
4 | Build script of buildSrc to configure dependencies of the build logic
5 | Source folder for convention plugins written in Groovy or Kotlin DSL
6 | Build script of the three subprojects - `app`, `list` and `utilities`
7 | Java source folders in each of the subprojects
8 | Java test source folders in the subprojects

You now have the project setup to build a Java application which is modularized into multiple subprojects.

## Review the project files

The `settings.gradle(.kts)` file has two interesting lines:

settings.gradle

    rootProject.name = 'demo'
    include('app', 'list', 'utilities')

settings.gradle.kts

    rootProject.name = "demo"
    include("app", "list", "utilities")

- `rootProject.name` assigns a name to the build, which overrides the default behavior of naming the build after the directory it’s in. It’s recommended to set a fixed name as the folder might change if the project is shared - e.g. as root of a Git repository.

- `include("app", "list", "utilities")` defines that the build consists of three subprojects in the corresponding folders. More subprojects can be added by extending the list or adding more `include(…​)` statements.

Since our build consists of multiple-subprojects, we want to share build logic and configuration between them. For this, we utilize so-called convention plugins that are located in the `buildSrc` folder. Convention plugins in `buildSrc` are an easy way to utilise Gradle’s plugin system to write reusable bits of build configuration.

in this sample, we can find three such convention plugins that are based on each other:

buildSrc/src/main/groovy/demo.java-common-conventions.gradle

    plugins {
        id 'java' (1)
    }

    repositories {
        mavenCentral() (2)
    }

    dependencies {
        constraints {
            implementation 'org.apache.commons:commons-text:1.9' (3)
        }

        testImplementation 'org.junit.jupiter:junit-jupiter:5.7.2' (4)
    }

    tasks.named('test') {
        useJUnitPlatform() (5)
    }

buildSrc/src/main/kotlin/demo.java-common-conventions.gradle.kts

    plugins {
        java (1)
    }

    repositories {
        mavenCentral() (2)
    }

    dependencies {
        constraints {
            implementation("org.apache.commons:commons-text:1.9") (3)
        }

        testImplementation("org.junit.jupiter:junit-jupiter:5.7.2") (4)
    }

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

The `java-common-conventions` defines some configuration that should be shared by all our Java project — independent of whether they represent a library or the actual application. First, we apply the Java Plugin (1) to have all functionality for building Java projects available. Then, we declare a repository —`mavenCentral()`— as source for external dependencies (2), define dependency constraints (3) as well as standard dependencies that are shared by all subprojects and set JUnit 5 as testing framework (4…​). Other shared settings, like compiler flags or JVM version compatibilities, could also be set here.

buildSrc/src/main/groovy/demo.java-library-conventions.gradle

    plugins {
        id 'demo.java-common-conventions' (1)

        id 'java-library' (2)
    }

buildSrc/src/main/kotlin/demo.java-library-conventions.gradle.kts

    plugins {
        id("demo.java-common-conventions") (1)

        `java-library` (2)
    }

buildSrc/src/main/groovy/demo.java-application-conventions.gradle

    plugins {
        id 'demo.java-common-conventions' (1)

        id 'application' (2)
    }

buildSrc/src/main/kotlin/demo.java-application-conventions.gradle.kts

    plugins {
        id("demo.java-common-conventions") (1)

        application (2)
    }

Both `java-library-conventions` and `java-application-conventions` apply the `java-common-conventions` plugin (1) so that the configuration performed there is shared by library and application projects alike. Next they apply the `java-library` or `application` plugin respectively (2) thus combining our common configuration logic with specifics for a library or application. While there is no more fine grained configuration in this example, library or application project specific build configuration can go into one of these convention plugin scripts.

Lets have a look at the `build.gradle(.kts)` files in the subprojects.

app/build.gradle

    plugins {
        id 'demo.java-application-conventions'
    }

    dependencies {
        implementation 'org.apache.commons:commons-text'
        implementation project(':utilities')
    }

    application {
        mainClass = 'demo.app.App' (1)
    }

app/build.gradle.kts

    plugins {
        id("demo.java-application-conventions")
    }

    dependencies {
        implementation("org.apache.commons:commons-text")
        implementation(project(":utilities"))
    }

    application {
        mainClass.set("demo.app.App") (1)
    }

list/build.gradle

    plugins {
        id 'demo.java-library-conventions'
    }

list/build.gradle.kts

    plugins {
        id("demo.java-library-conventions")
    }

utilities/build.gradle

    plugins {
        id 'demo.java-library-conventions'
    }

    dependencies {
        api project(':list')
    }

utilities/build.gradle.kts

    plugins {
        id("demo.java-library-conventions")
    }

    dependencies {
        api(project(":list"))
    }

Looking at the build scripts, we can see that they include up to three blocks

- Every build script should have a `plugins {}` block to apply plugins. In a well-structured build, it may only apply one convention plugin as in this example. The convention plugin will then take care of applying and configuring core Gradle plugins (like `application` or `java-library`) other convention plugin or community plugins from the Plugin Portal.

- Second, if the project has dependencies, a `dependencies {}` block should be added. Dependencies can be external, such as the JUnit dependencies we add in `java-common-conventions`, or can point to other local subprojects. For this, the `project(…​)` notation is used. In our example, the `utilities` library requires the `list` library. And the `app` makes use of the `utilities` library. If local projects depend on each other, Gradle takes care of building dependent projects if (and only if) needed. To learn more, have a look at the documentation about dependency management in Gradle.

- Third, there may be one or multiple configuration blocks for plugins. These should only be used in build scripts directly if they configure something specific for the one project. Otherwise, such configurations also belong into a convention plugin. In this example, we use the `application {}` block, which is specific to the `application` plugin, to set the `mainClass` in our `app` project to `demo.app.App` (1).

The last build file we have is the `build.gradle(.kts)` file in `buildSrc`.

buildSrc/build.gradle

    plugins {
        id 'groovy-gradle-plugin' (1)
    }

    repositories {
        gradlePluginPortal() (2)
    }

buildSrc/build.gradle.kts

    plugins {
        `kotlin-dsl` (1)
    }

    repositories {
        gradlePluginPortal() (2)
    }

This file is setting the stage to build the convention plugins themselves. By applying one of the plugins for plugin development —`groovy-gradle-plugin` or `kotlin-dsl`—(1) we enable the support for writing convention plugins as build files in `buildSrc`. Which are the convention plugins we already inspected above. Furthermore, we add Gradle’s plugin portal as repository (2), which gives us access to community plugins. To use a plugin it needs to be declared as dependency in the `dependencies {}` block.

Apart from the Gradle build files, you can find example Java source code and test source code in the corresponding folders. Feel free to modify these generated sources and tests to explore how Gradle reacts to changes when running the build as described next.

## Run the tests

You can use `./gradlew check` to execute all tests in all subprojects. When you call Gradle with a plain task name like `check`, the task will be executed for all subprojects that provide it. To target only a specific subproject, you can use the full path to the task. For example `:app:check` will only execute the tests of the `app` project. However, the other subprojects will still be compiled in the case of this example, because `app` declares dependencies to them.

    $ ./gradlew check

    BUILD SUCCESSFUL
    9 actionable tasks: 9 executed

Gradle won’t print more output to the console if all tests passed successfully. You can find the test reports in the `<subproject>/build/reports` folders. Feel free to change some of the example code or tests and rerun `check` to see what happens if a test fails.

## Run the application

Thanks to the `application` plugin, you can run the application directly from the command line. The `run` task tells Gradle to execute the `main` method in the class assigned to the `mainClass` property.

    $ ./gradlew run

    > Task :app:run
    Hello world!

    BUILD SUCCESSFUL
    2 actionable tasks: 2 executed

| The first time you run the wrapper script, `gradlew`, there may be a delay while that version of `gradle` is downloaded and stored locally in your `~/.gradle/wrapper/dists` folder.

## Bundle the application

The `application` plugin also bundles the application, with all its dependencies, for you. The archive will also contain a script to start the application with a single command.

    $ ./gradlew build

    BUILD SUCCESSFUL in 0s
    7 actionable tasks: 7 executed

If you run a full build as shown above, Gradle will have produced the archive in two formats for you: `app/build/distributions/app.tar` and `app/build/distributions/app.zip`.

## Publish a Build Scan

The best way to learn more about what your build is doing behind the scenes, is to publish a build scan. To do so, just run Gradle with the `--scan` flag.

    $ ./gradlew build --scan

    BUILD SUCCESSFUL in 0s
    7 actionable tasks: 7 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

Click the link and explore which tasks where executed, which dependencies where downloaded and many more details!

## Summary

That’s it! You’ve now successfully configured and built a Java application project with Gradle. You’ve learned how to:

- Initialize a project that produces a Java application

- Create a modular software project by combining multiple subprojects

- Share build configuration logic between subprojects using convention plugins in `buildSrc`

- Run similar named tasks in all subprojects

- Run a task in a specific subproject

- Build, bundle and run the application

## Next steps

When your project grows, you might be interested in more details how to configure JVM projects, structuring multi-project builds and dependency management:

- Building Java & JVM projects

- Working with multi-project builds

- Dependency management in Gradle