gradle教程 1. Building Groovy Librares

Building Groovy Libraries

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

What you’ll need

• About 8 minutes

• A text editor

• A command prompt

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

• A Gradle distribution, version 4.5 or better

Gradle comes with a built-in plugin called the Build Init plugin. 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.

Build Init plugin - tasks

Task name	Depends on	Type	Description
init	wrapper	InitBuild	Generates a Gradle project.
wrapper	-	Wrapper	Generates Gradle wrapper files.

What to set up

The init supports different build setup types. The type is specified by supplying a --typeargument value. 

• If a --type parameter is not supplied, Gradle will attempt to infer the type from the environment. For example, it will infer a type value of “pom” 
• if it finds a pom.xml to convert to a Gradle build. If the type could not be inferred, the type “basic” will be used.

Build init types -“groovy-library”

The “groovy-library” build init type is not inferable. It must be explicitly specified.

It has the following features:

• Uses the “groovy” plugin to produce a library Jar

• Uses the “jcenter” dependency repository

• Uses Groovy 2.x

• Uses Spock testing framework for testing

• Has directories in the conventional locations for source code

• Contains a sample Groovy class and an associated Spock specification, if there are no existing source or test files

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 in 1m 37s
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
│       └── 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

plugins {
    id 'groovy'
}

dependencies {
    compile 'org.codehaus.groovy:groovy-all:2.4.12' 2

    testCompile 'org.spockframework:spock-core:1.0-groovy-2.4' 3
}

repositories {
    jcenter() 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 someLibraryMethodmethod, 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 in 3m 45s
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:

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 in 1m 8s
2 actionable tasks: 2 executed

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.