A Build Automation Example

This repository contains an example of a build automation utility that can assist in automating the tasks related to compiling, testing, documenting, and formatting a Java project.

The example is based on the Gradle Build Tool, it is not intended as a tutorial about it (there are many pretty good ones around), but to provide some very minimal scaffolding that interested students of my Porgrammazione II class can leverage to organize their homework and to automate the related building tasks.

A deep understanding of how to configure and modify the settings of this tool is absolutely not required to pass the exam; to complete homework and project it's enough to know how to use the tool as pre-configured by the teacher.

How to use it

The (relevant) content of this repository is

├── build.gradle
├── gradlew
├── gradlew.bat
└── src
    ├── main
    │   └── java
    │       └── my
    │           └── pkg
    │               ├── Example.java
    │               └── package-info.java
    ├── overview.html
    └── test
        └── java
            └── my
                └── pkg
                    └── ExampleTest.java

The build.gradle file is the tool configuration file, while gradlew and gradlew.bat are two executable files (respectively for Unix/POSIX and Windows OSs) that can be used to (install and) run the tool.

The src directory hierarchy contains a sample package my.pkg with the Example.java implementation of a class, and ExampleTest.java set of unit tests for such class; moreover it contains some additional documentation (the package level overview.html and the project level overview.html files).

Dependencies on other tools

The unit tests are based on JUnit 5, coverage is handled using JaCoCo, and the documentation is redacted using Javadoc (endowed with MathJax to allow for a more pleasant mathematical notation); code formatting follows the Google Java Style Guide and is provided by Spotless, A basic introduction of such tools is presented during the class, any further detail is beside the scope of this repository (and the course itself).

The build automation tool will automatically satisfy the required dependencies, so that no manual installation and configuration will be needed.

One can add his packages, implementations and documentation to the src directory hierarchy (and possibly eliminate the sample code and documentation). The build tool can be invoked as

./gradlew task...

the most interesting tasks are described in the following table

Task	Effect
clean	Deletes the build directory
classes	Assembles main classes
testClasses	Assembles test classes
test	Runs the unit tests
build	Assembles and tests this project
runClass	Runs the main method of a class given by its fully qualified name
javadoc	Generates Javadoc API documentation for the main source code
spotlessApply	Applies code formatting steps to sourcecode in-place
tasks	Lists all available tasks

typically one wants to compile and run tests with

./gradlew build

or to reformat the code and generate the documentation with

./gradlew spotlessApply javadoc

The execution of such tasks creates and populates the build directory hierarchy as follows

build
├── classes
│   └── java
│       ├── main
│       │   └── my
│       │       └── pkg
│       │           └── Example.class
│       └── test
│           └── my
│               └── pkg
│                   └── ExampleTest.class
├── docs
│   └── javadoc
│       ├── index.html
│       └── ...
└── reports
    ├── jacoco
    │   └── test
    │       └── html
    │           ├── index.html
    │           └── ...
    └── tests
        └── test
            ├── index.html
            └── ...

where classes contains the compiled classes, reports contains the unit test and coverage results, and docs contains the generated documentation. Given the location of the compiled files, to run the Example class it's enough to specify build/classes/java/main as the classpath as in

java -cp build/classes/java/main my.pkg.Example hello

or to set the CLASSPATH environment variable once and for all; alternatively, one can use the runClass task as

./gradlew runClass -PmainClass=my.pkg.Example --args=hello

and the build tool will take care of the classpath.