Gradle User Guide

Version 1.3

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. Extra 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. Continuing the build when a failure occurs
11.4. Task name abbreviation
11.5. Selecting which build to execute
11.6. Obtaining information about your build
11.7. Dry Run
11.8. Summary
12. Using the Gradle Graphical User Interface
12.1. Task Tree
12.2. Favorites
12.3. Command Line
12.4. Setup
13. Writing Build Scripts
13.1. The Gradle build language
13.2. The Project API
13.3. The Script API
13.4. Declaring variables
13.5. Some Groovy basics
14. Tutorial - 'This and That'
14.1. Directory creation
14.2. Gradle properties and system properties
14.3. Configuring the project using an external build script
14.4. Configuring arbitrary objects
14.5. Configuring arbitrary objects using an external script
14.6. Caching
15. More about Tasks
15.1. Defining tasks
15.2. Locating tasks
15.3. Configuring tasks
15.4. Adding dependencies to a task
15.5. Adding a description to a task
15.6. Replacing tasks
15.7. Skipping tasks
15.8. Skipping tasks that are up-to-date
15.9. Task rules
15.10. Summary
16. Working With Files
16.1. Locating files
16.2. File collections
16.3. File trees
16.4. Using the contents of an archive as a file tree
16.5. Specifying a set of input files
16.6. Copying files
16.7. Using the Sync task
16.8. Creating archives
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. 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. The Gradle Daemon
19.1. Enter the daemon
19.2. Reusing and expiration of daemons
19.3. Usage and troubleshooting
19.4. Configuring the daemon
20. The Build Environment
20.1. Configuring the build environment via gradle.properties
20.2. Accessing the web via a proxy
21. Gradle Plugins
21.1. Applying plugins
21.2. What plugins do
21.3. Conventions
21.4. More on plugins
22. Standard Gradle plugins
22.1. Language plugins
22.2. Incubating language plugins
22.3. Integration plugins
22.4. Software development plugins
22.5. Base plugins
22.6. Third party plugins
23. The Java Plugin
23.1. Usage
23.2. Source sets
23.3. Tasks
23.4. Project layout
23.5. Dependency management
23.6. Convention properties
23.7. Working with source sets
23.8. Javadoc
23.9. Clean
23.10. Resources
23.11. CompileJava
23.12. Test
23.13. Jar
23.14. Uploading
24. The Groovy 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. CompileGroovy
25. The Scala Plugin
25.1. Usage
25.2. Tasks
25.3. Project layout
25.4. Dependency management
25.5. Convention properties
25.6. Source set properties
25.7. Fast Scala Compiler
25.8. Compiling in external process
25.9. Incremental compilation
26. The War Plugin
26.1. Usage
26.2. Tasks
26.3. Project layout
26.4. Dependency management
26.5. Convention properties
26.6. War
26.7. Customizing
27. The Ear Plugin
27.1. Usage
27.2. Tasks
27.3. Project layout
27.4. Dependency management
27.5. Convention properties
27.6. Ear
27.7. Customizing
27.8. Using custom descriptor file
28. The Jetty Plugin
28.1. Usage
28.2. Tasks
28.3. Project layout
28.4. Dependency management
28.5. Convention properties
29. The Checkstyle Plugin
29.1. Usage
29.2. Tasks
29.3. Project layout
29.4. Dependency management
29.5. Configuration
30. The CodeNarc Plugin
30.1. Usage
30.2. Tasks
30.3. Project layout
30.4. Dependency management
30.5. Configuration
31. The FindBugs Plugin
31.1. Usage
31.2. Tasks
31.3. Dependency management
31.4. Configuration
32. The JDepend Plugin
32.1. Usage
32.2. Tasks
32.3. Dependency management
32.4. Configuration
33. The PMD Plugin
33.1. Usage
33.2. Tasks
33.3. Dependency management
33.4. Configuration
34. The Sonar Plugin
34.1. Usage
34.2. Analyzing Multi-Project Builds
34.3. Analyzing Custom Source Sets
34.4. Setting Custom Sonar Properties
34.5. Tasks
35. The OSGi Plugin
35.1. Usage
35.2. Implicitly applied plugins
35.3. Tasks
35.4. Dependency management
35.5. Convention object
35.6.
36. The Eclipse Plugin
36.1. Usage
36.2. Tasks
36.3. Configuration
36.4. Customizing the generated files
37. The IDEA Plugin
37.1. Usage
37.2. Tasks
37.3. Configuration
37.4. Customizing the generated files
37.5. Further things to consider
38. The Antlr Plugin
38.1. Usage
38.2. Tasks
38.3. Project layout
38.4. Dependency management
38.5. Convention properties
38.6. Source set properties
39. The Project Report Plugin
39.1. Usage
39.2. Tasks
39.3. Project layout
39.4. Dependency management
39.5. Convention properties
40. The Announce Plugin
40.1. Usage
40.2. Configuration
41. The Build Announcements Plugin
41.1. Usage
42. The Application Plugin
42.1. Usage
42.2. Tasks
42.3. Convention properties
42.4. Including other resources in the distribution
43. Bootstrap Plugin
43.1. Maven conversion - features
43.2. Usage
44. Dependency Management
44.1. Introduction
44.2. Dependency Management Best Practices.
44.3. Dependency configurations
44.4. How to declare your dependencies
44.5. Working with dependencies
44.6. Repositories
44.7. How dependency resolution works
44.8. The dependency cache
44.9. Strategies for transitive dependency management
45. Publishing artifacts
45.1. Introduction
45.2. Artifacts and configurations
45.3. Declaring artifacts
45.4. Publishing artifacts
45.5. More about project libraries
46. The Maven Plugin
46.1. Usage
46.2. Tasks
46.3. Dependency management
46.4. Convention properties
46.5. Convention methods
46.6. Interacting with Maven repositories
47. The Signing Plugin
47.1. Usage
47.2. Signatory credentials
47.3. Specifying what to sign
47.4. Publishing the signatures
47.5. Signing POM files
48. C++ Support
48.1. Usage
48.2. Source code locations
48.3. Compiling
48.4. Configuring the compiler
48.5. Working with shared libraries
48.6. Dependencies
48.7. Publishing
49. The Build Lifecycle
49.1. Build phases
49.2. Settings file
49.3. Multi-project builds
49.4. Initialization
49.5. Configuration and execution of a single project build
49.6. Responding to the lifecycle in the build script
50. Multi-project Builds
50.1. Cross project configuration
50.2. Subproject configuration
50.3. Execution rules for multi-project builds
50.4. Running tasks by their absolute path
50.5. Project and task paths
50.6. Dependencies - Which dependencies?
50.7. Project lib dependencies
50.8. Decoupled Projects
50.9. Multi-Project Building and Testing
50.10. Property and method inheritance
50.11. Summary
51. Writing Custom Task Classes
51.1. Packaging a task class
51.2. Writing a simple task class
51.3. A standalone project
52. Writing Custom Plugins
52.1. Packaging a plugin
52.2. Writing a simple plugin
52.3. Getting input from the build
52.4. Working with files in custom tasks and plugins
52.5. A standalone project
52.6. Maintaining multiple domain objects
53. Organizing Build Logic
53.1. Inherited properties and methods
53.2. Injected configuration
53.3. Build sources in the buildSrc project
53.4. Running another Gradle build from a build
53.5. External dependencies for the build script
53.6. Ant optional dependencies
53.7. Summary
54. Initialization Scripts
54.1. Basic usage
54.2. Using an init script
54.3. Writing an init script
54.4. External dependencies for the init script
55. The Gradle Wrapper
55.1. Configuration
55.2. Unix file permissions
55.3. Environment variable
56. Embedding Gradle
56.1. Introduction to the Tooling API
56.2. Tooling API and the Gradle Build Daemon
56.3. Quickstart
57. Comparing Builds
57.1. Definition of terms
57.2. Current Capabilities
57.3. Comparing Gradle Builds
58. Ivy Publishing (new)
58.1.
58.2. The “ivy-publish” Plugin
58.3. Publications
58.4. Repositories
58.5. Performing a publish
58.6. Future features
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
59. The Feature Lifecycle
59.1. States
59.2. Backwards Compatibility Policy
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. Adding extra 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.7.10
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. Getting the insight into a particular dependency
11.14. Information about properties
12.1. Launching the GUI
13.1. Accessing property of the Project object
13.2. Using local variables
13.3. Using extra properties
13.4. Groovy JDK methods
13.5. Property accessors
13.6. Method call without parentheses
13.7. List and map literals
13.8. Closure as method parameter
13.9. Closure delegates
14.1. Directory creation with mkdir
14.2. Setting properties with a gradle.properties file
14.3. Configuring the project using an external build script
14.4. Configuring arbitrary objects
14.5. Configuring arbitrary objects using a script
15.1. Defining tasks
15.2. Defining tasks - using strings
15.3. Defining tasks with alternative syntax
15.4. Accessing tasks as properties
15.5. Accessing tasks via tasks collection
15.6. Accessing tasks by path
15.7. Creating a copy task
15.8. Configuring a task - various ways
15.9. Configuring a task - fluent interface
15.10. Configuring a task - with closure
15.11. Configuring a task - with configure() method
15.12. Defining a task with closure
15.13. Adding dependency on task from another project
15.14. Adding dependency using task object
15.15. Adding dependency using closure
15.16. Adding a description to a task
15.17. Overwriting a task
15.18. Skipping a task using a predicate
15.19. Skipping tasks with StopExecutionException
15.20. Enabling and disabling tasks
15.21. A generator task
15.22. Declaring the inputs and outputs of a task
15.23. Task rule
15.24. Dependency on rule based tasks
16.1. Locating files
16.2. Creating a file collection
16.3. Using a file collection
16.4. Implementing a file collection
16.5. Creating a file tree
16.6. Using a file tree
16.7. Using an archive as a file tree
16.8. Specifying a set of files
16.9. Specifying a set of files
16.10. Copying files using the copy task
16.11. Specifying copy task source files and destination directory
16.12. Selecting the files to copy
16.13. Copying files using the copy() method
16.14. Renaming files as they are copied
16.15. Filtering files as they are copied
16.16. Nested copy specs
16.17. Using the Sync task to copy dependencies
16.18. Creating a ZIP archive
16.19. Creation of ZIP archive
16.20. Configuration of archive task - custom archive name
16.21. Configuration of archive task - appendix & classifier
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 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
20.1. Configuring an HTTP proxy
20.2. Configuring an HTTPS proxy
21.1. Applying a plugin
21.2. Applying a plugin by type
21.3. Applying a plugin by type
21.4. Tasks added by a plugin
21.5. Changing plugin defaults
21.6. Plugin convention object
23.1. Using the Java plugin
23.2. Custom Java source layout
23.3. Accessing a source set
23.4. Configuring the source directories of a source set
23.5. Defining a source set
23.6. Defining source set dependencies
23.7. Compiling a source set
23.8. Assembling a JAR for a source set
23.9. Generating the Javadoc for a source set
23.10. Running tests in a source set
23.11. Customization of MANIFEST.MF
23.12. Creating a manifest object.
23.13. Separate MANIFEST.MF for a particular archive
23.14. Separate MANIFEST.MF for a particular archive
24.1. Using the Groovy plugin
24.2. Custom Groovy source layout
24.3. Configuration of Groovy plugin
24.4. Configuration of Groovy plugin
25.1. Using the Scala plugin
25.2. Custom Scala source layout
25.3. Declaring the Scala version to use
25.4. Enabling the Fast Scala Compiler
25.5. Adjusting memory settings
25.6. Activating the Zinc based compiler
26.1. Using the War plugin
26.2. Customization of war plugin
27.1. Using the Ear plugin
27.2. Customization of ear plugin
28.1. Using the Jetty plugin
29.1. Using the Checkstyle plugin
30.1. Using the CodeNarc plugin
31.1. Using the FindBugs plugin
32.1. Using the JDepend plugin
33.1. Using the PMD plugin
34.1. Applying the Sonar plugin
34.2. Configuring Sonar connection settings
34.3. Configuring Sonar project settings
34.4. Global configuration in a multi-project build
34.5. Common project configuration in a multi-project build
34.6. Individual project configuration in a multi-project build
34.7. Configuring the language to be analyzed
34.8. Using property syntax
34.9. Analyzing custom source sets
34.10. Setting custom global properties
34.11. Setting custom project properties
35.1. Using the OSGi plugin
35.2. Configuration of OSGi MANIFEST.MF file
36.1. Using the Eclipse plugin
36.2. Partial Overwrite for Classpath
36.3. Partial Overwrite for Project
36.4. Export Dependencies
36.5. Customizing the XML
37.1. Using the IDEA plugin
37.2. Partial Overwrite for Module
37.3. Partial Overwrite for Project
37.4. Export Dependencies
37.5. Customizing the XML
38.1. Using the Antlr plugin
38.2. Declare Antlr version
40.1. Using the announce plugin
40.2. Configure the announce plugin
40.3. Using the announce plugin
41.1. Using the build announcements plugin
41.2. Using the build announcements plugin from an init script
42.1. Using the application plugin
42.2. Configure the application main class
42.3. Include output from other tasks in the application distribution
42.4. Automatically creating files for distribution
44.1. Definition of a configuration
44.2. Accessing a configuration
44.3. Configuration of a configuration
44.4. Module dependencies
44.5. Artifact only notation
44.6. Dependency with classifier
44.7. Usage of external dependency of a configuration
44.8. Client module dependencies - transitive dependencies
44.9. Project dependencies
44.10. File dependencies
44.11. Generated file dependencies
44.12. Gradle API dependencies
44.13. Gradle's Groovy dependencies
44.14. Excluding transitive dependencies
44.15. Optional attributes of dependencies
44.16. Collections and arrays of dependencies
44.17. Dependency configurations
44.18. Dependency configurations for project
44.19. Configuration.copy
44.20. Accessing declared dependencies
44.21. Configuration.files
44.22. Configuration.files with spec
44.23. Configuration.copy
44.24. Configuration.copy vs. Configuration.files
44.25. Adding central Maven repository
44.26. Adding the local Maven cache as a repository
44.27. Adding custom Maven repository
44.28. Adding additional Maven repositories for JAR files
44.29. Accessing password protected Maven repository
44.30. Flat repository resolver
44.31. Ivy repository
44.32. Ivy repository with pattern layout
44.33. Ivy repository with custom patterns
44.34. Ivy repository
44.35. Accessing a repository
44.36. Configuration of a repository
44.37. Definition of a custom repository
44.38. Dynamic version cache control
44.39. Changing module cache control
45.1. Defining an artifact using an archive task
45.2. Defining an artifact using a file
45.3. Customizing an artifact
45.4. Map syntax for defining an artifact using a file
45.5. Configuration of the upload task
46.1. Using the Maven plugin
46.2. Creating a stand alone pom.
46.3. Upload of file to remote Maven repository
46.4. Upload of file via SSH
46.5. Customization of pom
46.6. Builder style customization of pom
46.7. Modifying auto-generated content
46.8. Customization of Maven installer
46.9. Generation of multiple poms
46.10. Accessing a mapping configuration
47.1. Using the Signing plugin
47.2. Signing a configuration
47.3. Signing a configuration output
47.4. Signing a task
47.5. Signing a task output
47.6. Conditional signing
47.7. Signing a POM for deployment
48.1. Using the 'cpp-exe' plugin
48.2. Using the 'cpp-lib' plugin
48.3. Supplying arbitrary args to the compiler
48.4. Declaring dependencies
48.5. Declaring project dependencies
48.6. Uploading exe or lib
49.1. Single project build
49.2. Hierarchical layout
49.3. Flat layout
49.4. Modification of elements of the project tree
49.5. Modification of elements of the project tree
49.6. Adding of test task to each project which has certain property set
49.7. Notifications
49.8. Setting of certain property to all tasks
49.9. Logging of start and end of each task execution
50.1. Multi-project tree - water & bluewhale projects
50.2. Build script of water (parent) project
50.3. Multi-project tree - water, bluewhale & krill projects
50.4. Water project build script
50.5. Defining common behaviour of all projects and subprojects
50.6. Defining specific behaviour for particular project
50.7. Defining specific behaviour for project krill
50.8. Adding custom behaviour to some projects (filtered by project name)
50.9. Adding custom behaviour to some projects (filtered by project properties)
50.10. Running build from subproject
50.11. Evaluation and execution of projects
50.12. Evaluation and execution of projects
50.13. Running tasks by their absolute path
50.14. Dependencies and execution order
50.15. Dependencies and execution order
50.16. Dependencies and execution order
50.17. Declaring dependencies
50.18. Declaring dependencies
50.19. Cross project task dependencies
50.20. Configuration time dependencies
50.21. Configuration time dependencies - evaluationDependsOn
50.22. Configuration time dependencies
50.23. Dependencies - real life example - crossproject configuration
50.24. Project lib dependencies
50.25. Project lib dependencies
50.26. Fine grained control over dependencies
50.27. Build and Test Single Project
50.28. Partial Build and Test Single Project
50.29. Build and Test Depended On Projects
50.30. Build and Test Dependent Projects
51.1. Defining a custom task
51.2. A hello world task
51.3. A customizable hello world task
51.4. A build for a custom task
51.5. A custom task
51.6. Using a custom task in another project
51.7. Testing a custom task
52.1. A custom plugin
52.2. A custom plugin extension
52.3. A custom plugin with configuration closure
52.4. Evaluating file properties lazily
52.5. A build for a custom plugin
52.6. Wiring for a custom plugin
52.7. Using a custom plugin in another project
52.8. Testing a custom plugin
52.9. Managing domain objects
53.1. Using inherited properties and methods
53.2. Using injected properties and methods
53.3. Custom buildSrc build script
53.4. Adding subprojects to the root buildSrc project
53.5. Running another build from a build
53.6. Declaring external dependencies for the build script
53.7. A build script with external dependencies
53.8. Ant optional dependencies
54.1. Using init script to perform extra configuration before projects are evaluated
54.2. Declaring external dependencies for an init script
54.3. An init script with external dependencies
55.1. Wrapper task
55.2. Wrapper generated files
55.3. Configuration of wrapper task
58.1. Applying the “ivy-publish” plugin
58.2. A build to publish
58.3. Example generated ivy.xml
58.4. Modifying the Ivy descriptor
58.5. Declaring repositories to publish to
B.1. Variables scope: local and script wide
B.2. Distinct configuration and execution phase