From 9ec871e57031338b3a94378a7412b0066365e9c5 Mon Sep 17 00:00:00 2001 From: Cedric Beust Date: Mon, 16 Nov 2015 09:37:06 -0800 Subject: [PATCH 1/9] Dokka documentation. --- plug-ins/index.html | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/plug-ins/index.html b/plug-ins/index.html index 49f3bcb..1baae44 100644 --- a/plug-ins/index.html +++ b/plug-ins/index.html @@ -312,6 +312,28 @@ $ ./kobaltw uploadJcenter All artifacts successfully uploaded +

Dokka

+ +

+ Dokka is Kotlin's documentation tool. The Kobalt Dokka plug-in allows you to launch it and configure it as follows: +

+
+    import com.beust.kobalt.plugin.dokka.dokka
+    // ...
+
+    dokka {
+        args("-output", "markdown")
+        linkMapping {
+            dir = "src/main/kotlin"
+            url = "https://github.com/cy6erGn0m/vertx3-lang-kotlin/blob/master/src/main/kotlin"
+            suffix = "#L"
+        }
+    }
+
+

+ You can then generate your documentation by running the dokka task. +

+ From 2ddd3e86cd8a348792492b67ad57d457ba990e65 Mon Sep 17 00:00:00 2001 From: Cedric Beust Date: Mon, 16 Nov 2015 22:48:33 -0800 Subject: [PATCH 2/9] Update dokka doc. --- plug-ins/index.html | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/plug-ins/index.html b/plug-ins/index.html index 1baae44..24d51cc 100644 --- a/plug-ins/index.html +++ b/plug-ins/index.html @@ -322,17 +322,34 @@ $ ./kobaltw uploadJcenter // ... dokka { - args("-output", "markdown") - linkMapping { + outputFormat = "markdown" + sourceLinks { dir = "src/main/kotlin" url = "https://github.com/cy6erGn0m/vertx3-lang-kotlin/blob/master/src/main/kotlin" - suffix = "#L" + urlSuffix = "#L" } }

- You can then generate your documentation by running the dokka task. + You can then generate your documentation by running the dokka task. Here is the full list of configuration parameters allowed:

