Creating New Gradle Builds

When encountering a project that uses Gradle for the first time, many developers don’t know what Gradle can do for them. The purpose of this guide is to show some of the basic tasks that work in any Gradle build, regardless of type of project. In this guide, you’ll create a trivial Gradle project, invoke some of the basic Gradle commands, and get a sense of how Gradle manages the project.

What you’ll need

• About 15 minutes

• A text editor or IDE

• A Java Development Kit (JDK), version 1.7 or better (only necessary to run Gradle)

• A Gradle distribution, version {gradle-version} or better

Create a project

You can start a new project simply by creating a build.gradle file and adding build logic to it. To keep this example as simple as possible, create a new directory and add an empty file called build.gradle to it.

Note	Shell commands will be shown for Unix-based systems. Windows has analogous commands for each.

$ mkdir basic-demo
$ cd basic-demo
$ touch build.gradle // (1)

1. Create an empty file called build.gradle

Run the tasks command

Gradle is a general-purpose build tool for projects. Gradle itself is built on an object-oriented API, which is made up of many classes and methods, along with a simple syntax for configuring them. The build file itself configures an instance of the org.gradle.api.Project class, which has many built-in properties and methods. From the Project, you have access to all of Gradle’s features.

By default, the name of the build file is called build.gradle. A Project includes a collection of tasks, each of which performs some basic operation.

To see what tasks are available even in this otherwise empty project, run the tasks command at the command prompt.

$ gradle tasks
:tasks

------------------------------------------------------------
All tasks runnable from root project
------------------------------------------------------------

Build Setup tasks
-----------------
init - Initializes a new Gradle build.
wrapper - Generates Gradle wrapper files.

Help tasks
----------
buildEnvironment - Displays all buildscript dependencies declared in root project 'basic-demo'.
components - Displays the components produced by root project 'basic-demo'. [incubating]
dependencies - Displays all dependencies declared in root project 'basic-demo'.
dependencyInsight - Displays the insight into a specific dependency in root project 'basic-demo'.
dependentComponents - Displays the dependent components of components in root project 'basic-demo'. [incubating]
help - Displays a help message.
model - Displays the configuration model of root project 'basic-demo'. [incubating]
projects - Displays the sub-projects of root project 'basic-demo'.
properties - Displays the properties of root project 'basic-demo'.
tasks - Displays the tasks runnable from root project 'basic-demo'.

To see all tasks and more detail, run gradle tasks --all

To see more detail about a task, run gradle help --task <task>

BUILD SUCCESSFUL

As the output shows, Gradle tasks are organized into categories, like Build Setup or Help, and each has a name and an optional description. You can define your own (known as ad hoc) tasks, configure tasks provided by the Gradle library, or use tasks that are added by plugins.

Generate a Gradle wrapper

As the output from the tasks command shows, the wrapper task generates a Gradle wrapper file. The wrapper is a small script and supporting jar and properties file that allows a user to execute Gradle tasks even if they don’t already have Gradle installed. Generating a wrapper also ensures that the user will use the same version of Gradle as the person who created the project.

Tip	While Gradle versions are very good about supporting backward compatibility, using a wrapper ensures that the user is working with a version of Gradle that the project creator supports, and is therefore considered a good practice.

Details about the wrapper task can be seen through the help task.

$ gradle help --task wrapper
:help
Detailed task information for wrapper

Path
     :wrapper

Type
     Wrapper (org.gradle.api.tasks.wrapper.Wrapper)

Options
     --distribution-type     The type of the Gradle distribution to be used by the wrapper.
                             Available values are:
                                  ALL
                                  BIN

     --gradle-distribution-url     The URL to download the Gradle distribution from.

     --gradle-version     The version of the Gradle distribution required by the wrapper.

Description
     Generates Gradle wrapper files.

Group
     Build Setup

BUILD SUCCESSFUL

By default, the wrapper task will generate a wrapper that uses the binary distribution of the same version as the Gradle command. Generate that wrapper now.

$ gradle wrapper
:wrapper

BUILD SUCCESSFUL

This generates a Unix script called gradlew and a Windows command called gradlew.bat, along with a jar file and a properties file. The resulting directory structure looks like:

.
├── build.gradle
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew          // (1)
└── gradlew.bat      // (2)

1. Wrapper script for Unix-based systems

2. Wrapper script for Windows

All subsequent commands in this guide will use the wrapper.

Run the properties task

If the tasks task tells you what tasks are available, the properties command does the same for the project’s attributes. Try that command as well.

$ ./gradlew properties

Note	On Windows, you don’t need the leading ./ in front of the gradlew command.

The output is extensive. Here are just a few of the available properties:

:properties

------------------------------------------------------------
Root project
------------------------------------------------------------

buildDir: /Users/.../basic-demo/build
buildFile: /Users/.../basic-demo/build.gradle
description: null
group:
name: basic-demo
projectDir: /Users/.../basic-demo
version: unspecified

BUILD SUCCESSFUL

The name of the project matches the name of the folder by default. You can also specify group and version properties, but at the moment they are taking their default values, as is description.

The buildFile property is fully-qualified path name to build.gradle, which resides in the buildDir — by default, the build subdirectory of the projectDir, the directory containing the build.gradle file.

You can change many of the properties. Add the following lines to your build.gradle file:

description = 'A trivial Gradle build'
version = '1.0'

Now run the properties task again and see the updated values of the description and version fields.

$ ./gradlew properties
:properties
...
description: A trivial Gradle build
...
version: 1.0
....

Configure a Gradle core task

Gradle comes with a library of tasks that you can configure in your own projects. For example, there is a core type called Copy, which copies files from one location to another. The Copy task is very powerful (see the documentation for details), but here, once again, keep it simple. Perform the following steps:

1. Create a directory called src.

2. Add a file called myfile.txt in the src directory. The contents are arbitrary (it can even be empty), but for convenience add the single line Hello, World! to it.

3. Define a task called copy of type Copy (note the capital letter) that copies the src directory to a new directory called dest. (You don’t have to create the dest directory — the task will do it for you.) The syntax is:

   task copy(type: Copy) {
       from 'src'
       into 'dest'
   }

   Now you can run the tasks command with the --all flag to see the new task:

$ ./gradlew tasks --all
:tasks
...
Other tasks
-----------
copy

Execute the copy task:

$ ./gradlew copy
:copy

BUILD SUCCESSFUL

Verify that it worked as expected by checking that there is now a file called myfile.txt in the dest directory, and that its contents match the contents of the same one in the src directory.

Configure a core task and use a plugin

Gradle includes a range of plugins, and many, many more are available at the Gradle plugin portal. One of the plugins included with the distribution is the base plugin. Combined with a core type called Zip, you can create a zip archive of your project with a configured name and location.

Add the base plugin to your build.gradle file using the plugins syntax. Be sure to add the plugins block at the top of the file.

plugins {
    id 'base'
}

... rest of the build file ...

Now add a task that creates a zip archive from the src directory.

task zip(type: Zip) {
    from 'src'
}

The base plugin works with the settings to create an archive file called basic-demo-1.0.zip in the libraries folder under build\distributions.

In this case, simply run the new zip task and see that the generated zip file is where you expect.

$ ./gradlew zip
zip:

BUILD SUCCESSFUL

Run the tasks command again to see the tasks added by the basic plugin.

$ ./gradlew tasks --all
tasks:

Build tasks
-----------
assemble - Assembles the outputs of this project.
build - Assembles and tests this project.
clean - Deletes the build directory.

...

Other tasks
-----------
copy
zip

The assemble and build tasks aren’t useful in this project, because they are associated with compilation and generation of a release artifact. Many of the language plugins, like the java plugin, are created on top of the base plugin.

The clean task, however, is an easy way to remove the build directory.

$ ./gradlew clean
clean:

BUILD SUCCESSFUL

The build directory should now be gone.

Add a "Hello, World!" task

Since every technology needs a "Hello, World!" example, add an ad hoc task to your Gradle build. The syntax is:

task hello {
    doLast {
        println 'Hello, World!'
    }
}

When executed, this task will print the string "Hello, World!" to the console.

$ ./gradlew hello
:hello
Hello, World!

BUILD SUCCESSFUL

The contents of the hello task use commands from the Gradle DSL, like task and doLast. Writing your own tasks is an interesting topic, but beyond the scope of this guide. See {guides}writing-gradle-tasks[Writing Custom Gradle Tasks] for details.

Next Steps

If you are specifically interested in building Java applications, read the {guides}creating-java-applications[Getting Started Building Java Applications] guide. You should also read the {user-manual}tutorial_java_projects.html[Java Quickstart] chapter of the user manual. To learn about creating other kinds of popular Gradle builds, follow these readings for the type of project you want:

Documentation for other popular project types

• C, C*, *Assembler*, *Objective-c*, *Objective-c: {user-manual}native_software.html[Native builds]

• Scala: {guides}building-scala-libraries[Scala plugin]

• Groovy: {guides}building-groovy-libraries[Groovy quickstart]

• Android: Android userguide

Additional information

Gradle is a very powerful tool, which means you need a good understanding of the underlying model to create maintainable builds. Fortunately, there are just a few core concepts to understand:

• Build phases: read the first section of the {user-manual}build_lifecycle.html[build lifecycle chapter] for a description of these.

• Properties: The project API and {user-manual}writing_build_scripts.html[properties]

• Tasks: {user-manual}more_about_tasks.html[Tasks]

• File handling: {user-manual}working_with_files.html[File handling]

• Dependency management: {user-manual}artifact_dependencies_tutorial.html[Dependency management]