Gradle

A build system

Version 0.7

Hans Dockter

Adam Murdoch

Copyright © 2007-2009 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. Unpacking
3.3. Environment variables
3.4. Running and testing your installation
3.5. 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. Artifact Basics
5.1. Artifact configurations
5.2. Repositories
5.3. External dependencies
5.4. Artifact publishing
5.5. API
6. Java Quickstart
6.1. A basic Java project
6.2. Multi-project Java build
6.3. Summary
7. Groovy Quickstart
7.1. A basic Groovy project
7.2. Summary
8. Web Application Quickstart
8.1. Building a WAR file
8.2. Running your web application
8.3. Summary
9. Using the Gradle Command-Line
9.1. Executing multiple tasks
9.2. Selecting which build to execute
9.3. Obtaining information about your build
9.4. Dry Run
10. Tutorial - 'This and That'
10.1. Skipping tasks
10.2. Directory creation
10.3. Gradle properties and system properties
10.4. Accessing the web via a proxy
10.5. Caching
10.6. Configuring arbitrary objects
11. The Project and Task API
11.1. Project API
11.2. Task API
11.3. Summary
12. More about Tasks
12.1. Defining tasks
12.2. Locating tasks
12.3. Configuring tasks
12.4. Adding dependencies to a task
12.5. Adding a description to a task
12.6. Replacing tasks
12.7. Task rules
12.8. Summary
13. Logging
13.1. Choosing a log level
13.2. External tools and standard output
13.3. Sending your own log messages
14. Using Ant from Gradle
14.1. Using Ant tasks and types in your build
14.2. Importing an Ant build
14.3. Ant properties and references
14.4. API
15. Plugins
15.1. Declaring plugins
15.2. Configuration
15.3. Summary
16. The Java Plugin
16.1. Tasks
16.2. Project layout
16.3. Dependency management
16.4. Convention properties
16.5. Javadoc
16.6. Clean
16.7. Resources
16.8. Compile
16.9. Test
16.10. Jar
16.11. Adding archives
16.12. Uploading
16.13. Eclipse
17. The Groovy Plugin
17.1. Tasks
17.2. Project layout
17.3. Dependency management
17.4. Convention properties
17.5. Compile
17.6. Test
18. The War Plugin
18.1. Tasks
18.2. Project layout
18.3. Dependency management
18.4. Convention properties
18.5. War
18.6. Customizing
18.7. Eclipse WTP
19. The Jetty Plugin
19.1. Tasks
19.2. Project layout
19.3. Dependency management
19.4. Convention properties
20. The Maven Plugin
20.1. Tasks
20.2. Project layout
20.3. Dependency management
20.4. Convention properties
21. The OSGi Plugin
21.1. Tasks
21.2. Project layout
21.3. Dependency management
21.4. Convention properties
22. The Eclipse Plugin
22.1. Tasks
22.2. Project layout
22.3. Dependency management
22.4. Convention properties
23. The Project Report Plugin
23.1. Tasks
23.2. Project layout
23.3. Dependency management
23.4. Convention properties
24. How to write Custom Plugins
25. Dependency Management
25.1. Introduction
25.2. Dependency management overview
25.3. How to declare your dependencies
25.4. Working with dependencies
25.5. Repositories
25.6. Strategies for transitive dependency management
26. Artifact Management
26.1. Introduction
26.2. Artifacts and configurations
26.3. Uploading artifacts
26.4. More about project libraries
26.5. Interacting with Maven repositories
27. The Build Lifecycle
27.1. Build phases
27.2. Settings file
27.3. Multi-project builds
27.4. Initialization
27.5. Configuration and execution of a single project build
27.6. Responding to the lifecycle in the build script
28. Multi-project Builds
28.1. Cross project configuration
28.2. Subproject configuration
28.3. Execution rules for multi-project builds
28.4. Running tasks by their absolute path
28.5. Project and task paths
28.6. Dependencies - Which dependencies?
28.7. Project lib dependencies
28.8. Property and method inheritance
28.9. Summary
29. Organizing Build Logic
29.1. Build sources
29.2. External dependencies for the build script
29.3. Ant optional dependencies
29.4. Summary
30. The Gradle Wrapper
30.1. Configuration
30.2. Unix file permissions
30.3. Environment variable
31. 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. Definition of a configuration
5.2. Accessing a configuration
5.3. Configuration of a configuration
5.4. Usage of Maven central repository
5.5. Usage of a local directory
5.6. Accessing a repository
5.7. Configuration of a repository
5.8. Definition of an external dependency
5.9. Usage of external dependency of a configuration
6.1. Java plugin
6.2. Adding Maven repository
6.3. Adding dependencies
6.4. Customization of MANIFEST.MF
6.5. Adding system property
6.6. Publishing the JAR file
6.7. Java example - complete build file
6.8. Multi-project build - hierarchical layout
6.9. Multi-project build - settings.gradle file
6.10. Multi-project build - common configuration
6.11. Multi-project build - dependencies between projects
6.12. Multi-project build - distribution file
7.1. Groovy plugin
7.2. Dependency on Groovy 1.6.0
7.3. Groovy example - complete build file
8.1. War plugin
8.2. Running web application with Jetty plugin
9.1. Executing multiple tasks
9.2. Obtaining information about tasks
9.3. Obtaining information about dependencies
10.1. Skipping tasks using default property name
10.2. Skipping tasks using custom property
10.3. Skipping depending tasks
10.4. Skipping tasks with StopExecutionException
10.5. Enabling and disabling tasks
10.6. Directory creation with mkdir
10.7. Directory creation with Directory tasks
10.8. Setting properties with a gradle.properties file
10.9. Accessing the web via a proxy
10.10. Configuring arbitrary objects
11.1. Accessing property of the Project object
11.2. Project properties
12.1. Defining tasks
12.2. Defining tasks - using strings
12.3. Defining tasks with alternative syntax
12.4. Accessing tasks as properties
12.5. Accessing tasks via tasks collection
12.6. Accessing tasks by path
12.7. Creating a copy task
12.8. Configuring a task - various ways
12.9. Configuring a task - fluent interface
12.10. Configuring a task - with closure
12.11. Configuring a task - with configure() method
12.12. Defining a task with closure
12.13. Adding dependency on task from another project
12.14. Adding dependency using task object
12.15. Adding dependency using closure
12.16. Adding a description to a task
12.17. Overwriting a task
12.18. Task rule
12.19. Dependency on rule based tasks
13.1. Sending your own log message
14.1. Using an Ant task
14.2. Passing nested text to an Ant task
14.3. Passing nested elements to an Ant task
14.4. Using an Ant type
14.5. Using a custom Ant task
14.6. Declaring the classpath for a custom Ant task
14.7. Using a custom Ant task and dependency management together
14.8. Importing an Ant build
14.9. Task that depends on Ant target
14.10. Adding behaviour to an Ant target
14.11. Ant target that depends on Gradle task
14.12. Setting an Ant property
14.13. Getting an Ant property
14.14. Setting an Ant reference
14.15. Getting an Ant reference
15.1. Using plugin
15.2. Configuring a plugin
15.3. Plugin convention object
16.1. Creation of ZIP archive
16.2. Configuration of archive task - custom archive name
16.3. Configuration of archive task - appendix & classifier
16.4. Adding content to archive - include & exclude
16.5. Adding content to archive - arbitrary files
16.6. Adding content to archive - zipFileSet
16.7. Creation of TAR archive
16.8. Customization of MANIFEST.MF
16.9. Customization of MANIFEST.MF for a particular archive
17.1. Configuration of Groovy plugin
17.2. Configuration of Groovy plugin
18.1. Customization of war plugin
18.2. Generation of JAR archive in addition to WAR archive
21.1. Configuration of OSGi MANIFEST.MF file
25.1. Module dependencies
25.2. Artifact only notation
25.3. Dependency with classifier
25.4. Client module dependencies - transitive dependencies
25.5. Project dependencies
25.6. File dependencies
25.7. Excluding transitive dependencies
25.8. Optional attributes of dependencies
25.9. Collections and arrays of dependencies
25.10. Dependency configurations
25.11. Dependency configurations for project
25.12. Configuration.copy
25.13. Accessing declared dependencies
25.14. Configuration.files
25.15. Configuration.files with spec
25.16. Configuration.copy
25.17. Configuration.copy vs. Configuration.files
25.18. Adding central Maven repository
25.19. Adding many Maven repositories
25.20. Adding custom Maven repository
25.21. Adding additional Maven repositories for JAR files
25.22. Flat repository resolver
25.23. Definition of a custom repository
26.1. Assignment of an artifact to a configuration
26.2. Configuration of the upload task
26.3. Upload of file to remote Maven repository
26.4. Upload of file via SSH
26.5. Customization of pom
26.6. Customization of Maven installer
26.7. Generation of multiple poms
26.8. Accessing a mapping configuration
27.1. Single project build
27.2. Hierarchical layout
27.3. Flat layout
27.4. Modification of elements of the project tree
27.5. Modification of elements of the project tree
27.6. Adding of test task to each project which has certain property set
27.7. Notifications
27.8. Setting of certain property to all tasks
27.9. Logging of start and end of each task execution
28.1. Multi-project tree - water & bluewhale projects
28.2. Build script of water (parent) project
28.3. Multi-project tree - water, bluewhale & krill projects
28.4. Water project build script
28.5. Defining common behaviour of all projects and subprojects
28.6. Defining specific behaviour for particular project
28.7. Defining specific behaviour for project krill
28.8. Adding custom behaviour to some projects (filtered by project name)
28.9. Adding custom behaviour to some projects (filtered by project properties)
28.10. Running build from subproject
28.11. Evaluation and execution of projects
28.12. Evaluation and execution of projects
28.13. Running tasks by their absolute path
28.14. Dependencies and execution order
28.15. Dependencies and execution order
28.16. Dependencies and execution order
28.17. Declaring dependencies
28.18. Declaring dependencies
28.19. Project dependencies
28.20. Project dependencies
28.21. Configuration time dependencies
28.22. Configuration time dependencies - evaluationDependsOn
28.23. Configuration time dependencies
28.24. Dependencies - real life example - crossproject configuration
28.25. Project dependencies
28.26. Project dependencies
28.27. Fine grained control over dependencies
29.1. Declaring external dependencies for the build script
29.2. A build script with external dependencies
29.3. Ant optional dependencies
30.1. Wrapper task
30.2. Configuration of wrapper task
A.1. Variables scope: local and script wide
A.2. Distinct configuration and execution phase
Next|Contents