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

What you’ll need

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 demo
$ cd demo

Run the init task

From inside the new project directory, run the init task, selecting first the 3: library type and then 2: Groovy language.

$ gradle init
> Task :wrapper

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

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

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

Project name (default: demo):

Source package (default: demo):

> Task :init
Get more help with your project:

2 actionable tasks: 2 executed

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
│       └──
├── gradlew
├── gradlew.bat
├── settings.gradle
└── src
    ├── main
    │   └── groovy  (2)
    │       └── demo
    │           └── Library.groovy
    └── test
        └── groovy (3)
            └── demo
                └── 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 = 'demo' (1)
1 This assigns the name of the root project, which overrides the default behavior of naming the project after the directory it’s in.

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
plugins {
    id 'groovy' (1)
    id 'java-library' (2)

repositories {
    jcenter() (3)

dependencies {
    implementation 'org.codehaus.groovy:groovy-all:2.5.7' (4)

    testImplementation 'org.spockframework:spock-core:1.3-groovy-2.5' (5)
1 Use the groovy plugin
2 Use the java-library plugin
3 Public Bintray Artifactory repository
4 Groovy version that this project will include as dependency
5 Spock Framework testing library

The build file adds the groovy and java-library plugins. The groovy one is an extension of the java plugin 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 java-library one configures to project to offer API / implementation separation.

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

Generated src/main/groovy/demo/Library.groovy
package demo

class Library {
    boolean someLibraryMethod() {

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

Generated src/test/groovy/demo/LibraryTest.groovy
 * This Spock specification was generated by the Gradle 'init' task.
package demo

import spock.lang.Specification

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

        def result = lib.someLibraryMethod()

        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
> Task :compileJava NO-SOURCE
> Task :compileGroovy
> Task :processResources NO-SOURCE
> Task :classes
> Task :jar
> Task :assemble
> Task :compileTestJava NO-SOURCE
> Task :compileTestGroovy
> Task :processTestResources NO-SOURCE
> Task :testClasses

> Task :test

> Task :check
> Task :build

4 actionable tasks: 4 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.

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.

 * This Groovy source file was generated by the Gradle 'init' task.
package demo

class Library {
    boolean someLibraryMethod() {

Run the groovydoc task.

$ ./gradlew groovydoc
> Task :compileJava NO-SOURCE
> Task :compileGroovy
> Task :processResources NO-SOURCE
> Task :classes

> Task :groovydoc

2 actionable tasks: 2 executed

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


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 and we’ll get back to you.