Gradle User Guide

A better way to build

Version 1.0-milestone-8a

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. Troubleshooting
5.1. Working through problems
5.2. Getting help
6. Build Script Basics
6.1. Projects and tasks
6.2. Hello world
6.3. A shortcut task definition
6.4. Build scripts are code
6.5. Task dependencies
6.6. Dynamic tasks
6.7. Manipulating existing tasks
6.8. Shortcut notations
6.9. Dynamic task properties
6.10. Using Ant Tasks
6.11. Using methods
6.12. Default tasks
6.13. Configure by DAG
6.14. Where to next?
7. Java Quickstart
7.1. The Java plugin
7.2. A basic Java project
7.3. Multi-project Java build
7.4. Where to next?
8. Dependency Management Basics
8.1. What is dependency management?
8.2. Declaring your dependencies
8.3. Dependency configurations
8.4. External dependencies
8.5. Repositories
8.6. Publishing artifacts
8.7. Where to next?
9. Groovy Quickstart
9.1. A basic Groovy project
9.2. Summary
10. Web Application Quickstart
10.1. Building a WAR file
10.2. Running your web application
10.3. Summary
11. Using the Gradle Command-Line
11.1. Executing multiple tasks
11.2. Excluding tasks
11.3. Task name abbreviation
11.4. Selecting which build to execute
11.5. Obtaining information about your build
11.6. Dry Run
11.7. Summary
12. Using the Gradle Graphical User Interface
12.1. Task Tree
12.2. Favorites
12.3. Command Line
12.4. Setup
13. The Gradle Daemon
13.1. Enter the daemon
13.2. Implementation notes
13.3. Usage and troubleshooting
13.4. Daemon properties
14. Tutorial - 'This and That'
14.1. Directory creation
14.2. Gradle properties and system properties
14.3. Configuring gradle via gradle.properties
14.4. Accessing the web via a proxy
14.5. Configuring the project using an external build script
14.6. Configuring arbitrary objects
14.7. Configuring arbitrary objects using an external script
14.8. Caching
15. Writing Build Scripts
15.1. The Gradle build language
15.2. The Project API
15.3. The Script API
15.4. Some Groovy basics
16. More about Tasks
16.1. Defining tasks
16.2. Locating tasks
16.3. Configuring tasks
16.4. Adding dependencies to a task
16.5. Adding a description to a task
16.6. Replacing tasks
16.7. Skipping tasks
16.8. Skipping tasks that are up-to-date
16.9. Task rules
16.10. Summary
17. Working With Files
17.1. Locating files
17.2. File collections
17.3. File trees
17.4. Using the contents of an archive as a file tree
17.5. Specifying a set of input files
17.6. Copying files
17.7. Using the Sync task
17.8. Creating archives
18. Logging
18.1. Choosing a log level
18.2. Writing your own log messages
18.3. Logging from external tools and libraries
18.4. Changing what Gradle logs
19. Using Ant from Gradle
19.1. Using Ant tasks and types in your build
19.2. Importing an Ant build
19.3. Ant properties and references
19.4. API
20. Using Plugins
20.1. Declaring plugins
20.2. Using the convention object
21. Standard Gradle plugins
21.1. Language plugins
21.2. Experimental language plugins
21.3. Integration plugins
21.4. Software development plugins
21.5. Base plugins
21.6. Third party plugins
22. The Java Plugin
22.1. Usage
22.2. Source sets
22.3. Tasks
22.4. Project layout
22.5. Dependency management
22.6. Convention properties
22.7. Working with source sets
22.8. Javadoc
22.9. Clean
22.10. Resources
22.11. CompileJava
22.12. Test
22.13. Jar
22.14. Uploading
23. The Groovy Plugin
23.1. Usage
23.2. Tasks
23.3. Project layout
23.4. Dependency management
23.5. Convention properties
23.6. Source set properties
23.7. CompileGroovy
24. The Scala Plugin
24.1. Usage
24.2. Tasks
24.3. Project layout
24.4. Dependency Management
24.5. Convention Properties
24.6. Source set properties
24.7. Fast Scala Compiler
25. The War Plugin
25.1. Usage
25.2. Tasks
25.3. Project layout
25.4. Dependency management
25.5. Convention properties
25.6. War
25.7. Customizing
26. The Ear Plugin
26.1. Usage
26.2. Tasks
26.3. Project layout
26.4. Dependency management
26.5. Convention properties
26.6. Ear
26.7. Customizing
26.8. Using custom descriptor file
27. The Jetty Plugin
27.1. Usage
27.2. Tasks
27.3. Project layout
27.4. Dependency management
27.5. Convention properties
28. The Checkstyle Plugin
28.1. Usage
28.2. Tasks
28.3. Project layout
28.4. Dependency management
28.5. Configuration
29. The CodeNarc Plugin
29.1. Usage
29.2. Tasks
29.3. Project layout
29.4. Dependency management
29.5. Configuration
30. The FindBugs Plugin
30.1. Usage
30.2. Tasks
30.3. Dependency management
30.4. Configuration
31. The JDepend Plugin
31.1. Usage
31.2. Tasks
31.3. Dependency management
31.4. Configuration
32. The PMD Plugin
32.1. Usage
32.2. Tasks
32.3. Dependency management
32.4. Configuration
33. The Sonar Plugin
33.1. Usage
33.2. Analyzing Multi-Project Builds
33.3. Analyzing Custom Source Sets
33.4. Setting Custom Sonar Properties
33.5. Tasks
34. The OSGi Plugin
34.1. Usage
34.2. Implicitly applied plugins
34.3. Tasks
34.4. Dependency management
34.5. Convention object
34.6.
35. The Eclipse Plugin
35.1. Usage
35.2. Tasks
35.3. Configuration
35.4. Customizing the generated files
36. The IDEA Plugin
36.1. Usage
36.2. Tasks
36.3. Configuration
36.4. Customizing the generated files
36.5. Further things to consider
37. The Antlr Plugin
37.1. Usage
37.2. Tasks
37.3. Project layout
37.4. Dependency management
37.5. Convention properties
37.6. Source set properties
38. The Project Report Plugin
38.1. Usage
38.2. Tasks
38.3. Project layout
38.4. Dependency management
38.5. Convention properties
39. The Announce Plugin
39.1. Usage
39.2. Tasks
39.3. Project layout
39.4. Dependency management
39.5. Convention properties
40. The Build Announcements Plugin
40.1. Usage
41. The Application Plugin
41.1. Usage
41.2. Tasks
41.3. Convention properties
41.4. Including other resources in the distribution
42. Dependency Management
42.1. Introduction
42.2. Dependency management overview
42.3. Dependency configurations
42.4. How to declare your dependencies
42.5. Working with dependencies
42.6. Repositories
42.7. The dependency cache
42.8. Strategies for transitive dependency management
43. Publishing artifacts
43.1. Introduction
43.2. Artifacts and configurations
43.3. Declaring artifacts
43.4. Publishing artifacts
43.5. More about project libraries
44. The Maven Plugin
44.1. Usage
44.2. Tasks
44.3. Dependency management
44.4. Convention properties
44.5. Convention methods
44.6. Interacting with Maven repositories
45. The Signing Plugin
45.1. Usage
45.2. Signatory credentials
45.3. Specifying what to sign
45.4. Publishing the signatures
45.5. Signing POM files
46. C++ Support
46.1. Usage
46.2. Source code locations
46.3. Compiling
46.4. Dependencies
46.5. Publishing
47. The Build Lifecycle
47.1. Build phases
47.2. Settings file
47.3. Multi-project builds
47.4. Initialization
47.5. Configuration and execution of a single project build
47.6. Responding to the lifecycle in the build script
48. Multi-project Builds
48.1. Cross project configuration
48.2. Subproject configuration
48.3. Execution rules for multi-project builds
48.4. Running tasks by their absolute path
48.5. Project and task paths
48.6. Dependencies - Which dependencies?
48.7. Project lib dependencies
48.8. Multi-Project Building and Testing
48.9. Property and method inheritance
48.10. Summary
49. Writing Custom Task Classes
49.1. Packaging a task class
49.2. Writing a simple task class
49.3. A standalone project
50. Writing Custom Plugins
50.1. Packaging a plugin
50.2. Writing a simple plugin
50.3. Getting input from the build
50.4. Working with files in custom tasks and plugins
50.5. A standalone project
50.6. Maintaining multiple domain objects
51. Organizing Build Logic
51.1. Inherited properties and methods
51.2. Injected configuration
51.3. Build sources in the buildSrc project
51.4. Running another Gradle build from a build
51.5. External dependencies for the build script
51.6. Ant optional dependencies
51.7. Summary
52. Initialization Scripts
52.1. Basic usage
52.2. Using an init script
52.3. Writing an init script
52.4. External dependencies for the init script
53. The Gradle Wrapper
53.1. Configuration
53.2. Unix file permissions
53.3. Environment variable
54. Embedding Gradle
54.1. Introduction to the Tooling API
54.2. Quickstart
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. Daemon 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

