This guide demonstrates how to create a Groovy library in the standard form using Gradle’s Build Init plugin.

What you’ll build

You’ll generate a Groovy library with the standard layout.

What you’ll need

  • About

  • A text editor

  • A command prompt

  • The Java Development Kit (JDK), version 1.7 or higher

  • A Gradle distribution, version 3.5 or better

Check the user manual

Gradle comes with a built-in plugin called the Build Init plugin. It is documented in the Gradle User Manual. The plugin has one task, called init, that generates the project. The init task calls 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 building-groovy-libraries
$ cd building-groovy-libraries

Run the init task

From inside the new project directory, run the init task with the groovy-library argument.

$ gradle init --type groovy-library
:wrapper
:init

BUILD SUCCESSFUL

The init task runs the wrapper task first, which generates the gradlew and gradlew.bat wrapper scripts. Then it creates the new project with the following structure:

├── build.gradle
├── gradle
│   └── wrapper  (1)
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew
├── gradlew.bat
├── settings.gradle
└── src
    ├── main
    │   └── groovy  (2)
    │       └── Library.groovy
    └── test
        └── groovy (3)
            └── LibraryTest.groovy
1 Generated folder for wrapper files
2 Default Groovy source folder
3 Default Groovy test folder

Review the generated project files

The settings.gradle file is heavily commented, but has only one active line:

Generated settings.gradle
rootProject.name = 'gradleRunner' (1)
1 This assigns the name of the root project.

The generated build.gradle file also has many comments. The active portion is reproduced here (note version numbers for the dependencies may be updated in later versions of Gradle):

Generated build.gradle
apply plugin: 'groovy'

repositories {
    jcenter() (1)
}

dependencies {
    compile 'org.codehaus.groovy:groovy-all:2.4.10' (2)

    testCompile 'org.spockframework:spock-core:1.0-groovy-2.4' (3)
    testCompile 'junit:junit:4.12' (4)
}
1 Public Bintray Artifactory repository
2 Groovy version that this project will include as dependency
3 Spock Framework testing library
4 JUnit testing library

The build file adds the groovy plugin. This is an extension of the java plugins and adds additional tasks for compiling Groovy source code. It also allows for joint compilation of Groovy and Java files if found in the appropriate groovy source folders.

The file src/main/groovy/Library.groovy is shown here:

Generated src/main/groovy/Library.groovy
class Library {
    boolean someLibraryMethod() {
        true
    }
}

The generated Spock specification, src/test/groovy/LibraryTest.groovy is shown next:

Generated src/test/groovy/LibraryTest.groovy
import spock.lang.Specification

class LibraryTest extends Specification {
    def "someLibraryMethod returns true"() {
        setup:
        def lib = new Library()

        when:
        def result = lib.someLibraryMethod()

        then:
        result == true
    }
}

The generated test class has a single Spock specification. The test instantiates the Library class, invokes the someLibraryMethod method, and checks that the returned value is `true.

Execute the build

To build the project, run the build task. You can use the regular gradle command, but when a project includes a wrapper script, it is considered good form to use it instead.

$ ./gradlew build
:compileJava NO-SOURCE
:compileGroovy
:processResources NO-SOURCE
:classes
:jar
:assemble
:compileTestJava NO-SOURCE
:compileTestGroovy
:processTestResources NO-SOURCE
:testClasses
:test
:check
:build

BUILD SUCCESSFUL
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.

The first time you run the build, Gradle will check whether or not you already have the Groovy, Spock Framework and JUnit libraries in your cache under your ~/.gradle directory. If not, the libraries will be downloaded and stored there. The next time you run the build, the cached versions will be used. The build task compiles the classes, runs the tests, and generates a test report.

You can view the test report by opening the HTML output file, located at build/reports/tests/test/index.html.

A sample report is shown here:

Test Summary

Congratulations, you have just completed the step from creating a Groovy library! You can can now customise this to your own project needs.

Adding API documentation

The groovy plugin has built-in support for Groovy’s API documentation tool groovydoc.

Annotate the Library.groovy file with Groovydoc markup.

src/main/groovy/Library.groovy
/** This Groovy source file was generated by the Gradle 'init' task.
 */
class Library {
    boolean someLibraryMethod() {
        true
    }
}

Run the groovydoc task.

$ ./gradlew groovydoc
:compileJava NO-SOURCE
:compileGroovy
:processResources NO-SOURCE
:classes
:groovydoc
[ant:groovydoc] /home/travis/build/gradle-guides/building-groovy-libraries/build/runners/gradleRunner/build/tmp/groovydoc contains source files in the default package, you must specify them as source files not packages.

BUILD SUCCESSFUL

You can view the generated Groovydoc by opening the HTML file, located at build/docs/groovydoc/index.html.

Summary

You now have a new Groovy project that you generated using Gradle’s build init plugin. In the process, you saw:

  • How to generate a Groovy library

  • How the generated build file and sample Groovy files are structured

  • How to run the build and view the test report

  • Generating API documentation.

Next Steps

Help improve this guide

Have feedback or a question? Found a typo? Like all Gradle guides, help is just a GitHub issue away. Please add an issue or pull request to gradle-guides/building-groovy-libraries and we’ll get back to you.