Gradle

A better way to build

Version 1.0-milestone-7

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. Where to next?
6. Java Quickstart
6.1. The Java plugin
6.2. A basic Java project
6.3. Multi-project Java build
6.4. Where to next?
7. Dependency Management Basics
7.1. What is dependency management?
7.2. Declaring your dependencies
7.3. Dependency configurations
7.4. External dependencies
7.5. Repositories
7.6. Publishing artifacts
7.7. Where to next?
8. Groovy Quickstart
8.1. A basic Groovy project
8.2. Summary
9. Web Application Quickstart
9.1. Building a WAR file
9.2. Running your web application
9.3. Summary
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. Experimental language plugins
19.3. Integration plugins
19.4. Software development plugins
19.5. Base plugins
19.6. 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 Ear Plugin
24.1. Usage
24.2. Tasks
24.3. Project layout
24.4. Dependency management
24.5. Convention properties
24.6. Ear
24.7. Customizing
24.8. Using custom descriptor file
25. The Jetty Plugin
25.1. Usage
25.2. Tasks
25.3. Project layout
25.4. Dependency management
25.5. Convention properties
26. The Code Quality Plugin
26.1. Usage
26.2. Tasks
26.3. Project layout
26.4. Dependency management
26.5. Convention properties
27. The Sonar Plugin
27.1. Usage
27.2. Analyzing Multi-Project Builds
27.3. Analyzing Custom Source Sets
27.4. Setting Custom Sonar Properties
27.5. Tasks
28. The OSGi Plugin
28.1. Usage
28.2. Implicitly applied plugins
28.3. Tasks
28.4. Dependency management
28.5. Convention object
28.6.
29. The Eclipse Plugin
29.1. Usage
29.2. Tasks
29.3. Configuration
29.4. Customizing the generated files
30. The IDEA Plugin
30.1. Usage
30.2. Tasks
30.3. Configuration
30.4. Customizing the generated files
30.5. Further things to consider
31. The Antlr Plugin
31.1. Usage
31.2. Tasks
31.3. Project layout
31.4. Dependency management
31.5. Convention properties
31.6. Source set properties
32. The Project Report Plugin
32.1. Usage
32.2. Tasks
32.3. Project layout
32.4. Dependency management
32.5. Convention properties
33. The Announce Plugin
33.1. Usage
33.2. Tasks
33.3. Project layout
33.4. Dependency management
33.5. Convention properties
34. The Build Announcements Plugin
34.1. Usage
35. The Application Plugin
35.1. Usage
35.2. Tasks
35.3. Convention properties
35.4. Including other resources in the distribution
36. Dependency Management
36.1. Introduction
36.2. Dependency management overview
36.3. Dependency configurations
36.4. How to declare your dependencies
36.5. Working with dependencies
36.6. Repositories
36.7. Strategies for transitive dependency management
37. Publishing artifacts
37.1. Introduction
37.2. Artifacts and configurations
37.3. Declaring artifacts
37.4. Publishing artifacts
37.5. More about project libraries
38. The Maven Plugin
38.1. Usage
38.2. Tasks
38.3. Dependency management
38.4. Convention properties
38.5. Convention methods
38.6. Interacting with Maven repositories
39. The Signing Plugin
39.1. Usage
39.2. Signatory credentials
39.3. Specifying what to sign
39.4. Publishing the signatures
39.5. Signing POM files
40. C++ Support
40.1. Usage
40.2. Source code locations
40.3. Compiling
40.4. Dependencies
40.5. Publishing
41. The Build Lifecycle
41.1. Build phases
41.2. Settings file
41.3. Multi-project builds
41.4. Initialization
41.5. Configuration and execution of a single project build
41.6. Responding to the lifecycle in the build script
42. Multi-project Builds
42.1. Cross project configuration
42.2. Subproject configuration
42.3. Execution rules for multi-project builds
42.4. Running tasks by their absolute path
42.5. Project and task paths
42.6. Dependencies - Which dependencies?
42.7. Project lib dependencies
42.8. Multi-Project Building and Testing
42.9. Property and method inheritance
42.10. Summary
43. Writing Custom Task Classes
43.1. Packaging a task class
43.2. Writing a simple task class
43.3. A standalone project
44. Writing Custom Plugins
44.1. Packaging a plugin
44.2. Writing a simple plugin
44.3. Getting input from the build
44.4. Working with files in custom tasks and plugins
44.5. A standalone project
44.6. Maintaining multiple domain objects
45. Organizing Build Logic
45.1. Inherited properties and methods
45.2. Injected configuration
45.3. Build sources in the buildSrc project
45.4. Running another Gradle build from a build
45.5. External dependencies for the build script
45.6. Ant optional dependencies
45.7. Summary
46. Initialization Scripts
46.1. Basic usage
46.2. Using an init script
46.3. Writing an init script
46.4. External dependencies for the init script
47. The Gradle Wrapper
47.1. Configuration
47.2. Unix file permissions
47.3. Environment variable
48. Embedding Gradle
A. Gradle Samples
A.1. Sample customBuildLanguage
A.2. Sample customDistribution
A.3. Sample customPlugin
A.4. 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. Declaring dependencies
7.2. Definition of an external dependency
7.3. Shortcut definition of an external dependency
7.4. Usage of Maven central repository
7.5. Usage of a remote Maven repository
7.6. Usage of a remote Ivy directory
7.7. Usage of a local Ivy directory
7.8. Publishing to an Ivy repository
7.9. Publishing to a Maven repository
8.1. Groovy plugin
8.2. Dependency on Groovy 1.6.0
8.3. Groovy example - complete build file
9.1. War plugin
9.2. Running web application with Jetty plugin
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 source set dependencies
20.7. Compiling a source set
20.8. Assembling a JAR for a source set
20.9. Generating the Javadoc for a source set
20.10. Running tests in a source set
20.11. Customization of MANIFEST.MF
20.12. Creating a manifest object.
20.13. Separate MANIFEST.MF for a particular archive
20.14. 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
24.1. Using the Ear plugin
24.2. Customization of ear plugin
25.1. Using the Jetty plugin
26.1. Using the code quality plugin
27.1. Applying the Sonar plugin
27.2. Configuring Sonar connection settings
27.3. Configuring Sonar project settings
27.4. Global configuration in a multi-project build
27.5. Common project configuration in a multi-project build
27.6. Individual project configuration in a multi-project build
27.7. Configuring the language to be analyzed
27.8. Using property syntax
27.9. Analyzing custom source sets
27.10. Setting custom global properties
27.11. Setting custom project properties
28.1. Using the OSGi plugin
28.2. Configuration of OSGi MANIFEST.MF file
29.1. Using the Eclipse plugin
29.2. Partial Overwrite for Classpath
29.3. Partial Overwrite for Project
29.4. Export Dependencies
29.5. Customizing the XML
30.1. Using the IDEA plugin
30.2. Partial Overwrite for Module
30.3. Partial Overwrite for Project
30.4. Export Dependencies
30.5. Customizing the XML
31.1. Using the Antlr plugin
31.2. Declare Antlr version
33.1. Using the announce plugin
33.2. Configure the announce plugin
33.3. Using the announce plugin
34.1. Using the build announcements plugin
34.2. Using the build announcements plugin from an init script
35.1. Using the application plugin
35.2. Configure the application main class
35.3. Include output from other tasks in the application distribution
35.4. Automatically creating files for distribution
36.1. Definition of a configuration
36.2. Accessing a configuration
36.3. Configuration of a configuration
36.4. Module dependencies
36.5. Artifact only notation
36.6. Dependency with classifier
36.7. Usage of external dependency of a configuration
36.8. Client module dependencies - transitive dependencies
36.9. Project dependencies
36.10. File dependencies
36.11. Generated file dependencies
36.12. Gradle API dependencies
36.13. Gradle's Groovy dependencies
36.14. Excluding transitive dependencies
36.15. Dynamic version cache control
36.16. Changing module cache control
36.17. Optional attributes of dependencies
36.18. Collections and arrays of dependencies
36.19. Dependency configurations
36.20. Dependency configurations for project
36.21. Configuration.copy
36.22. Accessing declared dependencies
36.23. Configuration.files
36.24. Configuration.files with spec
36.25. Configuration.copy
36.26. Configuration.copy vs. Configuration.files
36.27. Adding central Maven repository
36.28. Adding the local Maven cache as a repository
36.29. Adding custom Maven repository
36.30. Adding additional Maven repositories for JAR files
36.31. Accessing password protected Maven repository
36.32. Flat repository resolver
36.33. Ivy repository
36.34. Ivy repository with pattern layout
36.35. Ivy repository with custom patterns
36.36. Ivy repository
36.37. Accessing a repository
36.38. Configuration of a repository
36.39. Definition of a custom repository
37.1. Defining an artifact using an archive task
37.2. Defining an artifact using a file
37.3. Customizing an artifact
37.4. Map syntax for defining an artifact using a file
37.5. Configuration of the upload task
38.1. Using the Maven plugin
38.2. Creating a stand alone pom.
38.3. Upload of file to remote Maven repository
38.4. Upload of file via SSH
38.5. Customization of pom
38.6. Builder style customization of pom
38.7. Modifying auto-generated content
38.8. Customization of Maven installer
38.9. Generation of multiple poms
38.10. Accessing a mapping configuration
39.1. Using the Signing plugin
39.2. Signing a configuration
39.3. Signing a configuration output
39.4. Signing a task
39.5. Signing a task output
39.6. Conditional signing
39.7. Signing a POM for deployment
40.1. Using the 'cpp-exe' plugin
40.2. Using the 'cpp-lib' plugin
40.3. Supplying arbitrary args to gpp
40.4. Declaring dependencies
40.5. Declaring project dependencies
40.6. Uploading exe or lib
41.1. Single project build
41.2. Hierarchical layout
41.3. Flat layout
41.4. Modification of elements of the project tree
41.5. Modification of elements of the project tree
41.6. Adding of test task to each project which has certain property set
41.7. Notifications
41.8. Setting of certain property to all tasks
41.9. Logging of start and end of each task execution
42.1. Multi-project tree - water & bluewhale projects
42.2. Build script of water (parent) project
42.3. Multi-project tree - water, bluewhale & krill projects
42.4. Water project build script
42.5. Defining common behaviour of all projects and subprojects
42.6. Defining specific behaviour for particular project
42.7. Defining specific behaviour for project krill
42.8. Adding custom behaviour to some projects (filtered by project name)
42.9. Adding custom behaviour to some projects (filtered by project properties)
42.10. Running build from subproject
42.11. Evaluation and execution of projects
42.12. Evaluation and execution of projects
42.13. Running tasks by their absolute path
42.14. Dependencies and execution order
42.15. Dependencies and execution order
42.16. Dependencies and execution order
42.17. Declaring dependencies
42.18. Declaring dependencies
42.19. Project execution dependencies
42.20. Cross project task dependencies
42.21. Configuration time dependencies
42.22. Configuration time dependencies - evaluationDependsOn
42.23. Configuration time dependencies
42.24. Dependencies - real life example - crossproject configuration
42.25. Project lib dependencies
42.26. Project lib dependencies
42.27. Fine grained control over dependencies
42.28. Build and Test Single Project
42.29. Partial Build and Test Single Project
42.30. Build and Test Depended On Projects
42.31. Build and Test Dependent Projects
43.1. Defining a custom task
43.2. A hello world task
43.3. A customizable hello world task
43.4. A build for a custom task
43.5. A custom task
43.6. Using a custom task in another project
43.7. Testing a custom task
44.1. A custom plugin
44.2. A custom plugin extension
44.3. A custom plugin with configuration closure
44.4. A task with a configuration property
44.5. Wiring in the task property default value with conventions
44.6. Overriding conventional defaults
44.7. Conventional defaults in action
44.8. Evaluating file properties lazily
44.9. A build for a custom plugin
44.10. Wiring for a custom plugin
44.11. Using a custom plugin in another project
44.12. Testing a custom plugin
44.13. Managing domain objects
45.1. Using inherited properties and methods
45.2. Using injected properties and methods
45.3. Custom buildSrc build script
45.4. Adding subprojects to the root buildSrc project
45.5. Running another build from a build
45.6. Declaring external dependencies for the build script
45.7. A build script with external dependencies
45.8. Ant optional dependencies
46.1. Using init script to perform extra configuration before projects are evaluated
46.2. Declaring external dependencies for an init script
46.3. An init script with external dependencies
47.1. Wrapper task
47.2. Wrapper generated files
47.3. Configuration of wrapper task
B.1. Variables scope: local and script wide
B.2. Distinct configuration and execution phase