6.1. The first build script
6.2. Execution of a build script
6.3. A task definition shortcut
6.4. Using Groovy in Gradle's tasks
6.5. Using Groovy in Gradle's tasks
6.6. Declaration of dependencies between tasks
6.7. Lazy dependsOn - the other task does not exist (yet)
6.8. Dynamic creation of a task
6.9. Accessing a task via API - adding a dependency
6.10. Accessing a task via API - adding behaviour
6.11. Accessing task as a property of the build script
6.12. Assigning properties to a task
6.13. Using AntBuilder to execute ant.loadfile target
6.14. Using methods to organize your build logic
6.15. Defining a default tasks
6.16. Different outcomes of build depending on chosen tasks
7.1. Using the Java plugin
7.2. Building a Java project
7.3. Adding Maven repository
7.4. Adding dependencies
7.5. Customization of MANIFEST.MF
7.6. Adding a test system property
7.7. Publishing the JAR file
7.8. Eclipse plugin
7.9. Java example - complete build file
7.10. Multi-project build - hierarchical layout
7.11. Multi-project build - settings.gradle file
7.12. Multi-project build - common configuration
7.13. Multi-project build - dependencies between projects
7.14. Multi-project build - distribution file
8.1. Declaring dependencies
8.2. Definition of an external dependency
8.3. Shortcut definition of an external dependency
8.4. Usage of Maven central repository
8.5. Usage of a remote Maven repository
8.6. Usage of a remote Ivy directory
8.7. Usage of a local Ivy directory
8.8. Publishing to an Ivy repository
8.9. Publishing to a Maven repository
9.1. Groovy plugin
9.2. Dependency on Groovy 1.6.0
9.3. Groovy example - complete build file
10.1. War plugin
10.2. Running web application with Jetty plugin
11.1. Executing multiple tasks
11.2. Excluding tasks
11.3. Abbreviated task name
11.4. Abbreviated camel case task name
11.5. Selecting the project using a build file
11.6. Selecting the project using project directory
11.7. Obtaining information about projects
11.8. Providing a description for a project
11.9. Obtaining information about tasks
11.10. Changing the content of the task report
11.11. Obtaining more information about tasks
11.12. Obtaining information about dependencies
11.13. Information about properties
12.1. Launching the GUI
14.1. Directory creation with mkdir
14.2. Directory creation with Directory tasks
14.3. Setting properties with a gradle.properties file
14.4. Accessing the web via a proxy
14.5. Configuring the project using an external build script
14.6. Configuring arbitrary objects
14.7. Configuring arbitrary objects using a script
15.1. Accessing property of the Project object
15.2. Groovy JDK methods
15.3. Property accessors
15.4. Method call without parentheses
15.5. List and map literals
15.6. Closure as method parameter
15.7. Closure delegates
16.1. Defining tasks
16.2. Defining tasks - using strings
16.3. Defining tasks with alternative syntax
16.4. Accessing tasks as properties
16.5. Accessing tasks via tasks collection
16.6. Accessing tasks by path
16.7. Creating a copy task
16.8. Configuring a task - various ways
16.9. Configuring a task - fluent interface
16.10. Configuring a task - with closure
16.11. Configuring a task - with configure() method
16.12. Defining a task with closure
16.13. Adding dependency on task from another project
16.14. Adding dependency using task object
16.15. Adding dependency using closure
16.16. Adding a description to a task
16.17. Overwriting a task
16.18. Skipping a task using a predicate
16.19. Skipping tasks with StopExecutionException
16.20. Enabling and disabling tasks
16.21. A generator task
16.22. Declaring the inputs and outputs of a task
16.23. Task rule
16.24. Dependency on rule based tasks
17.1. Locating files
17.2. Creating a file collection
17.3. Using a file collection
17.4. Implementing a file collection
17.5. Creating a file tree
17.6. Using a file tree
17.7. Using an archive as a file tree
17.8. Specifying a set of files
17.9. Specifying a set of files
17.10. Copying files using the copy task
17.11. Specifying copy task source files and destination directory
17.12. Selecting the files to copy
17.13. Copying files using the copy() method
17.14. Renaming files as they are copied
17.15. Filtering files as they are copied
17.16. Nested copy specs
17.17. Using the Sync task to copy dependencies
17.18. Creating a ZIP archive
17.19. Creation of ZIP archive
17.20. Configuration of archive task - custom archive name
17.21. Configuration of archive task - appendix & classifier
18.1. Using stdout to write log messages
18.2. Writing your own log messages
18.3. Using SLF4J to write log messages
18.4. Configuring standard output capture
18.5. Configuring standard output capture for a task
18.6. Customizing what Gradle logs
19.1. Using an Ant task
19.2. Passing nested text to an Ant task
19.3. Passing nested elements to an Ant task
19.4. Using an Ant type
19.5. Using a custom Ant task
19.6. Declaring the classpath for a custom Ant task
19.7. Using a custom Ant task and dependency management together
19.8. Importing an Ant build
19.9. Task that depends on Ant target
19.10. Adding behaviour to an Ant target
19.11. Ant target that depends on Gradle task
19.12. Setting an Ant property
19.13. Getting an Ant property
19.14. Setting an Ant reference
19.15. Getting an Ant reference
20.1. Using a plugin
20.2. Applying a plugin by id
20.3. Applying a plugin by type
20.4. Applying a plugin by type
20.5. Configuring a plugin task
20.6. Plugin convention object
20.7. Using the plugin convention object
20.8. Explicit application of an implied plugin
22.1. Using the Java plugin
22.2. Custom Java source layout
22.3. Accessing a source set
22.4. Configuring the source directories of a source set
22.5. Defining a source set
22.6. Defining source set dependencies
22.7. Compiling a source set
22.8. Assembling a JAR for a source set
22.9. Generating the Javadoc for a source set
22.10. Running tests in a source set
22.11. Customization of MANIFEST.MF
22.12. Creating a manifest object.
22.13. Separate MANIFEST.MF for a particular archive
22.14. Separate MANIFEST.MF for a particular archive
23.1. Using the Groovy plugin
23.2. Custom Groovy source layout
23.3. Configuration of Groovy plugin
23.4. Configuration of Groovy plugin
24.1. Using the Scala plugin
24.2. Custom Scala source layout
24.3. Declaring the Scala version to use
24.4. Enabling the Fast Scala Compiler
25.1. Using the War plugin
25.2. Customization of war plugin
26.1. Using the Ear plugin
26.2. Customization of ear plugin
27.1. Using the Jetty plugin
28.1. Using the Checkstyle plugin
29.1. Using the CodeNarc plugin
30.1. Using the FindBugs plugin
31.1. Using the JDepend plugin
32.1. Using the PMD plugin
33.1. Applying the Sonar plugin
33.2. Configuring Sonar connection settings
33.3. Configuring Sonar project settings
33.4. Global configuration in a multi-project build
33.5. Common project configuration in a multi-project build
33.6. Individual project configuration in a multi-project build
33.7. Configuring the language to be analyzed
33.8. Using property syntax
33.9. Analyzing custom source sets
33.10. Setting custom global properties
33.11. Setting custom project properties
34.1. Using the OSGi plugin
34.2. Configuration of OSGi MANIFEST.MF file
35.1. Using the Eclipse plugin
35.2. Partial Overwrite for Classpath
35.3. Partial Overwrite for Project
35.4. Export Dependencies
35.5. Customizing the XML
36.1. Using the IDEA plugin
36.2. Partial Overwrite for Module
36.3. Partial Overwrite for Project
36.4. Export Dependencies
36.5. Customizing the XML
37.1. Using the Antlr plugin
37.2. Declare Antlr version
39.1. Using the announce plugin
39.2. Configure the announce plugin
39.3. Using the announce plugin
40.1. Using the build announcements plugin
40.2. Using the build announcements plugin from an init script
41.1. Using the application plugin
41.2. Configure the application main class
41.3. Include output from other tasks in the application distribution
41.4. Automatically creating files for distribution
42.1. Definition of a configuration
42.2. Accessing a configuration
42.3. Configuration of a configuration
42.4. Module dependencies
42.5. Artifact only notation
42.6. Dependency with classifier
42.7. Usage of external dependency of a configuration
42.8. Client module dependencies - transitive dependencies
42.9. Project dependencies
42.10. File dependencies
42.11. Generated file dependencies
42.12. Gradle API dependencies
42.13. Gradle's Groovy dependencies
42.14. Excluding transitive dependencies
42.15. Optional attributes of dependencies
42.16. Collections and arrays of dependencies
42.17. Dependency configurations
42.18. Dependency configurations for project
42.19. Configuration.copy
42.20. Accessing declared dependencies
42.21. Configuration.files
42.22. Configuration.files with spec
42.23. Configuration.copy
42.24. Configuration.copy vs. Configuration.files
42.25. Adding central Maven repository
42.26. Adding the local Maven cache as a repository
42.27. Adding custom Maven repository
42.28. Adding additional Maven repositories for JAR files
42.29. Accessing password protected Maven repository
42.30. Flat repository resolver
42.31. Ivy repository
42.32. Ivy repository with pattern layout
42.33. Ivy repository with custom patterns
42.34. Ivy repository
42.35. Accessing a repository
42.36. Configuration of a repository
42.37. Definition of a custom repository
42.38. Dynamic version cache control
42.39. Changing module cache control
43.1. Defining an artifact using an archive task
43.2. Defining an artifact using a file
43.3. Customizing an artifact
43.4. Map syntax for defining an artifact using a file
43.5. Configuration of the upload task
44.1. Using the Maven plugin
44.2. Creating a stand alone pom.
44.3. Upload of file to remote Maven repository
44.4. Upload of file via SSH
44.5. Customization of pom
44.6. Builder style customization of pom
44.7. Modifying auto-generated content
44.8. Customization of Maven installer
44.9. Generation of multiple poms
44.10. Accessing a mapping configuration
45.1. Using the Signing plugin
45.2. Signing a configuration
45.3. Signing a configuration output
45.4. Signing a task
45.5. Signing a task output
45.6. Conditional signing
45.7. Signing a POM for deployment
46.1. Using the 'cpp-exe' plugin
46.2. Using the 'cpp-lib' plugin
46.3. Supplying arbitrary args to gpp
46.4. Declaring dependencies
46.5. Declaring project dependencies
46.6. Uploading exe or lib
47.1. Single project build
47.2. Hierarchical layout
47.3. Flat layout
47.4. Modification of elements of the project tree
47.5. Modification of elements of the project tree
47.6. Adding of test task to each project which has certain property set
47.7. Notifications
47.8. Setting of certain property to all tasks
47.9. Logging of start and end of each task execution
48.1. Multi-project tree - water & bluewhale projects
48.2. Build script of water (parent) project
48.3. Multi-project tree - water, bluewhale & krill projects
48.4. Water project build script
48.5. Defining common behaviour of all projects and subprojects
48.6. Defining specific behaviour for particular project
48.7. Defining specific behaviour for project krill
48.8. Adding custom behaviour to some projects (filtered by project name)
48.9. Adding custom behaviour to some projects (filtered by project properties)
48.10. Running build from subproject
48.11. Evaluation and execution of projects
48.12. Evaluation and execution of projects
48.13. Running tasks by their absolute path
48.14. Dependencies and execution order
48.15. Dependencies and execution order
48.16. Dependencies and execution order
48.17. Declaring dependencies
48.18. Declaring dependencies
48.19. Project execution dependencies
48.20. Cross project task dependencies
48.21. Configuration time dependencies
48.22. Configuration time dependencies - evaluationDependsOn
48.23. Configuration time dependencies
48.24. Dependencies - real life example - crossproject configuration
48.25. Project lib dependencies
48.26. Project lib dependencies
48.27. Fine grained control over dependencies
48.28. Build and Test Single Project
48.29. Partial Build and Test Single Project
48.30. Build and Test Depended On Projects
48.31. Build and Test Dependent Projects
49.1. Defining a custom task
49.2. A hello world task
49.3. A customizable hello world task
49.4. A build for a custom task
49.5. A custom task
49.6. Using a custom task in another project
49.7. Testing a custom task
50.1. A custom plugin
50.2. A custom plugin extension
50.3. A custom plugin with configuration closure
50.4. A task with a configuration property
50.5. Wiring in the task property default value with conventions
50.6. Overriding conventional defaults
50.7. Conventional defaults in action
50.8. Evaluating file properties lazily
50.9. A build for a custom plugin
50.10. Wiring for a custom plugin
50.11. Using a custom plugin in another project
50.12. Testing a custom plugin
50.13. Managing domain objects
51.1. Using inherited properties and methods
51.2. Using injected properties and methods
51.3. Custom buildSrc build script
51.4. Adding subprojects to the root buildSrc project
51.5. Running another build from a build
51.6. Declaring external dependencies for the build script
51.7. A build script with external dependencies
51.8. Ant optional dependencies
52.1. Using init script to perform extra configuration before projects are evaluated
52.2. Declaring external dependencies for an init script
52.3. An init script with external dependencies
53.1. Wrapper task
53.2. Wrapper generated files
53.3. Configuration of wrapper task
B.1. Variables scope: local and script wide
B.2. Distinct configuration and execution phase