Gradle

A build system

Version 0.8

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?
2.3. Missing features
3. Getting Started
3.1. Prerequisites
3.2. Download
3.3. Unpacking
3.4. Environment variables
3.5. Running and testing your installation
3.6. JVM options
4. Build Script Basics
4.1. Hello world
4.2. Build scripts are code
4.3. Task dependencies
4.4. Dynamic tasks
4.5. Manipulating existing tasks
4.6. Shortcut notations
4.7. Dynamic task properties
4.8. Using Ant Tasks
4.9. Using methods
4.10. Default tasks
4.11. Configure by DAG
4.12. Summary
5. Java Quickstart
5.1. A basic Java project
5.2. Multi-project Java build
5.3. Summary
6. Groovy Quickstart
6.1. A basic Groovy project
6.2. Summary
7. Web Application Quickstart
7.1. Building a WAR file
7.2. Running your web application
7.3. Summary
8. Artifact Basics
8.1. Artifact configurations
8.2. Repositories
8.3. External dependencies
8.4. Artifact publishing
8.5. API
9. Using the Gradle Command-Line
9.1. Executing multiple tasks
9.2. Excluding tasks
9.3. Task name abbreviation
9.4. Selecting which build to execute
9.5. Obtaining information about your build
9.6. Dry Run
9.7. Summary
10. Using the Gradle Graphical User Interface
10.1. Task Tree
10.2. Favorites
10.3. Command Line
10.4. Setup
11. Tutorial - 'This and That'
11.1. Directory creation
11.2. Gradle properties and system properties
11.3. Accessing the web via a proxy
11.4. Caching
11.5. Configuring arbitrary objects
12. The Project and Task API
12.1. Project API
12.2. Task API
12.3. Summary
13. More about Tasks
13.1. Defining tasks
13.2. Locating tasks
13.3. Configuring tasks
13.4. Adding dependencies to a task
13.5. Adding a description to a task
13.6. Replacing tasks
13.7. Skipping tasks
13.8. Task rules
13.9. Summary
14. Working With Files
14.1. Locating files
14.2. File collections
14.3. File trees
14.4. Specifying a set of files
14.5. Copying files
15. Logging
15.1. Choosing a log level
15.2. Writing your own log messages
15.3. Logging from external tools and libraries
16. Using Ant from Gradle
16.1. Using Ant tasks and types in your build
16.2. Importing an Ant build
16.3. Ant properties and references
16.4. API
17. Using Plugins
17.1. Declaring plugins
17.2. Using the convention object
17.3. Summary
18. The Java Plugin
18.1. Source sets
18.2. Tasks
18.3. Project layout
18.4. Dependency management
18.5. Convention properties
18.6. Working with source sets
18.7. Javadoc
18.8. Clean
18.9. Resources
18.10. CompileJava
18.11. Test
18.12. Jar
18.13. Adding archives
18.14. Uploading
18.15. Eclipse
19. The Groovy Plugin
19.1. Tasks
19.2. Project layout
19.3. Dependency management
19.4. Convention properties
19.5. Source set properties
19.6. CompileGroovy
20. The Scala Plugin
20.1. Tasks
20.2. Project layout
20.3. Dependency Management
20.4. Convention Properties
20.5. Source set properties
21. The War Plugin
21.1. Tasks
21.2. Project layout
21.3. Dependency management
21.4. Convention properties
21.5. War
21.6. Customizing
21.7. Eclipse WTP
22. The Jetty Plugin
22.1. Tasks
22.2. Project layout
22.3. Dependency management
22.4. Convention properties
23. The Maven Plugin
23.1. Tasks
23.2. Project layout
23.3. Dependency management
23.4. Convention properties
24. The Code Quality Plugin
24.1. Tasks
24.2. Project layout
24.3. Dependency management
24.4. Convention properties
25. The OSGi Plugin
25.1. Tasks
25.2. Project layout
25.3. Dependency management
25.4. Convention properties
26. The Eclipse Plugin
26.1. Usage
26.2. Tasks
27. The Project Report Plugin
27.1. Tasks
27.2. Project layout
27.3. Dependency management
27.4. Convention properties
28. Dependency Management
28.1. Introduction
28.2. Dependency management overview
28.3. How to declare your dependencies
28.4. Working with dependencies
28.5. Repositories
28.6. Strategies for transitive dependency management
29. Artifact Management
29.1. Introduction
29.2. Artifacts and configurations
29.3. Uploading artifacts
29.4. More about project libraries
29.5. Interacting with Maven repositories
30. The Build Lifecycle
30.1. Build phases
30.2. Settings file
30.3. Multi-project builds
30.4. Initialization
30.5. Configuration and execution of a single project build
30.6. Responding to the lifecycle in the build script
31. Multi-project Builds
31.1. Cross project configuration
31.2. Subproject configuration
31.3. Execution rules for multi-project builds
31.4. Running tasks by their absolute path
31.5. Project and task paths
31.6. Dependencies - Which dependencies?
31.7. Project lib dependencies
31.8. Multi-Project Building and Testing
31.9. Property and method inheritance
31.10. Summary
32. Writing Custom Tasks
33. Writing Custom Plugins
34. Organizing Build Logic
34.1. Build sources
34.2. External dependencies for the build script
34.3. Ant optional dependencies
34.4. Summary
35. Initialization Scripts
35.1. Basic usage
35.2. External dependencies for the init script
36. The Gradle Wrapper
36.1. Configuration
36.2. Unix file permissions
36.3. Environment variable
37. Embedding Gradle
A. Potential Traps
A.1. Groovy script variables
A.2. Configuration and execution phase
B. Gradle Command Line
C. Existing IDE Support and how to cope without it
C.1. IntelliJ
C.2. Eclipse
C.3. Using Gradle without IDE support

