Starting with gradle, creating a simple build.gradle

(note: proof edits pending)

Gradle a very well known building tool, originating in JVM world, but spreading to wider and wider use. A building tool is designed to automate workflows, particularly for building programs but in fact can automate any workflow iincluding building, linting, testing, pushing and much more to make your life easier. Sometimes it could be hard to grasp the concept even after reading the official documentation. This guide focuses on the basics and can enable having gradle up and running within a few minutes.

1. Gradle Introduction
2. A practical workflow for working with gradle
3. Add plugins
4. Configure the plugin
5. Add the dependencies of your project
6. Configure the project information
7. End

1. Gradle Introduction.

The gradle configuration is actually program code, most of which will reside in the build.gradle file in the project root folder. The code in this file must specify the configuration, and can also specify workflow, including tasks which can do steps which would otherwise require shell scrips.

Gradle configurations are currently written in a groovy based DSL. Although there is a development project to use a kotlin based DS, this is still in development and not yet ready for general use.

Before you have this omg-new-language-just-for-building idea, read this quote from google official android documentation:

You don’t need to know Groovy to start configuring your build because the Android plugin for Gradle introduces most of the DSL elements you need.

This applies not just to Android, but to all but very complex builds. Most of the time, you don’t need to implement your own tasks, because there are gradle plugins which already finish writing the tasks for you. You just need to add the relevant plugins as dependencies, and put their configuration blocks here with your own values.

The ideas above should make the build.gradle file pretty easy to understand, because now its functionalities are narrowed down to only manage your plugins and project dependencies.

2. A practical workflow for working with gradle

So now you should have a clear workflow:

You pick up the gradle plugins you want.
You add them as dependencies and apply them, now you get the gradle tasks.
You can configure these plugins by adding their configuration blocks to your build.gradle file.
You then add the dependencies for your project.
You can configure your project information like groupId, archiveBasename, etc.
Happy gradle.

Let’s try set up a kotlin project with gradle. How do we start? Well, from above we now know that we just need to find a plugin which implements kotlin related tasks for us. And, we will use the official kotlin-gradle-plugin.

3. Add plugins

There are two ways to add the dependencies, let’s try the first one.

3.1 Informative way

buildscript {
  repositories {
    mavenCentral()
  }
  dependencies {
    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.2.21"
  }
}

apply plugin: 'kotlin'

Seems lots of things going on here, but in fact, it’s just that easy.

The first one is buildscript, it only controls dependencies for the buildscript process itself, not for the application code. Which means it will add the dependencies for this building session itself, which properly gonna help you to finish some tasks.

And inside it. We want a plugin org.jetbrains.kotlin:kotlin-gradle-plugin as our dependencies. It’s in one of the repositories called mavenCentral. And then you just need to apply them.

If you feel uncomfortable about this, then here is some real news to make you calm. 99% plugin author will give you this full code, you just need to copy and paste. 😀

3.2 Simpler way

The above way applies to the plugin which uses maven central to publish. And some plugins will also use plugin portal and it results in a simplified way.

plugins {
    id "org.jetbrains.kotlin.jvm" version "1.2.21"
}

That’s it, no buildscript and apply. You use the plugins DSL to add plugin dependencies. Much cleaner. But consider it’s still incubating and maybe change in the future, not all plugins are available in this way. But I’m sure it’s the future.

4. Configure the plugin

We have said that you need to copy and paste the configuration block of the plugin in order to customize it to your own needs. And by saying configuration block, I mean something like this:

commandYouWantToUse {
   // Here is your settings
}

And another term to call this is XXX DSL, because it’s a DSL which specific for settings. It will be put in your build.gradle file, just in the body of the file, not inside other blocks, and of course not buildscript {}. How to config? Easy, read their document.

And no matter which plugin you gonna use, their configurations all look identical to the above.

Let’s say that we want to see more information when the compiler is working. We just need to add something like this:

compileKotlin {
    kotlinOptions.verbose = true
}

Just that easy.

5. Add the dependencies of your project

Now we need to add the dependencies of your application code, which you need to add, so when the building phase happens, they will be included. You will see something pretty familiar:

repositories {
    mavenCentral()
}

dependencies {
    compile "org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.2.21"
    testCompile group: 'junit', name: 'junit', version: '4.12'
}

You define where to find the package, and you define the name of the package. They are different from the dependencies above. That dependencies need to reside inside the buildscript {} while this one just sits in the body of gradle. The testCompile command is for the libraries that you will use for the testing phase.

6. Configure the project information

This part is easy, most of the time, it’s just as simple as declare some variables. Let’s say we want to set up the groupId and version for our project. You just declare the following 2 variables:

group 'myProject'
version '1.0-SNAPSHOT'

In terms of what kind of variables you can and need to declare here, you can still find this information in the plugin documentation. That’s very straightforward.

If they need that, they will tell you. And if you need to customize that, you just add. Otherwise, don’t bother.

7. End

That’s it. Hope it helps. And any time you see any configuration block that you don’t know, just google that. It must be either from gradle itself or some plugin. You can check the official gradle document for more configuration block that you could use. Or, to be honest, most of the time, like most of the gradle user, you don’t need, just find that plugin that most people use and adopt that, then you are good to go.

Now move to using build.gradle in Intellij