Gradle

A better way to build

Version 1.0-milestone-1

Hans Dockter

Adam Murdoch

Copyright © 2007-2010 Hans Dockter, Adam Murdoch

Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.

Table of Contents

1. Introduction

1.1. About this user guide

2. Overview

2.1. Features
2.2. Why Groovy?

3. Tutorials

3.1. Getting Started

4. Installing Gradle

4.1. Prerequisites
4.2. Download
4.3. Unpacking
4.4. Environment variables
4.5. Running and testing your installation
4.6. JVM options

5. Build Script Basics

5.1. Projects and tasks
5.2. Hello world
5.3. A shortcut task definition
5.4. Build scripts are code
5.5. Task dependencies
5.6. Dynamic tasks
5.7. Manipulating existing tasks
5.8. Shortcut notations
5.9. Dynamic task properties
5.10. Using Ant Tasks
5.11. Using methods
5.12. Default tasks
5.13. Configure by DAG
5.14. Summary

6. Java Quickstart

6.1. The Java plugin
6.2. A basic Java project
6.3. Multi-project Java build
6.4. Summary

7. Groovy Quickstart

7.1. A basic Groovy project
7.2. Summary

8. Web Application Quickstart

8.1. Building a WAR file
8.2. Running your web application
8.3. Summary

9. Artifact Basics

9.1. Artifact configurations
9.2. Repositories
9.3. External dependencies
9.4. Artifact publishing
9.5. API

10. Using the Gradle Command-Line

10.1. Executing multiple tasks
10.2. Excluding tasks
10.3. Task name abbreviation
10.4. Selecting which build to execute
10.5. Obtaining information about your build
10.6. Dry Run
10.7. Summary

11. Using the Gradle Graphical User Interface

11.1. Task Tree
11.2. Favorites
11.3. Command Line
11.4. Setup

12. Tutorial - 'This and That'

12.1. Directory creation
12.2. Gradle properties and system properties
12.3. Accessing the web via a proxy
12.4. Configuring the project using an external build script
12.5. Configuring arbitrary objects
12.6. Configuring arbitrary objects using an external script
12.7. Caching

13. Writing Build Scripts

13.1. The Gradle build language
13.2. The Project API
13.3. The Script API
13.4. Some Groovy basics

14. More about Tasks

14.1. Defining tasks
14.2. Locating tasks
14.3. Configuring tasks
14.4. Adding dependencies to a task
14.5. Adding a description to a task
14.6. Replacing tasks
14.7. Skipping tasks
14.8. Skipping tasks that are up-to-date
14.9. Task rules
14.10. Summary

15. Working With Files

15.1. Locating files
15.2. File collections
15.3. File trees
15.4. Using the contents of an archive as a file tree
15.5. Specifying a set of input files
15.6. Copying files
15.7. Using the Sync task
15.8. Creating archives

16. Logging

16.1. Choosing a log level
16.2. Writing your own log messages
16.3. Logging from external tools and libraries
16.4. Changing what Gradle logs

17. Using Ant from Gradle

17.1. Using Ant tasks and types in your build
17.2. Importing an Ant build
17.3. Ant properties and references
17.4. API

18. Using Plugins

18.1. Declaring plugins
18.2. Using the convention object

19. Standard Gradle plugins

19.1. Language plugins
19.2. Integration plugins
19.3. Software development plugins
19.4. Base plugins
19.5. Third party plugins

20. The Java Plugin

20.1. Usage
20.2. Source sets
20.3. Tasks
20.4. Project layout
20.5. Dependency management
20.6. Convention properties
20.7. Working with source sets
20.8. Javadoc
20.9. Clean
20.10. Resources
20.11. CompileJava
20.12. Test
20.13. Jar
20.14. Uploading

21. The Groovy Plugin

21.1. Usage
21.2. Tasks
21.3. Project layout
21.4. Dependency management
21.5. Convention properties
21.6. Source set properties
21.7. CompileGroovy

22. The Scala Plugin

22.1. Usage
22.2. Tasks
22.3. Project layout
22.4. Dependency Management
22.5. Convention Properties
22.6. Source set properties

23. The War Plugin

23.1. Usage
23.2. Tasks
23.3. Project layout
23.4. Dependency management
23.5. Convention properties
23.6. War
23.7. Customizing

24. The Jetty Plugin

24.1. Usage
24.2. Tasks
24.3. Project layout
24.4. Dependency management
24.5. Convention properties

25. The Code Quality Plugin

25.1. Usage
25.2. Tasks
25.3. Project layout
25.4. Dependency management
25.5. Convention properties

26. The OSGi Plugin

26.1. Usage
26.2. Implicitly applied plugins
26.3. Tasks
26.4. Dependency management
26.5. Convention object
26.6.

27. The Eclipse Plugin

