Gradle User Guide

Version 3.0

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

I. About Gradle
1. Introduction
2. Overview
II. Working with existing builds
3. Installing Gradle
4. Using the Gradle Command-Line
5. The Gradle Wrapper
6. The Gradle Daemon
7. Dependency Management Basics
8. Introduction to multi-project builds
9. Continuous build
10. Using the Gradle Graphical User Interface
11. The Build Environment
12. Troubleshooting
13. Embedding Gradle using the Tooling API
III. Writing Gradle build scripts
14. Build Script Basics
15. Build Init Plugin
16. Writing Build Scripts
17. More about Tasks
18. Working With Files
19. Using Ant from Gradle
20. The Build Lifecycle
21. Wrapper Plugin
22. Logging
23. Dependency Management
24. Multi-project Builds
25. Gradle Plugins
26. Standard Gradle plugins
27. The Project Report Plugin
28. The Build Dashboard Plugin
29. Comparing Builds
30. Publishing artifacts
31. The Maven Plugin
32. The Signing Plugin
33. Ivy Publishing (new)
34. Maven Publishing (new)
35. The Distribution Plugin
36. The Announce Plugin
37. The Build Announcements Plugin
IV. Extending the build
38. Writing Custom Task Classes
39. Writing Custom Plugins
40. The Java Gradle Plugin Development Plugin
41. Organizing Build Logic
42. Initialization Scripts
43. The Gradle TestKit
V. Building JVM projects
44. Java Quickstart
45. The Java Plugin
46. Web Application Quickstart
47. The War Plugin
48. The Ear Plugin
49. The Jetty Plugin
50. The Application Plugin
51. The Java Library Distribution Plugin
52. Groovy Quickstart
53. The Groovy Plugin
54. The Scala Plugin
55. The ANTLR Plugin
56. The Checkstyle Plugin
57. The CodeNarc Plugin
58. The FindBugs Plugin
59. The JDepend Plugin
60. The PMD Plugin
61. The JaCoCo Plugin
62. The OSGi Plugin
63. The Eclipse Plugins
64. The IDEA Plugin
VI. The Software model - Next generation Gradle builds
65. Rule based model configuration
66. Software model concepts
67. Implementing model rules in a plugin
68. Building Java Libraries
69. Building Play applications
70. Building native software
71. Extending the software model
VII. Appendix
A. Gradle Samples
B. Potential Traps
C. The Feature Lifecycle
D. Gradle Command Line
E. Documentation licenses
Glossary

List of Examples

