diff --git a/contributing/index.html b/contributing/index.html new file mode 100644 index 0000000..0fef1f3 --- /dev/null +++ b/contributing/index.html @@ -0,0 +1,141 @@ + + + + + Kobalt, by Cedric Beust + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+

Contributing to Kobalt

+

Interested in contributing to Kobalt? This page explains how to configure your development environment.

+ +
+ + +
+ +

Launch configuration

+ +

+ Kobalt's main class is `com.beust.kobalt.MainKt`. Here is a typical launch configuration: +

+

+ +

+ +

+ A few observations: +

+ +

+ +

Auto complete in build files

+

+ It's useful to turn on auto completion for your Build.kt file if you are adding new + elements to the DSL. You can achieve this in two steps. +

+ +

Sync your build file

+

+ This is achieved with the Kobalt / Sync build file menu item. On top of configuring your + IDEA project with the correct dependencies, this will also add the kobalt.jar file to your + classpath. +

+

+ +

+

+ +

+ + +

Compile your build file

+

+ Next, mark the directory that contains your build file as a "Source directory": +

+

+ +

+
+

Alternate source directory for Build.kt

+ The default location for Build.kt is in the root directory of your project but + you can also put it in kobalt/src/Build.kt and then mark that directory as + a source directory. +
+ +

+ You can now use all the IDEA features on your build file: +

+

+ +

+ +
+ + +
+
+ + + + + + + + + + + + + diff --git a/documentation/index.html b/documentation/index.html index ae265a7..ee8ff5d 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: +

    + +

    + 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

    @@ -143,6 +171,7 @@ val kobalt = kotlinProject { assemble { jar { + } } } @@ -436,132 +465,42 @@ Now, all you need to do is to upload your package: ./kobaltw uploadJcenter -

    Writing a plug-in

    - -A good starting point to write a plug-in is the kobalt-line-count project, which shows a minimalistic plug-in. - -

    Building

    - -You only need to do two things to build a Kobalt plug-in: - -

    1. Add Kobalt as a dependency:

    - +

    Profiles

    +

    + Profiles allow you to run altered versions of your build file by using command + line parameters. +

    +

    + You start by defining boolean values initialized to false in your build file: +

    +
    +  val experimental = false
+  val premium = false
+
    +

    + Then you use this variable wherever you need it in your build file: +

    +
    +  val p = javaProject {
+      name = if (experimental) "project-exp" else "project"
+      version = "1.3"
+
    +

    + Finally, you invoke ./kobaltw with the --profiles parameter followed by the profiles you want to activate, separated by a comma: +

    +
    +  ./kobaltw -profiles experimental,premium assemble
+
    +

    + Keep in mind that since your build file is a real Kotlin source file, + you can use these profile variables pretty much anywhere, e.g.: +

     dependencies {
-    compile("com.beust:kobalt:0.61")
-}
-
    - -

    2. Declare the main class of your plug-in in the Jar file's manifest:

    - -
    -    packaging {
-        jar {
-            manifest {
-                attributes("Kobalt-Plugin-Class", "com.beust.kobalt.example.ExamplePlugin")
-            }
-        }
-
    - -

    Implementing

    - -A plug-in typically has three components: - - - -

    BasePlugin

    - -

    -The main class of your plugin extends BasePlugin and implements its apply() method and name variable: -

    - -
    -public class ExamplePlugin : BasePlugin() {
-    override val name = "kobalt-example-plugin"
-
-    override fun apply(project: Project, context: KobaltContext) {
-        println("Applying plugin ${name} with project ${project}")
-    }
-}
-
    - -

    Plugin tasks

    - -

    -Next, you can declare tasks with the @Task annotation: -

    - -
    -@Task(name = "coverage", description = "Run coverage", runAfter = arrayOf("compile"))
-public fun coverage(project: Project): TaskResult {
-    println("Running the coverage on project $project")
-    return TaskResult()
-}
-
    - - - -

    Directives

    - -

    -Finally, you need to define functions that can be used from the build file (directives). You are encouraged to use the Kotlin DSL approach to expose these functions so that the build file syntax can remain consistent. Typically, these functions will update data that your tasks can then use to do their job. -

    - -

    - -These can be either straight functions or extension functions. For example, here is the kotlinProject directive: - -

    -@Directive
-public fun kotlinProject(init: KotlinProject.() -> Unit): KotlinProject {
-    val result = KotlinProject()
-    result.init()
-    return result
-}
-
    - -

    -This function returns a KotlinProject and the user can then override variables or invoke methods from this class in their build file: -

    - -
    -val kobalt = kotlinProject {
-    name = "kobalt"
-    group = "com.beust"
-...
-
    - -

    -Using an extension function to define a directive allows you to add new functions to Kobalt classes. For example, currently, a project can have "dependencies" and "dependenciesTest". For a coverage plug-in, we would want to add a "dependenciesCoverage" section, which can be easily done by defining an extension function on Project: -

    - - -
    -@Directive
-public fun Project.dependenciesCoverage(ini: Dependencies.() -> Unit) : Dependencies {
-    val result = Dependencies()
-    result.init()
-    return result
-}
-
    - -

    -And we can now use: -

    - -
    -val p = kotlinProject {
-    dependenciesCoverage("com.example:foo:0.1")
-}
+    if (experimental)
+        "com.squareup.okhttp:okhttp:2.4.0"
+    else
+        "com.squareup.okhttp:okhttp:2.5.0",

    Sources and license

    diff --git a/js/kobalt.js b/js/kobalt.js index e6b6c95..1e4919f 100644 --- a/js/kobalt.js +++ b/js/kobalt.js @@ -28,6 +28,10 @@ var content = [ { url: "../ten-minutes/index.html", title: "Ten minutes" + }, + { + url: "../contributing/index.html", + title: "Contributing" } ]; diff --git a/pics/auto-complete.png b/pics/auto-complete.png new file mode 100644 index 0000000..566ea55 Binary files /dev/null and b/pics/auto-complete.png differ diff --git a/pics/kobalt-jar.png b/pics/kobalt-jar.png new file mode 100644 index 0000000..41e15b8 Binary files /dev/null and b/pics/kobalt-jar.png differ diff --git a/pics/launch-configuration.png b/pics/launch-configuration.png new file mode 100644 index 0000000..a30a495 Binary files /dev/null and b/pics/launch-configuration.png differ diff --git a/pics/menu-sync.png b/pics/menu-sync.png new file mode 100644 index 0000000..e40707f Binary files /dev/null and b/pics/menu-sync.png differ diff --git a/pics/source-root.png b/pics/source-root.png new file mode 100644 index 0000000..a7c7c18 Binary files /dev/null and b/pics/source-root.png differ diff --git a/plug-in-development/index.html b/plug-in-development/index.html index 6c6a137..0c9660a 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:
    • diff --git a/ten-minutes/index.html b/ten-minutes/index.html index 2a6cd79..4809e49 100644 --- a/ten-minutes/index.html +++ b/ten-minutes/index.html @@ -84,7 +84,7 @@ val project = kotlinProject {

    - Next, we need to create our plugin.xml file in the src/main/resources/META-INF directory. + Next, we need to create our kobalt-plugin.xml file in the src/main/resources/META-INF directory. Once there, it will be automatically copied in the right place in our jar file: