Following 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 NN

  • A terminal or IDE application

  • A Java Development Kit (JDK), version 1.7 or better if using the Gradle Groovy DSL, version 1.8 or better if using the Gradle Kotlin DSL (only necessary to run Gradle)

  • A Gradle distribution, version 4.8 or better

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

Initialize a project

First, let’s create a new directory where our project will go.

❯ mkdir basic-demo
❯ cd basic-demo

Now we can use Gradle’s init command to generate a simple project. We will explore everything that is generated so you know exactly what’s going on.

❯ gradle init (1)
Starting a Gradle Daemon (subsequent builds will be faster)

BUILD SUCCESSFUL in 3s
2 actionable tasks: 2 executed
1 If you want to use the Kotlin DSL use gradle init --dsl kotlin. See the documentation for details.

The command should show "BUILD SUCCESSFUL" and generate the following "empty" project. If it doesn’t, please ensure that Gradle is installed properly, and that you have the JAVA_HOME environment variable set correctly.

This is what Gradle generated for you.

Groovy
├── build.gradle  (1)
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar  (2)
│       └── gradle-wrapper.properties  (3)
├── gradlew  (4)
├── gradlew.bat  (5)
└── settings.gradle  (6)
Kotlin
├── build.gradle.kts  (1)
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar  (2)
│       └── gradle-wrapper.properties  (3)
├── gradlew  (4)
├── gradlew.bat  (5)
└── settings.gradle.kts  (6)
1 Project configuration script for configuring tasks in the current project
2 Gradle Wrapper executable JAR
3 Gradle Wrapper configuration properties
4 Gradle Wrapper script for Unix-based systems
5 Gradle Wrapper script for Windows
6 Settings configuration script for configuring which Projects participate in the build
gradle init can generate various different types of projects, and even knows how to translate simple pom.xml files to Gradle.

Boom! Roasted. We could just end the guide here, but chances are you want to know how to use Gradle in this project. Let’s do that.

Create a task

Gradle provides APIs for creating and configuring tasks through a Groovy or Kotlin-based DSL. A Project includes a collection of Tasks, each of which performs some basic operation.

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 useful (see the documentation for details), but here, once again, let’s 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) in your build file 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.)

build.gradle
task copy(type: Copy, group: "Custom", description: "Copies sources to the dest directory") {
    from "src"
    into "dest"
}
build.gradle.kts
tasks.create<Copy>("copy") {
    description = "Copies sources to the dest directory"
    group = "Custom"

    from("src")
    into("dest")
}

Here, group and description can be anything you want. You can even omit them, but doing so will also omit them from the tasks report, used later.

Now execute your new copy task:

❯ ./gradlew copy
> Task :copy

BUILD SUCCESSFUL in 0s
1 actionable task: 1 executed

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.

Apply 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 script file using the plugins syntax. Be sure to add the plugins {} block at the top of the file.

build.gradle
plugins {
    id "base"
}

... rest of the build file ...
build.gradle.kts
plugins {
    id("base")
}

... rest of the build file ...

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

build.gradle
task zip(type: Zip, group: "Archive", description: "Archives sources in a zip file") {
    from "src"
    setArchiveName "basic-demo-1.0.zip"
}
build.gradle.kts
tasks.create<Zip>("zip") {
    description = "Archives sources in a zip file"
    group = "Archive"

    from("src")
    setArchiveName("basic-demo-1.0.zip")
}

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

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

❯ ./gradlew zip
> Task :zip

BUILD SUCCESSFUL in 0s
1 actionable task: 1 executed

Explore and debug your build

Let’s see what else we can do with Gradle in our new project. A full reference to the command-line interface is available as well.

Discover available tasks

The tasks command lists Gradle tasks that you can invoke, including those added by the base plugin, and custom tasks you just added as well.

❯ ./gradlew tasks

> Task :tasks

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

Archive tasks
-------------
zip - Archives sources in a zip file

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

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

Custom tasks
------------
copy - Simply copies sources to a the build directory

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

Verification tasks
------------------
check - Runs all checks.

Rules
-----
Pattern: clean<TaskName>: Cleans the output files of a task.
Pattern: build<ConfigurationName>: Assembles the artifacts of a configuration.
Pattern: upload<ConfigurationName>: Assembles and uploads the artifacts belonging to a configuration.

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

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

BUILD SUCCESSFUL in 0s
1 actionable task: 1 executed

Analyze and debug your build

Gradle also provides a rich, web-based view of your build called a build scan.

basic demo build scan

By using the --scan option or by explicitly applying the build scan plugin to your project, you can create a build scan at link:scans.gradle.com free of charge. Publishing build scans to scans.gradle.com transmits this data to Gradle’s servers. To keep your data on your own servers, check out Gradle Enterprise.

Try creating a build scan by adding --scan when executing a task.

❯ ./gradlew zip --scan

BUILD SUCCESSFUL in 0s
1 actionable task: 1 up-to-date

Publishing a build scan to scans.gradle.com requires accepting the Terms of Service defined at https://scans.gradle.com/terms-of-service. Do you accept these terms? [yes, no]
Gradle Cloud Services license agreement accepted.

Publishing build scan...
https://gradle.com/s/repnge6srr5qs

If you browse around your build scan, you should be able to easily find out what tasks where executed and how long they took, which plugins were applied, and much more. Consider sharing a build scan the next time you are debugging something on StackOverflow.

Learn more about how to configure and use build scans in the Build Scan Plugin User Manual.

Discover available properties

The properties command tells you about a project’s attributes.

❯ ./gradlew properties

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

> Task :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
> Task :properties

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

buildDir: /Users/.../basic-demo/build
buildFile: /Users/.../basic-demo/build.gradle.kts
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 the fully-qualified path name to your build script, which resides in the projectDir — by default.

You can change many of the properties. For example, you might try adding the following lines to your build script file, and re-execute gradle properties.

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

Next Steps

Congratulations! You have created a new Gradle build and learned how to inspect Gradle builds!

Chances are you want to create a library or application for a specific platform, so here are some guides that will teach you more about creating builds in your platform of choice:

You can also checkout many sample Gradle builds on GitHub.

Help improve this guide

Have feedback or a question? Found a typo? Like all Gradle guides, help is just a GitHub issue away. Please add an issue or pull request to gradle-guides/creating-new-gradle-builds and we’ll get back to you.