List of Examples

4.1. The first build script
4.2. Execution of a build script
4.3. Using Groovy in Gradle's tasks
4.4. Using Groovy in Gradle's tasks
4.5. Declaration of dependencies between tasks
4.6. Lazy dependsOn - the other task does not exist (yet)
4.7. Dynamic creation of a task
4.8. Accessing a task via API - adding a dependency
4.9. Accessing a task via API - adding behaviour
4.10. Accessing task as a property of the build script
4.11. Assigning properties to a task
4.12. Using AntBuilder to execute ant.checksum target
4.13. Using methods to organize your build logic
4.14. Defining a default tasks
4.15. Different outcomes of build depending on chosen tasks
5.1. Using the Java plugin
5.2. Building a Java project
5.3. Adding Maven repository
5.4. Adding dependencies
5.5. Customization of MANIFEST.MF
5.6. Adding system property
5.7. Publishing the JAR file
5.8. Eclipse plugin
5.9. Java example - complete build file
5.10. Multi-project build - hierarchical layout
5.11. Multi-project build - settings.gradle file
5.12. Multi-project build - common configuration
5.13. Multi-project build - dependencies between projects
5.14. Multi-project build - distribution file
6.1. Groovy plugin
6.2. Dependency on Groovy 1.6.0
6.3. Groovy example - complete build file
7.1. War plugin
7.2. Running web application with Jetty plugin
8.1. Definition of a configuration
8.2. Accessing a configuration
8.3. Configuration of a configuration
8.4. Usage of Maven central repository
8.5. Usage of a local directory
8.6. Accessing a repository
8.7. Configuration of a repository
8.8. Definition of an external dependency
8.9. Usage of external dependency of a configuration
9.1. Executing multiple tasks
9.2. Excluding tasks
9.3. Abbreviated task name
9.4. Abbreviated camel case task name
9.5. Selecting the project using a build file
9.6. Selecting the project using project directory
9.7. Obtaining information about tasks
9.8. Obtaining information about dependencies
10.1. Launching the GUI
11.1. Directory creation with mkdir
11.2. Directory creation with Directory tasks
11.3. Setting properties with a gradle.properties file
11.4. Accessing the web via a proxy
11.5. Configuring arbitrary objects
12.1. Accessing property of the Project object
12.2. Project properties
13.1. Defining tasks
13.2. Defining tasks - using strings
13.3. Defining tasks with alternative syntax
13.4. Accessing tasks as properties
13.5. Accessing tasks via tasks collection
13.6. Accessing tasks by path
13.7. Creating a copy task
13.8. Configuring a task - various ways
13.9. Configuring a task - fluent interface
13.10. Configuring a task - with closure
13.11. Configuring a task - with configure() method
13.12. Defining a task with closure
13.13. Adding dependency on task from another project
13.14. Adding dependency using task object
13.15. Adding dependency using closure
13.16. Adding a description to a task
13.17. Overwriting a task
13.18. Skipping a task using a predicate
13.19. Skipping tasks with StopExecutionException
13.20. Enabling and disabling tasks
13.21. Task rule
13.22. Dependency on rule based tasks
14.1. Locating files
14.2. Creating a file collection
14.3. Using a file collection
14.4. Implementing a file collection
14.5. Creating a file tree
14.6. Using a file tree
14.7. Specifying a set of files
14.8. Specifying a set of files
14.9. Copying files using the copy task
14.10. Copying files using the copy() method
15.1. Using stdout to write log messages
15.2. Writing your own log messages
15.3. Using SLF4J to write log messages
15.4. Configuring standard output capture
15.5. Configuring standard output capture for a task
16.1. Using an Ant task
16.2. Passing nested text to an Ant task
16.3. Passing nested elements to an Ant task
16.4. Using an Ant type
16.5. Using a custom Ant task
16.6. Declaring the classpath for a custom Ant task
16.7. Using a custom Ant task and dependency management together
16.8. Importing an Ant build
16.9. Task that depends on Ant target
16.10. Adding behaviour to an Ant target
16.11. Ant target that depends on Gradle task
16.12. Setting an Ant property
16.13. Getting an Ant property
16.14. Setting an Ant reference
16.15. Getting an Ant reference
17.1. Using plugin
17.2. Configuring a plugin task
17.3. Plugin convention object
17.4. Using the plugin convention object
18.1. Custom Java source layout
18.2. Accessing a source set
18.3. Configuring the source directories of a source set
18.4. Defining a source set
18.5. Defining the classpath of a source set
18.6. Assembling a JAR for a source set
18.7. Generating the Javadoc for a source set
18.8. Running tests in a source set
18.9. Creation of ZIP archive
18.10. Configuration of archive task - custom archive name
18.11. Configuration of archive task - appendix & classifier
18.12. Adding content to archive - include & exclude
18.13. Adding content to archive - arbitrary files
18.14. Adding content to archive - zipFileSet
18.15. Creation of TAR archive
18.16. Customization of MANIFEST.MF
18.17. Customization of MANIFEST.MF for a particular archive
19.1. Custom Groovy source layout
19.2. Configuration of Groovy plugin
19.3. Configuration of Groovy plugin
20.1. Custom Scala source layout
20.2. Declaring the Scala version to use
21.1. Customization of war plugin
21.2. Generation of JAR archive in addition to WAR archive
25.1. Configuration of OSGi MANIFEST.MF file
28.1. Module dependencies
28.2. Artifact only notation
28.3. Dependency with classifier
28.4. Client module dependencies - transitive dependencies
28.5. Project dependencies
28.6. File dependencies
28.7. Generated file dependencies
28.8. Excluding transitive dependencies
28.9. Optional attributes of dependencies
28.10. Collections and arrays of dependencies
28.11. Dependency configurations
28.12. Dependency configurations for project
28.13. Configuration.copy
28.14. Accessing declared dependencies
28.15. Configuration.files
28.16. Configuration.files with spec
28.17. Configuration.copy
28.18. Configuration.copy vs. Configuration.files
28.19. Adding central Maven repository
28.20. Adding many Maven repositories
28.21. Adding custom Maven repository
28.22. Adding additional Maven repositories for JAR files
28.23. Accessing password protected Maven repository
28.24. Flat repository resolver
28.25. Definition of a custom repository
29.1. Assignment of an artifact to a configuration
29.2. Configuration of the upload task
29.3. Upload of file to remote Maven repository
29.4. Upload of file via SSH
29.5. Customization of pom
29.6. Customization of Maven installer
29.7. Generation of multiple poms
29.8. Accessing a mapping configuration
30.1. Single project build
30.2. Hierarchical layout
30.3. Flat layout
30.4. Modification of elements of the project tree
30.5. Modification of elements of the project tree
30.6. Adding of test task to each project which has certain property set
30.7. Notifications
30.8. Setting of certain property to all tasks
30.9. Logging of start and end of each task execution
31.1. Multi-project tree - water & bluewhale projects
31.2. Build script of water (parent) project
31.3. Multi-project tree - water, bluewhale & krill projects
31.4. Water project build script
31.5. Defining common behaviour of all projects and subprojects
31.6. Defining specific behaviour for particular project
31.7. Defining specific behaviour for project krill
31.8. Adding custom behaviour to some projects (filtered by project name)
31.9. Adding custom behaviour to some projects (filtered by project properties)
31.10. Running build from subproject
31.11. Evaluation and execution of projects
31.12. Evaluation and execution of projects
31.13. Running tasks by their absolute path
31.14. Dependencies and execution order
31.15. Dependencies and execution order
31.16. Dependencies and execution order
31.17. Declaring dependencies
31.18. Declaring dependencies
31.19. Project execution dependencies
31.20. Cross project task dependencies
31.21. Configuration time dependencies
31.22. Configuration time dependencies - evaluationDependsOn
31.23. Configuration time dependencies
31.24. Dependencies - real life example - crossproject configuration
31.25. Project lib dependencies
31.26. Project lib dependencies
31.27. Fine grained control over dependencies
31.28. Build and Test Single Project
31.29. Partial Build and Test Single Project
31.30. Build and Test Depended On Projects
31.31. Build and Test Dependent Projects
32.1. Defining a custom task
32.2. A hello world task
32.3. A customizable hello world task
33.1. A custom plugin
33.2. A custom plugin convention
34.1. Declaring external dependencies for the build script
34.2. A build script with external dependencies
34.3. Ant optional dependencies
35.1. Declaring external dependencies for an init script
35.2. An init script with external dependencies
36.1. Wrapper task
36.2. Configuration of wrapper task
A.1. Variables scope: local and script wide
A.2. Distinct configuration and execution phase