Gradle

A better way to build

Version 1.0-milestone-2

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
22.7. Fast Scala Compiler
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 Sonar Plugin
26.1. Usage
26.2. Tasks
26.3. Limitations
27. The OSGi Plugin
27.1. Usage
27.2. Implicitly applied plugins
27.3. Tasks
27.4. Dependency management
27.5. Convention object
27.6.
28. The Eclipse Plugin
28.1. Usage
28.2. Tasks
28.3. Customizing the generated files
29. The IDEA Plugin
29.1. Usage
29.2. Tasks
29.3. Customizing the generated files
29.4. Further things to consider
30. The Antlr Plugin
30.1. Usage
30.2. Tasks
30.3. Project layout
30.4. Dependency management
30.5. Convention properties
30.6. Source set properties
31. The Project Report Plugin
31.1. Usage
31.2. Tasks
31.3. Project layout
31.4. Dependency management
31.5. Convention properties
32. The Announce Plugin
32.1. Usage
32.2. Tasks
32.3. Project layout
32.4. Dependency management
32.5. Convention properties
33. The Application Plugin
33.1. Usage
33.2. Tasks
33.3. Convention properties
34. Dependency Management
34.1. Introduction
34.2. Dependency management overview
34.3. How to declare your dependencies
34.4. Working with dependencies
34.5. Repositories
34.6. Strategies for transitive dependency management
35. Artifact Management
35.1. Introduction
35.2. Artifacts and configurations
35.3. Uploading artifacts
35.4. More about project libraries
36. The Maven Plugin
36.1. Usage
36.2. Tasks
36.3. Dependency management
36.4. Convention properties
36.5. Convention methods
36.6. Interacting with Maven repositories
37. The Build Lifecycle
37.1. Build phases
37.2. Settings file
37.3. Multi-project builds
37.4. Initialization
37.5. Configuration and execution of a single project build
37.6. Responding to the lifecycle in the build script
38. Multi-project Builds
38.1. Cross project configuration
38.2. Subproject configuration
38.3. Execution rules for multi-project builds
38.4. Running tasks by their absolute path
38.5. Project and task paths
38.6. Dependencies - Which dependencies?
38.7. Project lib dependencies
38.8. Multi-Project Building and Testing
38.9. Property and method inheritance
38.10. Summary
39. Writing Custom Task Classes
39.1. Packaging a task class
39.2. Writing a simple task class
39.3. A standalone project
40. Writing Custom Plugins
40.1. Packaging a plugin
40.2. Writing a simple plugin
40.3. Getting input from the build
40.4. A standalone project
40.5. Maintaining multiple domain objects
41. Organizing Build Logic
41.1. Inherited properties and methods
41.2. Injected configuration
41.3. Build sources in the buildSrc project
41.4. Running another Gradle build from a build
41.5. External dependencies for the build script
41.6. Ant optional dependencies
41.7. Summary
42. Initialization Scripts
42.1. Basic usage
42.2. Writing an init script
42.3. External dependencies for the init script
43. The Gradle Wrapper
43.1. Configuration
43.2. Unix file permissions
43.3. Environment variable
44. 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.loadfile 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
22.4. Enabling the Fast Scala Compiler
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 Sonar plugin
26.2. Configuring connection settings
27.1. Using the OSGi plugin
27.2. Configuration of OSGi MANIFEST.MF file
28.1. Using the Eclipse plugin
28.2. Partial Overwrite for Classpath
28.3. Partial Overwrite for Project
28.4. Export Dependencies
28.5. Customizing the XML
29.1. Using the IDEA plugin
29.2. Partial Overwrite for Module
29.3. Partial Overwrite for Project
29.4. Export Dependencies
29.5. Customizing the XML
30.1. Using the Antlr plugin
30.2. Declare Antlr version
32.1. Using the announce plugin
32.2. Configure the announce plugin
32.3. Using the announce plugin
33.1. Using the application plugin
33.2. Configure the application main class
34.1. Module dependencies
34.2. Artifact only notation
34.3. Dependency with classifier
34.4. Client module dependencies - transitive dependencies
34.5. Project dependencies
34.6. File dependencies
34.7. Generated file dependencies
34.8. Gradle API dependencies
34.9. Excluding transitive dependencies
34.10. Optional attributes of dependencies
34.11. Collections and arrays of dependencies
34.12. Dependency configurations
34.13. Dependency configurations for project
34.14. Configuration.copy
34.15. Accessing declared dependencies
34.16. Configuration.files
34.17. Configuration.files with spec
34.18. Configuration.copy
34.19. Configuration.copy vs. Configuration.files
34.20. Adding central Maven repository
34.21. Adding several Maven repositories
34.22. Adding custom Maven repository
34.23. Adding additional Maven repositories for JAR files
34.24. Adding the local Maven cache as a repository
34.25. Accessing password protected Maven repository
34.26. Flat repository resolver
34.27. Definition of a custom repository
35.1. Assignment of an artifact to a configuration
35.2. Configuration of the upload task
36.1. Using the Maven plugin
36.2. Creating a stand alone pom.
36.3. Upload of file to remote Maven repository
36.4. Upload of file via SSH
36.5. Customization of pom
36.6. Builder style customization of pom
36.7. Modifying auto-generated content
36.8. Customization of Maven installer
36.9. Generation of multiple poms
36.10. Accessing a mapping configuration
37.1. Single project build
37.2. Hierarchical layout
37.3. Flat layout
37.4. Modification of elements of the project tree
37.5. Modification of elements of the project tree
37.6. Adding of test task to each project which has certain property set
37.7. Notifications
37.8. Setting of certain property to all tasks
37.9. Logging of start and end of each task execution
38.1. Multi-project tree - water & bluewhale projects
38.2. Build script of water (parent) project
38.3. Multi-project tree - water, bluewhale & krill projects
38.4. Water project build script
38.5. Defining common behaviour of all projects and subprojects
38.6. Defining specific behaviour for particular project
38.7. Defining specific behaviour for project krill
38.8. Adding custom behaviour to some projects (filtered by project name)
38.9. Adding custom behaviour to some projects (filtered by project properties)
38.10. Running build from subproject
38.11. Evaluation and execution of projects
38.12. Evaluation and execution of projects
38.13. Running tasks by their absolute path
38.14. Dependencies and execution order
38.15. Dependencies and execution order
38.16. Dependencies and execution order
38.17. Declaring dependencies
38.18. Declaring dependencies
38.19. Project execution dependencies
38.20. Cross project task dependencies
38.21. Configuration time dependencies
38.22. Configuration time dependencies - evaluationDependsOn
38.23. Configuration time dependencies
38.24. Dependencies - real life example - crossproject configuration
38.25. Project lib dependencies
38.26. Project lib dependencies
38.27. Fine grained control over dependencies
38.28. Build and Test Single Project
38.29. Partial Build and Test Single Project
38.30. Build and Test Depended On Projects
38.31. Build and Test Dependent Projects
39.1. Defining a custom task
39.2. A hello world task
39.3. A customizable hello world task
39.4. A build for a custom task
39.5. A custom task
39.6. Using a custom task in another project
39.7. Testing a custom task
40.1. A custom plugin
40.2. A custom plugin convention
40.3. A custom plugin with closure convention
40.4. A build for a custom plugin
40.5. Wiring for a custom plugin
40.6. Using a custom plugin in another project
40.7. Testing a custom plugin
40.8. Managing domain objects
41.1. Using inherited properties and methods
41.2. Using injected properties and methods
41.3. Running another build from a build
41.4. Declaring external dependencies for the build script
41.5. A build script with external dependencies
41.6. Ant optional dependencies
42.1. Declaring external dependencies for an init script
42.2. An init script with external dependencies
43.1. Wrapper task
43.2. Wrapper generated files
43.3. Configuration of wrapper task
B.1. Variables scope: local and script wide
B.2. Distinct configuration and execution phase