+
+
samplesDir
+
The list of directories containing sample code (documentation for those directories is not generated but declarations from them can be referenced using the @sample tag).
+
includeDirs
+
The names of directories containing the documentation for the module and individual packages.
+
outputDir
+
The output directory where the documentation is generated.
+
outputFormat
+
The output format: html, markdown, jekyll, + or javadoc.
+
sourceLinks
+
The source link mappings.
+
moduleName
+
The name of the module being documented (used as the root directory of the generated documentation).
+
skip
+
If true, don't generate anything.
+
From cd49baeaab632803b63e64001a0ce27352bdb601 Mon Sep 17 00:00:00 2001 From: Cedric Beust Date: Wed, 18 Nov 2015 00:01:56 -0800 Subject: [PATCH 3/9] Syntax doc. --- documentation/index.html | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/documentation/index.html b/documentation/index.html index ae265a7..c3d9a25 100644 --- a/documentation/index.html +++ b/documentation/index.html @@ -129,6 +129,34 @@ Here are a few noteworthy details about this small build file:
  • The functions kotlinProject and homeDir are supplied by Kobalt and are referred to as "directives" +

    + In terms of syntax, there are basically three different ways to specify values in a build file: +

    +
      +
    • Individual values for primitives (numbers, strings) are a straight equals sign: + 
      +name = "kobalt"
      +
      • + +
    • + Parameters that can receive multiple values are usually captured by function calls, so you use parentheses, as usual in Kotlin: + 
      +compile("dep1", "dep2", "dep2")
      +
      • + +
    • + Complex objects are passed as closures, so you use curly braces to define them: + 
      +dependencies {
+    ...
+}
      +
      • +
    +

    + Remember that a build file is a valid Kotlin source, so you can use function calls instead of literal values, or any other correct Kotlin code in your build file: +

    + 
    +version = readVersion()

    Directives

    From c3363183e23dcb9d417164132ba0d2f6a9b8e210 Mon Sep 17 00:00:00 2001 From: Cedric Beust Date: Mon, 16 Nov 2015 01:35:33 -0800 Subject: [PATCH 4/9] Document variants and BuildConfig. --- plug-ins/index.html | 106 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 101 insertions(+), 5 deletions(-) diff --git a/plug-ins/index.html b/plug-ins/index.html index 24d51cc..b729be9 100644 --- a/plug-ins/index.html +++ b/plug-ins/index.html @@ -9,7 +9,7 @@ - + @@ -69,10 +69,10 @@ val p = javaProject(wrapper) {

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

    -

    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). @@ -92,7 +92,7 @@ A Project has two mandatory attributes: name and The dependencies for your tests -

    Tasks

    +

    Tasks

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

    @@ -106,7 +106,103 @@ Once you have at least one project configured, the plug-in lets you invoke the f
    Clean the project
    -

    Application

    +

    Variants

    +

    + Variants let you configure your project to generate different artifacts compiled from different sources depending on the variant you selected. +

    +
    +

    Note

    + Kobalt's variant system is very similar to Android's build types, so you should already be familiar with these concepts if you have built Android applications. The difference is that Kobalt supports variants in its core, so that all projects (not just Android's) can take advantage of it. +
    + +

    + A variant is made of at least one of the following two components: +

    +
      +
    • The product flavor.
      • +
    • The build type.
      • +
    +

    + Product flavors usually contains different source files and different logic (e.g. a "free version" and a "pro version". Build types lead to different archives (e.g. "debug" and "release", with the "release" version being obfuscated). This effect is achieved by defining identical source files in different directories and then letting Kobalt build the correct one. Each product flavor and build type has a name which translates directory into a source directory. For example: +

    +
    +productFlavor("free") {
+}
+
+buildType("release") {
+}
    +

    + With these variants defined, you can now add source files in the "src/free/java" and "src/release/java" directories (Kotlin is also supported): +

    + 
    +src/free/java/Product.java
+src/release/java/Product.java
    +

    + If you define at least one variant, new tasks get added to your build: +

    + 
    +$ ./kobaltw --tasks
+
+===== java =====
+compileFreeRelease
+compileFreeDebug
+
+===== packaging =====
+assembleFreeRelease
+assembleFreeDebug
    +

    + For example, if you define two flavors, "pro" and "free", and two build types, "debug" and "release", four tasks will be added that combine these: "proDebug", "proRelease", "freeDebug" and "freeRelease". If you assemble any of these, an artifact named after that combination will be created, e.g. "kobalt-0.273-free-debug.jar". +

    + +

    BuildConfig

    +

    + If you defined at least one variant defined, a special file called BuildConfig.java (or + BuildConfig.kt) will be automatically generated. +

    +
    +

    Note

    + You need to define packageName in your project in order for this file to be generated or + Kobalt will fail. +
    +

    + This class contains at least two fields defining the current variant: +

    +
    +class BuildConfig {
+    companion object {
+        val PRODUCT_FLAVOR : String = "pro"
+        val BUILD_TYPE : String = "debug"
+    }
+}
    +

    + You can add your own custom fields to this file by calling the buildConfig directive + inside your + flavor: +

    + 
    +productFlavor("free") {
+    buildConfig {
+        field("aStringField", "String", "\"The free field\"")
+        field("anIntField", "Int", "42")
+    }
+}
    +

    + The generated file will then contain: +

    +
    +class BuildConfig {
+    companion object {
+        val PRODUCT_FLAVOR : String = "free"
+        val BUILD_TYPE : String = "debug"
+        val aStringField : String = "The free field"
+        val anIntField : Int = 42
+    }
+}
    +

    + Take a look at the variants example + project to see an actual example using variants and BuildConfig. +

    +

    Application

    The "application" plug-in lets you run your application directly from kobaltw. You configure it as follows: From 803caaaadd58a437ff02cadab0b0e11a3243db33 Mon Sep 17 00:00:00 2001 From: Cedric Beust Date: Mon, 16 Nov 2015 03:09:31 -0800 Subject: [PATCH 5/9] Rename plugin.xml -> kobalt-plugin.xml. --- plug-in-development/index.html | 8 ++++---- ten-minutes/index.html | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/plug-in-development/index.html b/plug-in-development/index.html index bb88785..43d3014 100644 --- a/plug-in-development/index.html +++ b/plug-in-development/index.html @@ -58,7 +58,7 @@ Kobalt plug-ins are usually made of several parts: