Gradle

A better way to build

Version 1.0-milestone-5

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 Application Plugin
34.1. Usage
34.2. Tasks
34.3. Convention properties
34.4. Including other resources in the distribution
35. Dependency Management
35.1. Introduction
35.2. Dependency management overview
35.3. How to declare your dependencies
35.4. Working with dependencies
35.5. Repositories
35.6. Strategies for transitive dependency management
36. Artifact Management
36.1. Introduction
36.2. Artifacts and configurations
36.3. Uploading artifacts
36.4. More about project libraries
37. The Maven Plugin
37.1. Usage
37.2. Tasks
37.3. Dependency management
37.4. Convention properties
37.5. Convention methods
37.6. Interacting with Maven repositories
38. The Signing Plugin
38.1. Usage
38.2. Signatory credentials
38.3. Specifying what to sign
38.4. Publishing the signatures
38.5. Signing POM files
39. The Build Lifecycle
39.1. Build phases
39.2. Settings file
39.3. Multi-project builds
39.4. Initialization
39.5. Configuration and execution of a single project build
39.6. Responding to the lifecycle in the build script
40. Multi-project Builds
40.1. Cross project configuration
40.2. Subproject configuration
40.3. Execution rules for multi-project builds
40.4. Running tasks by their absolute path
40.5. Project and task paths
40.6. Dependencies - Which dependencies?
40.7. Project lib dependencies
40.8. Multi-Project Building and Testing
40.9. Property and method inheritance
40.10. Summary
41. Writing Custom Task Classes
41.1. Packaging a task class
41.2. Writing a simple task class
41.3. A standalone project
42. Writing Custom Plugins
42.1. Packaging a plugin
42.2. Writing a simple plugin
42.3. Getting input from the build
42.4. Working with files in custom tasks and plugins
42.5. A standalone project
42.6. Maintaining multiple domain objects
43. Organizing Build Logic
43.1. Inherited properties and methods
43.2. Injected configuration
43.3. Build sources in the buildSrc project
43.4. Running another Gradle build from a build
43.5. External dependencies for the build script
43.6. Ant optional dependencies
43.7. Summary
44. Initialization Scripts
44.1. Basic usage
44.2. Writing an init script
44.3. External dependencies for the init script
45. The Gradle Wrapper
45.1. Configuration
45.2. Unix file permissions
45.3. Environment variable
46. 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
47. C++ Support
47.1. Usage
47.2. Source code locations
47.3. Compiling
47.4. Dependencies
47.5. Publishing
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
23.3. Generation of JAR archive in addition to WAR archive
24.1. Using the Ear plugin
24.2. Customization of ear plugin
24.3. Generation of JAR archive in addition to EAR archive
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 application plugin
34.2. Configure the application main class
34.3. Include output from other tasks in the application distribution
34.4. Automatically creating files for distribution
35.1. Definition of a configuration
35.2. Accessing a configuration
35.3. Configuration of a configuration
35.4. Module dependencies
35.5. Artifact only notation
35.6. Dependency with classifier
35.7. Usage of external dependency of a configuration
35.8. Client module dependencies - transitive dependencies
35.9. Project dependencies
35.10. File dependencies
35.11. Generated file dependencies
35.12. Gradle API dependencies
35.13. Gradle's Groovy dependencies
35.14. Excluding transitive dependencies
35.15. Optional attributes of dependencies
35.16. Collections and arrays of dependencies
35.17. Dependency configurations
35.18. Dependency configurations for project
35.19. Configuration.copy
35.20. Accessing declared dependencies
35.21. Configuration.files
35.22. Configuration.files with spec
35.23. Configuration.copy
35.24. Configuration.copy vs. Configuration.files
35.25. Adding central Maven repository
35.26. Adding several Maven repositories
35.27. Adding custom Maven repository
35.28. Adding additional Maven repositories for JAR files
35.29. Adding the local Maven cache as a repository
35.30. Accessing password protected Maven repository
35.31. Flat repository resolver
35.32. Ivy repository
35.33. Ivy repository with pattern layout
35.34. Ivy repository with custom patterns
35.35. Ivy repository
35.36. Accessing a repository
35.37. Configuration of a repository
35.38. Definition of a custom repository
36.1. Assignment of an artifact to a configuration
36.2. Configuration of the upload task
37.1. Using the Maven plugin
37.2. Creating a stand alone pom.
37.3. Upload of file to remote Maven repository
37.4. Upload of file via SSH
37.5. Customization of pom
37.6. Builder style customization of pom
37.7. Modifying auto-generated content
37.8. Customization of Maven installer
37.9. Generation of multiple poms
37.10. Accessing a mapping configuration
38.1. Using the Signing plugin
38.2. Signing a configuration
38.3. Signing a configuration output
38.4. Signing a task
38.5. Signing a task output
38.6. Conditional signing
38.7. Signing a POM for deployment
39.1. Single project build
39.2. Hierarchical layout
39.3. Flat layout
39.4. Modification of elements of the project tree
39.5. Modification of elements of the project tree
39.6. Adding of test task to each project which has certain property set
39.7. Notifications
39.8. Setting of certain property to all tasks
39.9. Logging of start and end of each task execution
40.1. Multi-project tree - water & bluewhale projects
40.2. Build script of water (parent) project
40.3. Multi-project tree - water, bluewhale & krill projects
40.4. Water project build script
40.5. Defining common behaviour of all projects and subprojects
40.6. Defining specific behaviour for particular project
40.7. Defining specific behaviour for project krill
40.8. Adding custom behaviour to some projects (filtered by project name)
40.9. Adding custom behaviour to some projects (filtered by project properties)
40.10. Running build from subproject
40.11. Evaluation and execution of projects
40.12. Evaluation and execution of projects
40.13. Running tasks by their absolute path
40.14. Dependencies and execution order
40.15. Dependencies and execution order
40.16. Dependencies and execution order
40.17. Declaring dependencies
40.18. Declaring dependencies
40.19. Project execution dependencies
40.20. Cross project task dependencies
40.21. Configuration time dependencies
40.22. Configuration time dependencies - evaluationDependsOn
40.23. Configuration time dependencies
40.24. Dependencies - real life example - crossproject configuration
40.25. Project lib dependencies
40.26. Project lib dependencies
40.27. Fine grained control over dependencies
40.28. Build and Test Single Project
40.29. Partial Build and Test Single Project
40.30. Build and Test Depended On Projects
40.31. Build and Test Dependent Projects
41.1. Defining a custom task
41.2. A hello world task
41.3. A customizable hello world task
41.4. A build for a custom task
41.5. A custom task
41.6. Using a custom task in another project
41.7. Testing a custom task
42.1. A custom plugin
42.2. A custom plugin extension
42.3. A custom plugin with configuration closure
42.4. A task with a configuration property
42.5. Wiring in the task property default value with conventions
42.6. Overriding conventional defaults
42.7. Conventional defaults in action
42.8. Evaluating file properties lazily
42.9. A build for a custom plugin
42.10. Wiring for a custom plugin
42.11. Using a custom plugin in another project
42.12. Testing a custom plugin
42.13. Managing domain objects
43.1. Using inherited properties and methods
43.2. Using injected properties and methods
43.3. Custom buildSrc build script
43.4. Running another build from a build
43.5. Declaring external dependencies for the build script
43.6. A build script with external dependencies
43.7. Ant optional dependencies
44.1. Using init script to perform extra configuration after project is evaluated
44.2. Declaring external dependencies for an init script
44.3. An init script with external dependencies
45.1. Wrapper task
45.2. Wrapper generated files
45.3. Configuration of wrapper task
B.1. Variables scope: local and script wide
B.2. Distinct configuration and execution phase
47.1. Using the 'cpp-exe' plugin
47.2. Using the 'cpp-lib' plugin
47.3. Supplying arbitrary args to gpp
47.4. Declaring dependencies
47.5. Declaring project dependencies
47.6. Uploading exe or lib