4.1. Executing multiple tasks
4.2. Excluding tasks
4.3. Abbreviated task name
4.4. Abbreviated camel case task name
4.5. Selecting the project using a build file
4.6. Selecting the project using project directory
4.7. Forcing tasks to run
4.8. Obtaining information about projects
4.9. Providing a description for a project
4.10. Obtaining information about tasks
4.11. Changing the content of the task report
4.12. Obtaining more information about tasks
4.13. Obtaining detailed help for tasks
4.14. Obtaining information about dependencies
4.15. Filtering dependency report by configuration
4.16. Getting the insight into a particular dependency
4.17. Information about properties
5.1. Running the Wrapper task
5.2. Wrapper task
5.3. Wrapper generated files
5.4. Generating a SHA-256 hash
5.5. Configuring SHA-256 checksum verification
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 JCenter repository
7.6. Usage of a remote Maven repository
7.7. Usage of a remote Ivy directory
7.8. Usage of a local Ivy directory
7.9. Publishing to an Ivy repository
7.10. Publishing to a Maven repository
8.1. Listing the projects in a build
10.1. Launching the GUI
11.1. Setting properties with a gradle.properties file
11.2. Configuring an HTTP proxy
11.3. Configuring an HTTPS proxy
14.1. Your first build script
14.2. Execution of a build script
14.3. A task definition shortcut
14.4. Using Groovy in Gradle's tasks
14.5. Using Groovy in Gradle's tasks
14.6. Declaration of task that depends on other task
14.7. Lazy dependsOn - the other task does not exist (yet)
14.8. Dynamic creation of a task
14.9. Accessing a task via API - adding a dependency
14.10. Accessing a task via API - adding behaviour
14.11. Accessing task as a property of the build script
14.12. Adding extra properties to a task
14.13. Using AntBuilder to execute ant.loadfile target
14.14. Using methods to organize your build logic
14.15. Defining a default task
14.16. Different outcomes of build depending on chosen tasks
16.1. Accessing property of the Project object
16.2. Using local variables
16.3. Using extra properties
16.4. Configuring arbitrary objects
16.5. Configuring arbitrary objects using a script
16.6. Groovy JDK methods
16.7. Property accessors
16.8. Method call without parentheses
16.9. List and map literals
16.10. Closure as method parameter
16.11. Closure delegates
17.1. Defining tasks
17.2. Defining tasks - using strings for task names
17.3. Defining tasks with alternative syntax
17.4. Accessing tasks as properties
17.5. Accessing tasks via tasks collection
17.6. Accessing tasks by path
17.7. Creating a copy task
17.8. Configuring a task - various ways
17.9. Configuring a task - with closure
17.10. Defining a task with closure
17.11. Adding dependency on task from another project
17.12. Adding dependency using task object
17.13. Adding dependency using closure
17.14. Adding a 'must run after' task ordering
17.15. Adding a 'should run after' task ordering
17.16. Task ordering does not imply task execution
17.17. A 'should run after' task ordering is ignored if it introduces an ordering cycle
17.18. Adding a description to a task
17.19. Overwriting a task
17.20. Skipping a task using a predicate
17.21. Skipping tasks with StopExecutionException
17.22. Enabling and disabling tasks
17.23. A generator task
17.24. Declaring the inputs and outputs of a task
17.25. Task rule
17.26. Dependency on rule based tasks
17.27. Adding a task finalizer
17.28. Task finalizer for a failing task
18.1. Locating files
18.2. Creating a file collection
18.3. Using a file collection
18.4. Implementing a file collection
18.5. Creating a file tree
18.6. Using a file tree
18.7. Using an archive as a file tree
18.8. Specifying a set of files
18.9. Copying files using the copy task
18.10. Specifying copy task source files and destination directory
18.11. Selecting the files to copy
18.12. Copying files using the copy() method without up-to-date check
18.13. Copying files using the copy() method with up-to-date check
18.14. Renaming files as they are copied
18.15. Filtering files as they are copied
18.16. Nested copy specs
18.17. Using the Sync task to copy dependencies
18.18. Creating a ZIP archive
18.19. Creation of ZIP archive
18.20. Configuration of archive task - custom archive name
18.21. Configuration of archive task - appendix & classifier
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. Renaming imported Ant targets
19.13. Setting an Ant property
19.14. Getting an Ant property
19.15. Setting an Ant reference
19.16. Getting an Ant reference
19.17. Fine tuning Ant logging
20.1. Single project build
20.2. Hierarchical layout
20.3. Flat layout
20.4. Modification of elements of the project tree
20.5. Adding of test task to each project which has certain property set
20.6. Notifications
20.7. Setting of certain property to all tasks
20.8. Logging of start and end of each task execution
22.1. Using stdout to write log messages
22.2. Writing your own log messages
22.3. Using SLF4J to write log messages
22.4. Configuring standard output capture
22.5. Configuring standard output capture for a task
22.6. Customizing what Gradle logs
23.1. Definition of a configuration
23.2. Accessing a configuration
23.3. Configuration of a configuration
23.4. Module dependencies
23.5. Artifact only notation
23.6. Dependency with classifier
23.7. Iterating over a configuration
23.8. Client module dependencies - transitive dependencies
23.9. Project dependencies
23.10. File dependencies
23.11. Generated file dependencies
23.12. Gradle API dependencies
23.13. Gradle's Groovy dependencies
23.14. Excluding transitive dependencies
23.15. Optional attributes of dependencies
23.16. Collections and arrays of dependencies
23.17. Dependency configurations
23.18. Dependency configurations for project
23.19. Configuration.copy
23.20. Accessing declared dependencies
23.21. Configuration.files
23.22. Configuration.files with spec
23.23. Configuration.copy
23.24. Configuration.copy vs. Configuration.files
23.25. Adding central Maven repository
23.26. Adding Bintray's JCenter Maven repository
23.27. Using Bintrays's JCenter with HTTP
23.28. Adding the local Maven cache as a repository
23.29. Adding custom Maven repository
23.30. Adding additional Maven repositories for JAR files
23.31. Accessing password protected Maven repository
23.32. Flat repository resolver
23.33. Ivy repository
23.34. Ivy repository with named layout
23.35. Ivy repository with pattern layout
23.36. Ivy repository with multiple custom patterns
23.37. Ivy repository with Maven compatible layout
23.38. Ivy repository
23.39. Declaring a Maven and Ivy repository
23.40. Providing credentials to a Maven and Ivy repository
23.41. Declaring a S3 backed Maven and Ivy repository
23.42. Configure repository to use only digest authentication
23.43. Configure repository to use preemptive authentication
23.44. Accessing a repository
23.45. Configuration of a repository
23.46. Definition of a custom repository
23.47. Forcing consistent version for a group of libraries
23.48. Using a custom versioning scheme
23.49. Blacklisting a version with a replacement
23.50. Changing dependency group and/or name at the resolution
23.51. Substituting a module with a project
23.52. Substituting a project with a module
23.53. Conditionally substituting a dependency
23.54. Specifying default dependencies on a configuration
23.55. Enabling dynamic resolve mode
23.56. 'Latest' version selector
23.57. Custom status scheme
23.58. Custom status scheme by module
23.59. Ivy component metadata rule
23.60. Rule source component metadata rule
23.61. Component selection rule
23.62. Component selection rule with module target
23.63. Component selection rule with metadata
23.64. Component selection rule using a rule source object
23.65. Declaring module replacement
23.66. Dynamic version cache control
23.67. Changing module cache control
24.1. Multi-project tree - water & bluewhale projects
24.2. Build script of water (parent) project
24.3. Multi-project tree - water, bluewhale & krill projects
24.4. Water project build script
24.5. Defining common behavior of all projects and subprojects
24.6. Defining specific behaviour for particular project
24.7. Defining specific behaviour for project krill
24.8. Adding custom behaviour to some projects (filtered by project name)
24.9. Adding custom behaviour to some projects (filtered by project properties)
24.10. Running build from subproject
24.11. Evaluation and execution of projects
24.12. Evaluation and execution of projects
24.13. Running tasks by their absolute path
24.14. Dependencies and execution order
24.15. Dependencies and execution order
24.16. Dependencies and execution order
24.17. Declaring dependencies
24.18. Declaring dependencies
24.19. Cross project task dependencies
24.20. Configuration time dependencies
24.21. Configuration time dependencies - evaluationDependsOn
24.22. Configuration time dependencies
24.23. Dependencies - real life example - crossproject configuration
24.24. Project lib dependencies
24.25. Project lib dependencies
24.26. Fine grained control over dependencies
24.27. Build and Test Single Project
24.28. Partial Build and Test Single Project
24.29. Build and Test Depended On Projects
24.30. Build and Test Dependent Projects
25.1. Applying a script plugin
25.2. Applying a core plugin
25.3. Applying a community plugin
25.4. Applying plugins only on certain subprojects.
25.5. Using plugins from custom plugin repositories.
25.6. Complete Plugin Publishing Sample
25.7. Applying a binary plugin
25.8. Applying a binary plugin by type
25.9. Applying a plugin with the buildscript block
28.1. Using the Build Dashboard plugin
30.1. Defining an artifact using an archive task
30.2. Defining an artifact using a file
30.3. Customizing an artifact
30.4. Map syntax for defining an artifact using a file
30.5. Configuration of the upload task
31.1. Using the Maven plugin
31.2. Creating a stand alone pom.
31.3. Upload of file to remote Maven repository
31.4. Upload of file via SSH
31.5. Customization of pom
31.6. Builder style customization of pom
31.7. Modifying auto-generated content
31.8. Customization of Maven installer
31.9. Generation of multiple poms
31.10. Accessing a mapping configuration
32.1. Using the Signing plugin
32.2. Signing a configuration
32.3. Signing a configuration output
32.4. Signing a task
32.5. Signing a task output
32.6. Conditional signing
32.7. Signing a POM for deployment
33.1. Applying the “ivy-publish” plugin
33.2. Publishing a Java module to Ivy
33.3. Publishing additional artifact to Ivy
33.4. customizing the publication identity
33.5. Customizing the module descriptor file
33.6. Publishing multiple modules from a single project
33.7. Declaring repositories to publish to
33.8. Choosing a particular publication to publish
33.9. Publishing all publications via the “publish” lifecycle task
33.10. Generating the Ivy module descriptor file
33.11. Publishing a Java module
33.12. Example generated ivy.xml
34.1. Applying the 'maven-publish' plugin
34.2. Adding a MavenPublication for a Java component
34.3. Adding additional artifact to a MavenPublication
34.4. customizing the publication identity
34.5. Modifying the POM file
34.6. Publishing multiple modules from a single project
34.7. Declaring repositories to publish to
34.8. Publishing a project to a Maven repository
34.9. Publish a project to the Maven local repository
34.10. Generate a POM file without publishing
35.1. Using the distribution plugin
35.2. Adding extra distributions
35.3. Configuring the main distribution
35.4. publish main distribution
36.1. Using the announce plugin
36.2. Configure the announce plugin
36.3. Using the announce plugin
37.1. Using the build announcements plugin
37.2. Using the build announcements plugin from an init script
38.1. Defining a custom task
38.2. A hello world task
38.3. A customizable hello world task
38.4. A build for a custom task
38.5. A custom task
38.6. Using a custom task in another project
38.7. Testing a custom task
38.8. Defining an incremental task action
38.9. Running the incremental task for the first time
38.10. Running the incremental task with unchanged inputs
38.11. Running the incremental task with updated input files
38.12. Running the incremental task with an input file removed
38.13. Running the incremental task with an output file removed
38.14. Running the incremental task with an input property changed
39.1. A custom plugin
39.2. A custom plugin extension
39.3. A custom plugin with configuration closure
39.4. Evaluating file properties lazily
39.5. A build for a custom plugin
39.6. Wiring for a custom plugin
39.7. Using a custom plugin in another project
39.8. Applying a community plugin with the plugins DSL
39.9. Testing a custom plugin
39.10. Using the Java Gradle Plugin Development plugin
39.11. Managing domain objects
40.1. Using the Java Gradle Plugin Development plugin
40.2. Using the gradlePlugin {} block.
41.1. Using inherited properties and methods
41.2. Using injected properties and methods
41.3. Configuring the project using an external build script
41.4. Custom buildSrc build script
41.5. Adding subprojects to the root buildSrc project
41.6. Running another build from a build
41.7. Declaring external dependencies for the build script
41.8. A build script with external dependencies
41.9. Ant optional dependencies
42.1. Using init script to perform extra configuration before projects are evaluated
42.2. Declaring external dependencies for an init script
42.3. An init script with external dependencies
42.4. Using plugins in init scripts
43.1. Declaring the TestKit dependency
43.2. Declaring the JUnit dependency
43.3. Using GradleRunner with JUnit
43.4. Using GradleRunner with Spock
43.5. Making the code under test classpath available to the tests
43.6. Injecting the code under test classes into test builds
43.7. Using the Java Gradle Development plugin for generating the plugin metadata
43.8. Automatically injecting the code under test classes into test builds
43.9. Reconfiguring the classpath generation conventions of the Java Gradle Development plugin
43.10. Specifying a Gradle version for test execution
44.1. Using the Java plugin
44.2. Building a Java project
44.3. Adding Maven repository
44.4. Adding dependencies
44.5. Customization of MANIFEST.MF
44.6. Adding a test system property
44.7. Publishing the JAR file
44.8. Eclipse plugin
44.9. Java example - complete build file
44.10. Multi-project build - hierarchical layout
44.11. Multi-project build - settings.gradle file
44.12. Multi-project build - common configuration
44.13. Multi-project build - dependencies between projects
44.14. Multi-project build - distribution file
45.1. Using the Java plugin
45.2. Custom Java source layout
45.3. Accessing a source set
45.4. Configuring the source directories of a source set
45.5. Defining a source set
45.6. Defining source set dependencies
45.7. Compiling a source set
45.8. Assembling a JAR for a source set
45.9. Generating the Javadoc for a source set
45.10. Running tests in a source set
45.11. Filtering tests in the build script
45.12. JUnit Categories
45.13. Grouping TestNG tests
45.14. Preserving order of TestNG tests
45.15. Grouping TestNG tests by instances
45.16. Creating a unit test report for subprojects
45.17. Customization of MANIFEST.MF
45.18. Creating a manifest object.
45.19. Separate MANIFEST.MF for a particular archive
45.20. Configure Java 6 build
46.1. War plugin
46.2. Running web application with Jetty plugin
47.1. Using the War plugin
47.2. Customization of war plugin
48.1. Using the Ear plugin
48.2. Customization of ear plugin
49.1. Using the Jetty plugin
50.1. Using the application plugin
50.2. Configure the application main class
50.3. Configure default JVM settings
50.4. Include output from other tasks in the application distribution
50.5. Automatically creating files for distribution
51.1. Using the Java library distribution plugin
51.2. Configure the distribution name
51.3. Include files in the distribution
52.1. Groovy plugin
52.2. Dependency on Groovy
52.3. Groovy example - complete build file
53.1. Using the Groovy plugin
53.2. Custom Groovy source layout
53.3. Configuration of Groovy dependency
53.4. Configuration of Groovy test dependency
53.5. Configuration of bundled Groovy dependency
53.6. Configuration of Groovy file dependency
53.7. Configure Java 6 build for Groovy
54.1. Using the Scala plugin
54.2. Custom Scala source layout
54.3. Declaring a Scala dependency for production code
54.4. Declaring a Scala dependency for test code
54.5. Declaring a version of the Zinc compiler to use
54.6. Forcing a scala-library dependency for all configurations
54.7. Forcing a scala-library dependency for the zinc configuration
54.8. Adjusting memory settings
54.9. Forcing all code to be compiled
54.10. Configure Java 6 build for Scala
54.11. Explicitly specify a target IntelliJ IDEA version
55.1. Using the ANTLR plugin
55.2. Declare ANTLR version
55.3. setting custom max heap size and extra arguments for ANTLR
56.1. Using the Checkstyle plugin
56.2. Customizing the HTML report
57.1. Using the CodeNarc plugin
58.1. Using the FindBugs plugin
58.2. Customizing the HTML report
59.1. Using the JDepend plugin
60.1. Using the PMD plugin
61.1. Applying the JaCoCo plugin
61.2. Configuring JaCoCo plugin settings
61.3. Configuring test task
61.4. Configuring test task
61.5. Using application plugin to generate code coverage data
61.6. Coverage reports generated by applicationCodeCoverageReport
62.1. Using the OSGi plugin
62.2. Configuration of OSGi MANIFEST.MF file
63.1. Using the Eclipse plugin
63.2. Using the Eclipse WTP plugin
63.3. Partial Overwrite for Classpath
63.4. Partial Overwrite for Project
63.5. Export Dependencies
63.6. Customizing the XML
64.1. Using the IDEA plugin
64.2. Partial Rewrite for Module
64.3. Partial Rewrite for Project
64.4. Export Dependencies
64.5. Customizing the XML
65.1. applying a rule source plugin
65.2. a model creation rule
65.3. a model mutation rule
65.4. creating a task
65.5. a managed type
65.6. a String property
65.7. a File property
65.8. a Long property
65.9. a boolean property
65.10. an int property
65.11. a managed property
65.12. an enumeration type property
65.13. a managed set
65.14. strongly modelling sources sets
65.15. a DSL example applying a rule to every element in a scope
65.16. DSL configuration rule
65.17. Configuration run when required
65.18. Configuration not run when not required
65.19. DSL creation rule
65.20. DSL creation rule without initialization
65.21. Initialization before configuration
65.22. Nested DSL creation rule
65.23. Nested DSL configuration rule
65.24. DSL configuration rule for each element in a map
65.25. Nested DSL property configuration
65.26. a DSL example showing type conversions
65.27. a DSL rule using inputs
65.28. model task output
68.1. Using the Java software plugins
68.2. Creating a java library
68.3. Configuring a source set
68.4. Creating a new source set
68.5. The components report
68.6. Declaring a dependency onto a library
68.7. Declaring a dependency onto a project with an explicit library
68.8. Declaring a dependency onto a project with an implicit library
68.9. Declaring a dependency onto a library published to a Maven repository
68.10. Declaring a module dependency using shorthand notation
68.11. Configuring repositories for dependency resolution
68.12. Specifying api packages
68.13. Specifying api dependencies
68.14. Main sources
68.15. Client component
68.16. Broken client component
68.17. Recompiling the client
68.18. Declaring target platforms
68.19. Declaring binary specific sources
68.20. Declaring target platforms
68.21. Using the JUnit plugin
68.22. Executing the test suite
68.23. Executing the test suite
68.24. Declaring a component under test
68.25. Declaring local Java installations
69.1. Using the Play plugin
69.2. The components report
69.3. Selecting a version of the Play Framework
69.4. Adding dependencies to a Play application
69.5. Adding extra source sets to a Play application
69.6. Configuring Scala compiler options
69.7. Configuring routes style
69.8. Configuring a custom asset pipeline
69.9. Configuring dependencies on Play subprojects
69.10. Add extra files to a Play application distribution
69.11. Applying both the Play and IDEA plugins
70.1. Defining a library component
70.2. Defining executable components
70.3. The components report
70.4. The 'cpp' plugin
70.5. C++ source set
70.6. The 'c' plugin
70.7. C source set
70.8. The 'assembler' plugin
70.9. The 'objective-c' plugin
70.10. The 'objective-cpp' plugin
70.11. Settings that apply to all binaries
70.12. Settings that apply to all shared libraries
70.13. Settings that apply to all binaries produced for the 'main' executable component
70.14. Settings that apply only to shared libraries produced for the 'main' library component
70.15. The 'windows-resources' plugin
70.16. Configuring the location of Windows resource sources
70.17. Building a resource-only dll
70.18. Providing a library dependency to the source set
70.19. Providing a library dependency to the binary
70.20. Declaring project dependencies
70.21. Creating a precompiled header file
70.22. Including a precompiled header file in a source file
70.23. Configuring a precompiled header
70.24. Defining build types
70.25. Configuring debug binaries
70.26. Defining platforms
70.27. Defining flavors
70.28. Targeting a component at particular platforms
70.29. Building all possible variants
70.30. Defining tool chains
70.31. Reconfigure tool arguments
70.32. Defining target platforms
70.33. Registering CUnit tests
70.34. Running CUnit tests
70.35. Registering GoogleTest tests
71.1. an example of using a custom software model
71.2. Declare a custom component
71.3. Register a custom component
71.4. Declare a custom binary
71.5. Register a custom binary
71.6. Declare a custom source set
71.7. Register a custom source set
71.8. Generates documentation binaries
71.9. Generates tasks for text source sets
71.10. Register a custom source set
71.11. an example of using a custom software model
71.12. foo bar
71.13. public type and internal view declaration
71.14. type registration
71.15. public and internal data mutation
71.16. example build script and model report output
B.1. Variables scope: local and script wide
B.2. Distinct configuration and execution phase