Gradle Kotlin DSL 1.0: Basic App Build

Contents:

• Kotlin DSL list of other pages
• Build Basics in Gradle
  • Plugins
  • Dependencies and Artifact Repositories
• A Simple Practical Example
• Varying the Source Locations: SourceSets
• Application
• Testing – JUnit
• local jars as dependencies

Build Basics with Gradle.

The build file prepares a configuration for gradle and for any optional extra build tools.  The basic configuration for a build requires:

• what tools will the build need?
• where are the source files?
• what libraries are needed?
• where are artifact repositories (holding the libraries)?

Consider the simplest case for each of these basics:

• What tools will be used for the build? A:Kotlin – the jvm version
• Where are the source files? A: ‘src/main/kotlin’
• What libraries are needed? A: the kotlin std library
• Where are the artifact repositories for the libs? A: jcenter

Providing only these for a configuration is the simplest case, and here is a build.gradle.kts file for this simplest case.

plugins { kotlin("jvm") version "1.2.60" }
dependencies { compile(kotlin("stdlib")) }
repositories { jcenter() }

The tools are added through ‘plugins’, in this case the kotlin(“jvm”) plugin is all that is needed.

If the source files are in src/main/kotlin, then as this is the default, no instructions on source files are needed (how to add more source locations is covered below).

The dependency is the standard kotlin compile library, which is in the artifcact repository specificed by ‘jcenter()’.

Plugins.

The main plugin for kotlin requires what type of kotlin as a parameter, and in the current version of Gradle Kotlin DSL (1.0 rc) requires a modifier specifying the version of the plugin (currently  1.2.60).

Dependences and Artifact Repositories.

Dependencies are libraries, code, images… any component of any type that is part of a program distribution is a dependency. The most common dependencies are library functions and classes.

To build a program, the build tool needs to know to find the depenencies, and the normal system is to have the dependencies held in maven style artifact repositories.

This means in addition to the what the depnencies are, it is also necessary to list the repositories to search to find each dependency.

A simple practical Example

• Step 1 Install gradle
  • if you don’t already have gradle installed, follow on online instructions to install and verify installation
• Step 2 – build simple example in Intellij
  • Create a new kotlin jvm project in Idea
    • File/New/Project/Kotlin/Kotlin JVM
  • Note the blue ‘src’ folder in the project (blue indicates source files)
  • Add a kotlin file with a main method to the src folder
    • right click on folder, then New/Koltin file/class
    • add a main function with a print or something
      • fun  main(args: Array){
    • check for the green triangle (Play symbol) next in the gutter to the left of ‘fun’
      • argument must of an Array String for the symbol to appear
    • click play to get the program to run.
• Step 3 – add build.gradle.kts
  • add build.gradle.kts to the project root
    • use New/File .. not New/Gradle_Kotlin DSL build script
      • at the time of writing the DSL build script does not work
    • add the text of the 3 line example in build basics above
    • exit and restart the project
    • select ‘import gradle project’
      • the import may bring up an options window
        • select no itck boxes,  ‘use local gradle’
        • other settings should be able to left at default
  • the green play symbol will disappear as the project does not match the new settings
    • add a ‘main’ folder to src, and a ‘kotlin’ folder to main
    • move the sample kotlin file to the kotlin file
  • The new configuration should now work!
    • find the gradle tab on the right edge of the intellij window
      • open the gradle tab
    • if the gradle tab cannot be located..
      • use the main menu :  view/tool windows/gradle
      • use the expand triangles to locate tasks/build/build click build
• Congratulations – you are on the road to being a gradle master

Gradle Settings.

Auto import can be annoying.

Create directories for empty roots is best for the more experienced.

These settings do work for the example.

Varying the source locations

In the example above, the source file must be moved from ‘src’ to ‘src/main/kotlin’.  There is some sound logic to the move, as some sub folders under ‘src’ make sense, particularly to allow for both ‘main’ and ‘test’.

In place of moving the file to suit gradle defaults, you can move add ‘src’ to be a source file location.

sourceSets["main"].java {
    // srcDir{"src/main/kotlin") - this is the default, always set!
    srcDir("src")
}

Why sourceSets[“main”].java and not sourceSets[“main”].kotlin? Maybe it will change in future, but for this example creating for the jvm [“main”].java is for the main file location. [“test”].java for the test files locations for jvm apps.

Reflect

Beyond the most basic app, the reflect repository can simply added.

dependencies {
    compile(kotlin("stdlib"))
    compile(kotlin("reflect"))

Application.

The instructions so far set up building and running in Intellij, but the easy way to package up an application for distribution is the application plugin. Simply add application (as a name, no quotes) as a line in the plugins block, then add an application block to set the main class name, which will be the name of the file containing main, prefixed by the package name (if any) for that file, with the ‘.kt’ converted to “Kt”, and the first leftter of the name in caps. So “testapp.kt” would become “TestappKt”, or “sample.TestappKt” if there is a package of “sample”. The convention is to name source files with the same rules a classes, so the first letter of each world would normally be Capitalised.

application{
   mainClassName = "TestAppKt"
}

The build the then generates distributions in the ‘build/distributions’ folder. I a ‘.jar’ file not just of the code in the project, but packaged with all libraries is required (known as ‘fat jar‘ or ‘uber jar’ , then add the following lines to add the shadow plugin. A ‘-all.jar‘ will then also be built, as well as the ‘.jar‘.

plugins{
    id("com.github.johnrengelman.shadow") version "2.0.4"
}

buildscript{
    dependencies{
    val shadow = "2.0.4"
    classpath( "com.github.jengelman.gradle.plugins:shadow:$shadow")
    }
}

Testing – JUnit.

Here is the code to add, here are the repositories I have been using, together with the configuration of test.

repositories{
    val junit = "5.2.0"
    compile("org.junit.jupiter:junit-jupiter-api:$junit")
    compile("org.junit.jupiter:junit-jupiter-params:$junit")
    runtime("org.junit.jupiter:junit-jupiter-engine:$junit")
    val kluent ="1.4"
    testImplementation("org.amshove.kluent:kluent:$kluent")
}

tasks.withType {
    useJUnitPlatform()
}

Here is also an alternate combination, which should be cleaner and simpler, but I am still checking some problems at this time.

Note, both these versions are also providing ‘kluent’, which you may not use, but it can read well.

repositories{
 compile(kotlin("stdlib"))
 compile(kotlin("reflect"))

 compile(kotlin("test"))
 compile(kotlin("test-junit"))

 val kluent ="1.4"
 testImplementation("org.amshove.kluent:kluent:$kluent")
}

tasks.withType {
    useJUnitPlatform()
}

Local Jar Dependencies

The jar file (no, need a complete application, just the jar) can provide code for another project by simply adding the jar as a dependency.

dependencies{
    compile(files("../OtherProject/lib/App.jar","lib/otherJar.jar"))
}

The path uses ‘/’ characters, even on windows, starts from the project root and can have ‘..’ (parent folder) elements to step ‘up’ out of the project.