Файл: Gradle.pdf

Gradle User Guide

A better way to build

Version 1.0-rc-3

Hans Dockter

Adam Murdoch

Copyright © 2007-2010 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. 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. 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. Reusing and expiration of daemons

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 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. The Build Environment

15.1. Configuring the build environment via gradle.properties 15.2. Accessing the web via a proxy

16. Writing Build Scripts

16.1. The Gradle build language

16.2. The Project API

16.3. The Script API

16.4. Declaring variables

16.5. Some Groovy basics

17. More about Tasks

17.1. Defining tasks

17.2. Locating tasks

17.3. Configuring tasks

17.4. Adding dependencies to a task 17.5. Adding a description to a task 17.6. Replacing tasks

17.7. Skipping tasks

17.8. Skipping tasks that are up-to-date 17.9. Task rules

17.10. Summary

18. Working With Files

18.1. Locating files

18.2. File collections

18.3. File trees

18.4. Using the contents of an archive as a file tree 18.5. Specifying a set of input files

18.6. Copying files

18.7. Using the Sync task

18.8. Creating archives

19. Logging

19.1. Choosing a log level

19.2. Writing your own log messages

19.3. Logging from external tools and libraries 19.4. Changing what Gradle logs

20. Using Ant from Gradle

20.1. Using Ant tasks and types in your build 20.2. Importing an Ant build

20.3. Ant properties and references

20.4. API

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. Experimental 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

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. Tasks

40.3. Project layout

40.4. Dependency management

40.5. Convention properties

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. Dependency Management

43.1. Introduction

43.2. Dependency management overview

43.3. Dependency configurations

43.4. How to declare your dependencies

43.5. Working with dependencies

43.6. Repositories

43.7. How dependency resolution works

43.8. The dependency cache

43.9. Strategies for transitive dependency management

44. Publishing artifacts

44.1. Introduction

44.2. Artifacts and configurations

44.3. Declaring artifacts

44.4. Publishing artifacts

44.5. More about project libraries

45. The Maven Plugin

45.1. Usage

45.2. Tasks

45.3. Dependency management

45.4. Convention properties

45.5. Convention methods

45.6. Interacting with Maven repositories

46. The Signing Plugin

46.1. Usage

46.2. Signatory credentials

46.3. Specifying what to sign

46.4. Publishing the signatures

46.5. Signing POM files

47. C++ Support

47.1. Usage

47.2. Source code locations

47.3. Compiling

47.4. Configuring the compiler

47.5. Working with shared libraries

47.6. Dependencies

47.7. Publishing

48. The Build Lifecycle

48.1. Build phases

48.2. Settings file

48.3. Multi-project builds

48.4. Initialization

48.5. Configuration and execution of a single project build

48.6. Responding to the lifecycle in the build script

49. Multi-project Builds

49.1. Cross project configuration

49.2. Subproject configuration

49.3. Execution rules for multi-project builds 49.4. Running tasks by their absolute path 49.5. Project and task paths

49.6. Dependencies - Which dependencies?

49.7. Project lib dependencies

49.8. Multi-Project Building and Testing 49.9. Property and method inheritance 49.10. Summary

50. Writing Custom Task Classes

50.1. Packaging a task class

50.2. Writing a simple task class

50.3. A standalone project

51. Writing Custom Plugins

51.1. Packaging a plugin

51.2. Writing a simple plugin

51.3. Getting input from the build

51.4. Working with files in custom tasks and plugins 51.5. A standalone project

51.6. Maintaining multiple domain objects

52. Organizing Build Logic

52.1. Inherited properties and methods

52.2. Injected configuration

52.3. Build sources in the buildSrc project 52.4. Running another Gradle build from a build 52.5. External dependencies for the build script 52.6. Ant optional dependencies

52.7. Summary

53. Initialization Scripts

53.1. Basic usage

53.2. Using an init script

53.3. Writing an init script

53.4. External dependencies for the init script

54. The Gradle Wrapper

54.1. Configuration

54.2. Unix file permissions

54.3. Environment variable

55. Embedding Gradle

55.1. Introduction to the Tooling API

55.2. Tooling API and the Gradle Build Daemon

55.3. 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.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.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.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.Configuring an HTTP proxy

15.2.Configuring an HTTPS proxy

16.1.Accessing property of the Project object

16.2.Using local variables

16.3.Using extra properties

16.4.Groovy JDK methods

16.5.Property accessors

16.6.Method call without parentheses

16.7.List and map literals

16.8.Closure as method parameter

16.9.Closure delegates

17.1.Defining tasks

17.2.Defining tasks - using strings

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