27.1. Usage
27.2. Tasks
27.3. Customizing the generated files

28. The IDEA Plugin

28.1. Usage
28.2. Tasks
28.3. Customizing the generated files
28.4. Further things to consider

29. The Antlr Plugin

29.1. Usage
29.2. Tasks
29.3. Project layout
29.4. Dependency management
29.5. Convention properties
29.6. Source set properties

30. The Project Report Plugin

30.1. Usage
30.2. Tasks
30.3. Project layout
30.4. Dependency management
30.5. Convention properties

31. The Announce Plugin

31.1. Usage
31.2. Tasks
31.3. Project layout
31.4. Dependency management
31.5. Convention properties

32. The Application Plugin

32.1. Usage
32.2. Tasks
32.3. Convention properties

33. Dependency Management

33.1. Introduction
33.2. Dependency management overview
33.3. How to declare your dependencies
33.4. Working with dependencies
33.5. Repositories
33.6. Strategies for transitive dependency management

34. Artifact Management

34.1. Introduction
34.2. Artifacts and configurations
34.3. Uploading artifacts
34.4. More about project libraries

35. The Maven Plugin

35.1. Usage
35.2. Tasks
35.3. Dependency management
35.4. Convention properties
35.5. Convention methods
35.6. Interacting with Maven repositories

36. The Build Lifecycle

36.1. Build phases
36.2. Settings file
36.3. Multi-project builds
36.4. Initialization
36.5. Configuration and execution of a single project build
36.6. Responding to the lifecycle in the build script

37. Multi-project Builds

37.1. Cross project configuration
37.2. Subproject configuration
37.3. Execution rules for multi-project builds
37.4. Running tasks by their absolute path
37.5. Project and task paths
37.6. Dependencies - Which dependencies?
37.7. Project lib dependencies
37.8. Multi-Project Building and Testing
37.9. Property and method inheritance
37.10. Summary

38. Writing Custom Task Classes

38.1. Packaging a task class
38.2. Writing a simple task class
38.3. A standalone project

39. Writing Custom Plugins

39.1. Packaging a plugin
39.2. Writing a simple plugin
39.3. Getting input from the build
39.4. A standalone project
39.5. Maintaining multiple domain objects

40. Organizing Build Logic

40.1. Inherited properties and methods
40.2. Injected configuration
40.3. Build sources in the buildSrc project
40.4. Running another Gradle build from a build
40.5. External dependencies for the build script
40.6. Ant optional dependencies
40.7. Summary

41. Initialization Scripts

41.1. Basic usage
41.2. Writing an init script
41.3. External dependencies for the init script

42. The Gradle Wrapper

42.1. Configuration
42.2. Unix file permissions
42.3. Environment variable

43. Embedding Gradle

A. Gradle Samples

A.1. Sample customBuildLanguage
A.2. Sample java/multiproject

B. Potential Traps

B.1. Groovy script variables
B.2. Configuration and execution phase

C. Gradle Command Line

C.1. Deprecated command-line options
C.2. Experimental command-line options
C.3. System properties
C.4. Environment variables

D. Existing IDE Support and how to cope without it

D.1. IntelliJ
D.2. Eclipse
D.3. Using Gradle without IDE support

List of Examples

