Create a new open-source Java project using the Gradle build tool

🔔 This article was originally posted on my site, MihaiBojin.com. 🔔

When building a house, you should start with a strong foundation. Similarly, creating a new open-source project requires a certain level of organization!

Roughly, here is a base minimum that makes for a decent project:

• A version control system: having it is a must-have, especially if you're planning to publish an open-source project!
• A README: help your visitors understand what the project is about and how they can find out more
• A LICENSE: choosing one early informs potential users if they can avail of the project
• A CONTRIBUTING guide: this is not precisely day one stuff, but starting one and updating it as your project develops, encourages outside contributions
• A build tool: regardless of the chosen programming language, you will need a way to manage dependencies and build or redistribute your project as binaries

Any decent build tool should be able to support:

• subprojects or modules
• code formatting
• static code analysis
• global versioning scheme
• generating sources and documentation
• running tests
• enforcing a coding standard

Let's look at all of these in detail below.

Version Control System

Most projects today use git hosted on GitHub. Other options exist, but they are beyond the scope of this article.

To create a new repository, take the following actions:

• Create a new organization: https://github.com/account/organizations/new?coupon=&plan=team_free
• Create a new repository
• Choose a license (I chose MIT because it's permissive; doing so will create a LICENSE file in your repository)
• Here's the result: https://github.com/props-sh/props

Basic repository information

At the very least, provide essential information, in a README, that helps your users understand what the project is about, how it can help them if they can use it, and how they can contribute to it.

A LICENSE file informs potential users about the conditions under which they can use your project. This article doesn't aim to inform about all differences between various types of licenses, but you can read more about it here.

Finally, a CONTRIBUTING guide will help potential developers open PRs and collaborate in your project.

Build tool

And now, let's get to the 'meaty' part.

Since I'm writing a Java project, this is very opinionated. For the first iteration of this project, I used Bazel but, since I'm starting from scratch, I thought I'd have some fun and use Gradle.

I started by installing SDKman! and then Gradle: sdk install gradle.

Since I'd never used it before, I started by reading the getting started guide. Another helpful page is how to configure java projects.

I use IntelliJ as an IDE, and it has full support for Gradle using Kotlin DSL.

Next, let's configure a sound basis for a Java library made up of multiple submodules.

Root directory configuration

I've set up this project as a multi-project build.

I started by creating a settings.gradle.kts file, which defines a name, and the pluginManagement/repositories section, which represents a set of artifact repositories to use in all (sub) projects.

rootProject.name = "props"

pluginManagement {
    repositories {
        mavenCentral()
        gradlePluginPortal()
    }
}

Define a global version for all dependencies

I created a build.gradle.kts file and defined a group and version.

group = "sh.props"
version = project.version

The version is implicitly loaded from the project and can be specified in a gradle.properties file:

version=0.2.0-SNAPSHOT

or by passing it via the command-line, e.g., gradle -Pversion=0.3.0 ...

Create a subproject

IntelliJ can easily create subprojects:

• right-click the project and select New Module
• or press Cmd-N
• select Gradle Java module
• fill in the details and you're good to go!

Alternatively, create a new directory and inside of it:

• create a build.gradle.kts file
• create a Maven-like directory structure: src/main/java, src/main/resources, src/test/java, src/test/resources

Include this subproject in the settings.gradle.kts file:

include("java-props-core")

Set a java toolchain version

Edit the subproject's build.gradle.kts file and define the following block to set the Java version to 11.

plugins {
    `java-library`
}

java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(JavaVersion.VERSION_11.toString()))
    }
}

// additionally also allow incremental builds, speeding up build speed
tasks.compileJava {
    options.isIncremental = true
}

Generate source JARs and Javadocs

Since props is a library, I wanted to generate source and documentation (Javadoc) JARs.

Luckily, this is super easy to do in Gradle. Again, edit the build.gradle.kts file:

java {
    withJavadocJar()
    withSourcesJar()
}

tasks.create<Zip>("docZip") {
    archiveFileName.set("doc.zip")
    from("doc")
}

Running tests

I chose the JUnit 5 (Jupiter) framework, for which we need to set up a few things:

First, define a new task that will run the tests when called

tasks.test {
    // Use JUnit Platform for unit tests.
    useJUnitPlatform()

    // limit heap usage to 1G (can we tweaked later)
    // https://docs.gradle.org/7.2/userguide/java_testing.html#sec:test_execution
    maxHeapSize = "1G"
}

As well as the necessary dependencies:

dependencies {
    testImplementation(libs.junit.jupiter.api)
    testRuntimeOnly(libs.junit.jupiter.engine)
}

