Kobalt, by Cedric Beust

Java and Kotlin

The Java and Kotlin plug-ins are extremely similar, the only difference is that you configure a Java project with the javaProject directive and a Kotlin project with kotlinProject:

val p = javaProject(wrapper) {
  name = "kobalt"
  group = "com.beust"
  artifactId = name
  version = "0.1"
}

Both these directives allow you to consider an object of type Project.

Project

A Project has two mandatory attributes: name and version. If you are planning to deploy your project to a Maven repository, you also have to specify its group (e.g. com.beust) and artifactId (e.g. kobalt).

Additionally, a Project lets you specify the following parameters:

sourceDirectories: The location of your source files
sourceDirectoriesTest: The location of your test source files
dependencies: The dependencies for your project
dependenciesTest: The dependencies for your tests

Tasks

Once you have at least one project configured, the plug-in lets you invoke the following tasks:

compile: Compile the project
compileTest: Compile the tests
test: Run the tests
clean: Clean the project

Packaging

The Packaging plug-in lets you generate various archives for your project: jar, war and zip files, each of them defining a directive by the same name inside the assemble directive:

val packaging = assemble(kobalt) {
  jar {}
}

If you don't specify a name for your archive, a default one will be used that contains your project name, version and the corresponding suffix, e.g. kobalt-1.1.jar or sec-0.2.war.

zip

All these archives are zip files, so the zip archive is at the top of the hierarchy and jar and war inherit all its attributes, which include name, include and exclude.

include and exclude

All archives let you include and exclude files.

include has two different forms:

val a = assemble(kobalt) {
  zip {
      include("kobaltw", "README")
      include(from("doc/"),
              to("html/"),
              glob("**html"))
  }
}

The first form, with just one parameter, simply copies the file from your directory into the archive, preserving its path. The second form has three parameters which allow you to move the file to a different path into your archive. Note the use of the from, to and glob directives, which are necessary to disambiguate the call.

jar

A jar is like a zip with two additional available parameters:

fatJar: If true, all the dependencies and their dependencies will be included in the jar file
manifest: Specify attributes to add to the manifest

Here is how you generate an executable jar file:

val a = assemble(kobalt) {
  jar {
      fatJar = true
      manifest {
          attributes("Main-Class", "com.beust.kobalt.KobaltPackage")
      }
  }
}

war

The war directive generates a war file suitable to be deployed into a servlet container.

mavenJars

The mavenJars directive generates several jar files (binary, source, javadoc) which are required by Maven repositories. It's basically a shortcut that saves you the trouble from having to assemble these jar files manually in your build file. It allows you to specify Manifest attributes, just like the jar directive.

Publishing

The Publishing plug-in lets you upload files to JCenter. These files can be either generic ones (e.g. a zip file, a README, etc...) or a Maven-compatible form of your project.

Before you can upload, you need to create a file local.properties in the root directory of your project with the following keys:

bintray.user=...
bintray.apikey=...

The values for the user and apikey keys can be found in your bintray profile, as described here. Add this file to your .gitignore file and make sure you never upload it to your source control.

Before you can upload, you also need to create the package in bintray, as explained here. Once this is done, you are ready to do your first upload.

You define what to upload with the jcenter directive:

val jc = jcenter(kobalt) {
  publish = true
  file("${kobalt.buildDirectory}/libs/${kobalt.name}-${kobalt.version}.zip",
       "${kobalt.name}/${kobalt.version}/${kobalt.name}-${kobalt.version}.zip")
}

The jcenter directive accepts the following parameters:

publish: If true, the uploaded file will be published in your personal space (e.g. https://dl.bintray.com/cbeust/maven). Once the file is uploaded there, it can be automatically synchronized to JCenter by linking your project to JCenter on the bintray web site. By default, files are not published.
file: The first parameter is the file you want to upload and the second one is the path where it will be uploaded to.

$ ./kobaltw uploadJcenter
...
========== kobalt-line-count:uploadJcenter
  kobalt-line-count: Found 2 artifacts to upload
  All artifacts successfully uploaded

Plug-ins