5.1. The first build script
5.2. Execution of a build script
5.3. A task definition shortcut
5.4. Using Groovy in Gradle's tasks
5.5. Using Groovy in Gradle's tasks
5.6. Declaration of dependencies between tasks
5.7. Lazy dependsOn - the other task does not exist (yet)
5.8. Dynamic creation of a task
5.9. Accessing a task via API - adding a dependency
5.10. Accessing a task via API - adding behaviour
5.11. Accessing task as a property of the build script
5.12. Assigning properties to a task
5.13. Using AntBuilder to execute ant.checksum target
5.14. Using methods to organize your build logic
5.15. Defining a default tasks
5.16. Different outcomes of build depending on chosen tasks
6.1. Using the Java plugin
6.2. Building a Java project
6.3. Adding Maven repository
6.4. Adding dependencies
6.5. Customization of MANIFEST.MF
6.6. Adding a test system property
6.7. Publishing the JAR file
6.8. Eclipse plugin
6.9. Java example - complete build file
6.10. Multi-project build - hierarchical layout
6.11. Multi-project build - settings.gradle file
6.12. Multi-project build - common configuration
6.13. Multi-project build - dependencies between projects
6.14. Multi-project build - distribution file
7.1. Groovy plugin
7.2. Dependency on Groovy 1.6.0
7.3. Groovy example - complete build file
8.1. War plugin
8.2. Running web application with Jetty plugin
9.1. Definition of a configuration
9.2. Accessing a configuration
9.3. Configuration of a configuration
9.4. Usage of Maven central repository
9.5. Usage of a local directory
9.6. Accessing a repository
9.7. Configuration of a repository
9.8. Definition of an external dependency
9.9. Usage of external dependency of a configuration
10.1. Executing multiple tasks
10.2. Excluding tasks
10.3. Abbreviated task name
10.4. Abbreviated camel case task name
10.5. Selecting the project using a build file
10.6. Selecting the project using project directory
10.7. Obtaining information about projects
10.8. Providing a description for a project
10.9. Obtaining information about tasks
10.10. Changing the content of the task report
10.11. Obtaining more information about tasks
10.12. Obtaining information about dependencies
10.13. Information about properties
11.1. Launching the GUI
12.1. Directory creation with mkdir
12.2. Directory creation with Directory tasks
12.3. Setting properties with a gradle.properties file
12.4. Accessing the web via a proxy
12.5. Configuring the project using an external build script
12.6. Configuring arbitrary objects
12.7. Configuring arbitrary objects using a script
13.1. Accessing property of the Project object
13.2. Groovy JDK methods
13.3. Property accessors
13.4. Method call without parentheses
13.5. List and map literals
13.6. Closure as method parameter
13.7. Closure delegates
14.1. Defining tasks
14.2. Defining tasks - using strings
14.3. Defining tasks with alternative syntax
14.4. Accessing tasks as properties
14.5. Accessing tasks via tasks collection
14.6. Accessing tasks by path
14.7. Creating a copy task
14.8. Configuring a task - various ways
14.9. Configuring a task - fluent interface
14.10. Configuring a task - with closure
14.11. Configuring a task - with configure() method
14.12. Defining a task with closure
14.13. Adding dependency on task from another project
14.14. Adding dependency using task object
14.15. Adding dependency using closure
14.16. Adding a description to a task
14.17. Overwriting a task
14.18. Skipping a task using a predicate
14.19. Skipping tasks with StopExecutionException
14.20. Enabling and disabling tasks
14.21. A generator task
14.22. Declaring the inputs and outputs of a task
14.23. Task rule
14.24. Dependency on rule based tasks
15.1. Locating files
15.2. Creating a file collection
15.3. Using a file collection
15.4. Implementing a file collection
15.5. Creating a file tree
15.6. Using a file tree
15.7. Using an archive as a file tree
15.8. Specifying a set of files
15.9. Specifying a set of files
15.10. Copying files using the copy task
15.11. Specifying copy task source files and destination directory
15.12. Selecting the files to copy
15.13. Copying files using the copy() method
15.14. Renaming files as they are copied
15.15. Filtering files as they are copied
15.16. Nested copy specs
15.17. Using the Sync task to copy dependencies
15.18. Creating a ZIP archive
15.19. Creation of ZIP archive
15.20. Configuration of archive task - custom archive name
15.21. Configuration of archive task - appendix & classifier
16.1. Using stdout to write log messages
16.2. Writing your own log messages
16.3. Using SLF4J to write log messages
16.4. Configuring standard output capture
16.5. Configuring standard output capture for a task
16.6. Customizing what Gradle logs
17.1. Using an Ant task
17.2. Passing nested text to an Ant task
17.3. Passing nested elements to an Ant task
17.4. Using an Ant type
17.5. Using a custom Ant task
17.6. Declaring the classpath for a custom Ant task
17.7. Using a custom Ant task and dependency management together
17.8. Importing an Ant build
17.9. Task that depends on Ant target
17.10. Adding behaviour to an Ant target
17.11. Ant target that depends on Gradle task
17.12. Setting an Ant property
17.13. Getting an Ant property
17.14. Setting an Ant reference
17.15. Getting an Ant reference
18.1. Using a plugin
18.2. Applying a plugin by id
18.3. Applying a plugin by type
18.4. Applying a plugin by type
18.5. Configuring a plugin task
18.6. Plugin convention object
18.7. Using the plugin convention object
18.8. Explicit application of an implied plugin
20.1. Using the Java plugin
20.2. Custom Java source layout
20.3. Accessing a source set
20.4. Configuring the source directories of a source set
20.5. Defining a source set
20.6. Defining the classpath of a source set
20.7. Assembling a JAR for a source set
20.8. Generating the Javadoc for a source set
20.9. Running tests in a source set
20.10. Customization of MANIFEST.MF
20.11. Creating a manifest object.
20.12. Separate MANIFEST.MF for a particular archive
20.13. Separate MANIFEST.MF for a particular archive
21.1. Using the Groovy plugin
21.2. Custom Groovy source layout
21.3. Configuration of Groovy plugin
21.4. Configuration of Groovy plugin
22.1. Using the Scala plugin
22.2. Custom Scala source layout
22.3. Declaring the Scala version to use
23.1. Using the War plugin
23.2. Customization of war plugin
23.3. Generation of JAR archive in addition to WAR archive
24.1. Using the Jetty plugin
25.1. Using the code quality plugin
26.1. Using the OSGi plugin
26.2. Configuration of OSGi MANIFEST.MF file
27.1. Using the Eclipse plugin
27.2. Partial Overwrite for Classpath
27.3. Partial Overwrite for Project
27.4. Export Dependencies
27.5. Customizing the XML
28.1. Using the IDEA plugin
28.2. Partial Overwrite for Module
28.3. Partial Overwrite for Project
28.4. Export Dependencies
28.5. Customizing the XML
29.1. Using the Antlr plugin
29.2. Declare Antlr version
31.1. Using the announce plugin
31.2. Configure the announce plugin
31.3. Using the announce plugin
32.1. Using the application plugin
32.2. Configure the application main class
33.1. Module dependencies
33.2. Artifact only notation
33.3. Dependency with classifier
33.4. Client module dependencies - transitive dependencies
33.5. Project dependencies
33.6. File dependencies
33.7. Generated file dependencies
33.8. Gradle API dependencies
33.9. Excluding transitive dependencies
33.10. Optional attributes of dependencies
33.11. Collections and arrays of dependencies
33.12. Dependency configurations
33.13. Dependency configurations for project
33.14. Configuration.copy
33.15. Accessing declared dependencies
33.16. Configuration.files
33.17. Configuration.files with spec
33.18. Configuration.copy
33.19. Configuration.copy vs. Configuration.files
33.20. Adding central Maven repository
33.21. Adding several Maven repositories
33.22. Adding custom Maven repository
33.23. Adding additional Maven repositories for JAR files
33.24. Adding the local Maven cache as a repository
33.25. Accessing password protected Maven repository
33.26. Flat repository resolver
33.27. Definition of a custom repository
34.1. Assignment of an artifact to a configuration
34.2. Configuration of the upload task
35.1. Using the Maven plugin
35.2. Creating a stand alone pom.
35.3. Upload of file to remote Maven repository
35.4. Upload of file via SSH
35.5. Customization of pom
35.6. Builder style customization of pom
35.7. Modifying auto-generated content
35.8. Customization of Maven installer
35.9. Generation of multiple poms
35.10. Accessing a mapping configuration
36.1. Single project build
36.2. Hierarchical layout
36.3. Flat layout
36.4. Modification of elements of the project tree
36.5. Modification of elements of the project tree
36.6. Adding of test task to each project which has certain property set
36.7. Notifications
36.8. Setting of certain property to all tasks
36.9. Logging of start and end of each task execution
37.1. Multi-project tree - water & bluewhale projects
37.2. Build script of water (parent) project
37.3. Multi-project tree - water, bluewhale & krill projects
37.4. Water project build script
37.5. Defining common behaviour of all projects and subprojects
37.6. Defining specific behaviour for particular project
37.7. Defining specific behaviour for project krill
37.8. Adding custom behaviour to some projects (filtered by project name)
37.9. Adding custom behaviour to some projects (filtered by project properties)
37.10. Running build from subproject
37.11. Evaluation and execution of projects
37.12. Evaluation and execution of projects
37.13. Running tasks by their absolute path
37.14. Dependencies and execution order
37.15. Dependencies and execution order
37.16. Dependencies and execution order
37.17. Declaring dependencies
37.18. Declaring dependencies
37.19. Project execution dependencies
37.20. Cross project task dependencies
37.21. Configuration time dependencies
37.22. Configuration time dependencies - evaluationDependsOn
37.23. Configuration time dependencies
37.24. Dependencies - real life example - crossproject configuration
37.25. Project lib dependencies
37.26. Project lib dependencies
37.27. Fine grained control over dependencies
37.28. Build and Test Single Project
37.29. Partial Build and Test Single Project
37.30. Build and Test Depended On Projects
37.31. Build and Test Dependent Projects
38.1. Defining a custom task
38.2. A hello world task
38.3. A customizable hello world task
38.4. A build for a custom task
38.5. A custom task
38.6. Using a custom task in another project
38.7. Testing a custom task
39.1. A custom plugin
39.2. A custom plugin convention
39.3. A custom plugin with closure convention
39.4. A build for a custom plugin
39.5. Wiring for a custom plugin
39.6. Using a custom plugin in another project
39.7. Testing a custom plugin
39.8. Managing domain objects
40.1. Using inherited properties and methods
40.2. Using injected properties and methods
40.3. Running another build from a build
40.4. Declaring external dependencies for the build script
40.5. A build script with external dependencies
40.6. Ant optional dependencies
41.1. Declaring external dependencies for an init script
41.2. An init script with external dependencies
42.1. Wrapper task
42.2. Wrapper generated files
42.3. Configuration of wrapper task
B.1. Variables scope: local and script wide
B.2. Distinct configuration and execution phase