The libs.junit.jupiter.api notation represents type-safe project dependencies in Gradle. These are defined in the root project settings; see below.

Define a version catalog

Version catalogs are an incubating feature and must be explicitly enabled.

Edit the settings.gradle.kts file and add the following section:

// enable the incubating feature
enableFeaturePreview("VERSION_CATALOGS")

dependencyResolutionManagement {
    versionCatalogs {
        create("libs") {
            // define the version once
            version("junit", "5.7.2")

            // then create aliases to each component, referencing the version above
            alias("junit-jupiter-api").to("org.junit.jupiter", "junit-jupiter-api").versionRef("junit")
            alias("junit-jupiter-engine").to("org.junit.jupiter", "junit-jupiter-engine").versionRef("junit")
        }
    }
}

Once the above is done, any tests deployed in **/src/test/java can be run by executing gradle test.

Code formatting

As a codebase grows, it's essential for the code to 'look' the same, as it helps give developers a consistent experience.

The chosen format (style) is less important than doing this from early on. After all, you can always change the style and reformat the codebase in one go later on!

This is, in my opinion, best done by a tool that indiscriminately auto-formats your code (as you write it)!

Gradle has a great plugin for this: spotless.

Define the plugin's version in your settings.gradle.kts file:

pluginManagement {
    plugins {
        id("com.diffplug.spotless").version("5.14.3")
    }
}

And add the following configuration to your build.gradle.kts file:

spotless {
    // generic formatting for miscellaneous files
    format("misc") {
        target("*.gradle", "*.md", ".gitignore")

        trimTrailingWhitespace()
        indentWithSpaces()
        endWithNewline()
    }

    // chose the Google java formatter, version 1.9
    java {
        googleJavaFormat("1.9").aosp()

        // and apply a license header
        licenseHeaderFile(rootProject.file("props.license.kt"))
    }
}

As you can see in the comments, it formats Java files as well as other extensions.

For Java, it uses the google java formatter and also applies a license header to every file. The props.license.kt contains a copy of the LICENSE file with a few tweaks:

• the text is a comment block: (/* ... */)
• and the year is programmatically filled in: ($YEAR)

/*
MIT License

Copyright (c) $YEAR Mihai Bojin

Permission is hereby granted...
*/

Check formatting with gradle spotlessJavaCheck or apply it with gradle spotlessJavaApply.

Coding standard

Checking that a project's coding standard meets minimal quality criteria results in better code!

For this I use checkstyle, which is also very easy to set up with Gradle:

Add the following to settings.gradle.kts :

dependencyResolutionManagement {
    versionCatalogs {
        create("libs") {
            // make a global version available
            version("checkstyle", "9.0")
        }
    }
}

Then edit the subproject's build.gradle.kts file:

plugins {
    checkstyle
}

checkstyle {
    // will use the version declared in the catalog
    toolVersion = libs.versions.checkstyle.get()
}

Run the check with gradle checkstyleMain.

Smarter static code analysis

Finally, the last component I'll be talking about in this article is errorprone, a library built by Google that performs smarter static code analysis. Apart from being a great standalone mistake finder, it also integrates with other projects such as NullAway, a tool that helps developers find and fix NullPointerExceptions in their Java code.

Start by adding the plugin to your settings.gradle.kts file:

pluginManagement {
    plugins {
        id("net.ltgt.errorprone").version("2.0.2")
    }
}

And then add the following configuration to your subproject's build.gradle.kts file:

import net.ltgt.gradle.errorprone.errorprone
plugins {
    id("net.ltgt.errorprone")
}

dependencies {
    errorprone(libs.errorprone.core)
    errorprone(libs.nullaway)
}

// hook up the checker to the compilation target
tasks.withType<JavaCompile>().configureEach {
    options.errorprone.disableWarningsInGeneratedCode.set(true)
}

Conclusion

Hopefully, this tutorial gave you an idea of the first steps you should take towards starting an open-source Java library on GitHub.

So far, I only spent a few hours learning how to do all of these from scratch and had a lot of fun doing it!

Since I haven't ported over any code from the v1 repo, I have probably yet to smooth out all the rough edges. If you end up using it, ping me on Twitter and tell me how you got on! ( I'd appreciate it! )

You can find all the code referenced above on GitHub in the props project!

Stay tuned for more articles in this series, and don't forget to subscribe to my newsletter! I'll be sending regular updates as I write more code.

Thank you and until next time!

If you liked this article and want to read more like it, please subscribe to my newsletter; I send one out every few weeks!