Gradle

A better way to build

Version 0.9.1

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. Dependency Management
32.1. Introduction
32.2. Dependency management overview
32.3. How to declare your dependencies
32.4. Working with dependencies
32.5. Repositories
32.6. Strategies for transitive dependency management
33. Artifact Management
33.1. Introduction
33.2. Artifacts and configurations
33.3. Uploading artifacts
33.4. More about project libraries
34. The Maven Plugin
34.1. Usage
34.2. Tasks
34.3. Dependency management
34.4. Convention properties
34.5. Convention methods
34.6. Interacting with Maven repositories
35. The Build Lifecycle
35.1. Build phases
35.2. Settings file
35.3. Multi-project builds
35.4. Initialization
35.5. Configuration and execution of a single project build
35.6. Responding to the lifecycle in the build script
36. Multi-project Builds
36.1. Cross project configuration
36.2. Subproject configuration
36.3. Execution rules for multi-project builds
36.4. Running tasks by their absolute path
36.5. Project and task paths
36.6. Dependencies - Which dependencies?
36.7. Project lib dependencies
36.8. Multi-Project Building and Testing
36.9. Property and method inheritance
36.10. Summary
37. Writing Custom Tasks
37.1. Packaging a task
37.2. Writing a simple task
37.3. A standalone project
38. Writing Custom Plugins
38.1. Packaging a plugin
38.2. Writing a simple plugin
38.3. Getting input from the build
39. Organizing Build Logic
39.1. Inherited properties and methods
39.2. Injected configuration
39.3. Build sources in the buildSrc project
39.4. Running another Gradle build from a build
39.5. External dependencies for the build script
39.6. Ant optional dependencies
39.7. Summary
40. Initialization Scripts
40.1. Basic usage
40.2. Writing an init script
40.3. External dependencies for the init script
41. The Gradle Wrapper
41.1. Configuration
41.2. Unix file permissions
41.3. Environment variable
42. 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
Glossary

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 Module
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. Module dependencies
32.2. Artifact only notation
32.3. Dependency with classifier
32.4. Client module dependencies - transitive dependencies
32.5. Project dependencies
32.6. File dependencies
32.7. Generated file dependencies
32.8. Gradle API dependencies
32.9. Excluding transitive dependencies
32.10. Optional attributes of dependencies
32.11. Collections and arrays of dependencies
32.12. Dependency configurations
32.13. Dependency configurations for project
32.14. Configuration.copy
32.15. Accessing declared dependencies
32.16. Configuration.files
32.17. Configuration.files with spec
32.18. Configuration.copy
32.19. Configuration.copy vs. Configuration.files
32.20. Adding central Maven repository
32.21. Adding several Maven repositories
32.22. Adding custom Maven repository
32.23. Adding additional Maven repositories for JAR files
32.24. Adding the local Maven cache as a repository
32.25. Accessing password protected Maven repository
32.26. Flat repository resolver
32.27. Definition of a custom repository
33.1. Assignment of an artifact to a configuration
33.2. Configuration of the upload task
34.1. Using the Maven plugin
34.2. Creating a stand alone pom.
34.3. Upload of file to remote Maven repository
34.4. Upload of file via SSH
34.5. Customization of pom
34.6. Builder style customization of pom
34.7. Modifying auto-generated content
34.8. Customization of Maven installer
34.9. Generation of multiple poms
34.10. Accessing a mapping configuration
35.1. Single project build
35.2. Hierarchical layout
35.3. Flat layout
35.4. Modification of elements of the project tree
35.5. Modification of elements of the project tree
35.6. Adding of test task to each project which has certain property set
35.7. Notifications
35.8. Setting of certain property to all tasks
35.9. Logging of start and end of each task execution
36.1. Multi-project tree - water & bluewhale projects
36.2. Build script of water (parent) project
36.3. Multi-project tree - water, bluewhale & krill projects
36.4. Water project build script
36.5. Defining common behaviour of all projects and subprojects
36.6. Defining specific behaviour for particular project
36.7. Defining specific behaviour for project krill
36.8. Adding custom behaviour to some projects (filtered by project name)
36.9. Adding custom behaviour to some projects (filtered by project properties)
36.10. Running build from subproject
36.11. Evaluation and execution of projects
36.12. Evaluation and execution of projects
36.13. Running tasks by their absolute path
36.14. Dependencies and execution order
36.15. Dependencies and execution order
36.16. Dependencies and execution order
36.17. Declaring dependencies
36.18. Declaring dependencies
36.19. Project execution dependencies
36.20. Cross project task dependencies
36.21. Configuration time dependencies
36.22. Configuration time dependencies - evaluationDependsOn
36.23. Configuration time dependencies
36.24. Dependencies - real life example - crossproject configuration
36.25. Project lib dependencies
36.26. Project lib dependencies
36.27. Fine grained control over dependencies
36.28. Build and Test Single Project
36.29. Partial Build and Test Single Project
36.30. Build and Test Depended On Projects
36.31. Build and Test Dependent Projects
37.1. Defining a custom task
37.2. A hello world task
37.3. A customizable hello world task
37.4. A build for a custom task
37.5. A custom task
37.6. Testing a custom task
38.1. A custom plugin
38.2. A custom plugin convention
38.3. A custom plugin with closure convention
39.1. Using inherited properties and methods
39.2. Using injected properties and methods
39.3. Running another build from a build
39.4. Declaring external dependencies for the build script
39.5. A build script with external dependencies
39.6. Ant optional dependencies
40.1. Declaring external dependencies for an init script
40.2. An init script with external dependencies
41.1. Wrapper task
41.2. Wrapper generated files
41.3. Configuration of wrapper task
B.1. Variables scope: local and script wide
B.2. Distinct configuration and execution phase