diff --git a/contributing/index.html b/contributing/index.html index 0f8e336..ca06646 100644 --- a/contributing/index.html +++ b/contributing/index.html @@ -37,7 +37,7 @@
-

License, Source code & Issues

+

License, Source code & Issues

Kobalt is licensed under Apache 2.0

@@ -53,8 +53,33 @@
  • Join kobalt-dev, the mailing-list for Kobalt developers. This mailing-list is for people interested in writing code for Kobalt, either the core, or writing plug-ins, or just to follow various technical discussions about Kobalt's internals.
    • -

    Launch configuration

    -

    Here is how to configure your development environment.

    +

    Configuring IDEA

    +

    + Working on the Kobalt code base with Intellij IDEA is very easy. +

    +

    Edit kobalt.version

    +

    + First of all, edit the file src/main/resources/kobalt.properties and set it + to a nonexistent version. For example, if the current version is 0.399, + set it to 0.400. +

    + 
    +                    kobalt.version=0.400
+
    +

    + When you launch Kobalt from IDEA with a nonexistent version, Kobalt will show a message saying + that it couldn't locate that version and instead, it will use the classes generated by IDEA. This + way, you will always be running the files that you just modified with IDEA. On start up, + Kobalt will display a message looking like: +

    + 
    +Couldn't find .../kobalt-0.400.jar, using ...
+
    +

    + Note that at the moment, Kobalt expects to be located in $HOME/kotlin/kobalt. +

    +

    Launch configuration

    +

    Next, create a launch configuration in IDEA.

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

    diff --git a/documentation/index.html b/documentation/index.html index 29d0bc3..4b349d5 100644 --- a/documentation/index.html +++ b/documentation/index.html @@ -68,9 +68,8 @@ The build file is located in kobalt/src/Built.kt and it is a valid 
     import com.beust.kobalt.*
-import com.beust.kobalt.plugin.kotlin.kotlinProject
 
-val kobalt = kotlinProject {
+val kobalt = project {
     name = "kobalt"
     group = "com.beust"
     artifactId = name
@@ -84,7 +83,7 @@ Here are a few noteworthy details about this small build file:
 
 
           
    
@@ -124,7 +123,7 @@ Now that we have declared a project, we can use it to configure additional steps
 
     import com.beust.kobalt.plugin.packaging.assemble
 
-val kobalt = kotlinProject {
+val kobalt = project {
     // ...
     assemble {
         jar {
@@ -192,6 +191,19 @@ fun taskCreateVersion(project: Project) : TaskResult {
   This tasks takes a template file and replaces all occurrences of the string "@version@" with the actual version of the project. Obviously, this task is very specific to TestNG's own build and it wasn't worth writing a plug-in ftor this. Note the attributes runBefore and runAfter, which specify when this task will run. You can find more information about tasks in the plug-in development section.
 
    
 
+
    Build file classpath
    
+
    
+  If you are writing code or an inline task in your build file that requires additional libraries,
+  you can specify these dependencies with the buildFileClasspath() directive, which accepts a list
+  of dependencies in parameters. Each of these dependencies will then be added to the classpath when
+  your build file is compiled and run:
+
    
+
    +// Build.kt
+val bfc = buildFileClasspath("org.testng:testng:6.9.11")
+val t = org.testng.TestNG()  // now legal
+
    
+
 
    Dependencies
    
 
 
    
@@ -217,56 +229,189 @@ dependencies {
 }
 
    
 
-          
    
-              There are various kinds of dependencies:
-          
    
-          
    
-              
    compile
    
-              
    Used to compile your project.
    
-              
    runtime
    
-              
    Not used at compile time but passed to the JVM to run your application.
    
-              
    provided
    
-              
    Used at compile time but not used to run your application.
    
-              
    exclude
    
-              
    Exclude the given dependencies from the classpath. You can either
-                  specify a versioned id (e.g. "groupId:artifactId:version") or a versionless one
-                  ("groupId:artifactId:").
    
-          
    
+
    Dependency versions
    
+
    
+  Kobalt lets you specify Maven coordinates in one line, such as "org.testng:testng:6.9.10". Note that Kobalt uses the Maven Coordinates defined in the Maven specification, which are a little bit different from the ones that Gradle uses.
+
    
+
    
+  The standard format for such coordinates, as explained in the link above, is:
+
    
+
    +groupId:artifactId:packaging:classifier:version
    
+
    
+  packaging (e.g. "jar") and classifier (usually an arbitrary name) are optional and can be omitted. If version
+  is omitted, Kobalt will resolve the artifact to its latest version from all the specified repos.
+  Most of the time, you will only specify groupId, artifactId and version, but if you ever need to specify additional components such as packaging (sometimes referred to as "extension") or classifier,
+  please take note that these should appear before the version number.
+
    
+
    
+  Here are a few examples of valid Maven coordinates:
+
    
+
    +# No version, resolves to the latest
+org.testng:testng:
 
-          
    Settings
    
+# Specifies an extension and a qualifier
+com.badlogicgames.gdx:gdx-platform:jar:natives-desktop:1.9.2
    
+
+
    Dependency types
    
+
+
    
+  There are various kinds of dependencies:
+
    
+
    
+  
    compile
    
+  
    Used to compile your project.
    
+  
    runtime
    
+  
    Not used at compile time but passed to the JVM to run your application.
    
+  
    provided
    
+  
    Used at compile time but not used to run your application.
    
+  
    exclude
    
+  
    Exclude the given dependencies from the classpath. You can either
+      specify a versioned id (e.g. "groupId:artifactId:version") or a versionless one
+      ("groupId:artifactId:").
    
+    
    native
    
+    
    Used to define native dependencies.
    
+
    
+
+
    Native dependencies
    
+
    
+  Native dependencies will only be used when you invoke the run task on your project:
+
    
+
    +dependencies {
+    native("org.lwjgl.lwjgl:lwjgl-platform:jar:natives-windows:2.9.3",
+           "org.lwjgl.lwjgl:lwjgl-platform:jar:natives-linux:2.9.3",
+           "org.lwjgl.lwjgl:lwjgl-platform:jar:natives-osx:2.9.3"
+        )
+    }
    
+
    Settings
    
+
    
+  You can define settings that will apply to all your Kobalt builds by creating
+  the file ~/.config/kobalt/settings.xml:
+
    
+
+
    +<kobalt-settings>
+    <local-repo>/Users/beust/my-kobalt-repo</local-repo>
+    <default-repos>
+        <repo>http://jcenter.com</repo>
+        <repo>http://example.com</repo>
+    </default-repos>
+</kobalt-settings>
    
+
    
+  Here is a list of the parameters you can configure:
+
    
+
+    +        +        +        +    
+    
+        
+            
+            
+            
+        
+    
+
+    
+        
+        
+        
+    
+    
+        
+        
+        
+    
+    
+        
+        
+        
+    
+    
+        
+        
+        
+    
+
    




    NameDefaultDescription
    default-reposDefault reposList of repos overriding the default ones that Kobalt uses.
    kobalt-compiler-version1.0.0The version of the Kotlin compiler that Kobalt uses.
    kobalt-compiler-repoNoneThe Maven repository where to find the compiler. By default, the compiler is looked up in the default repos (JCenter, Maven, ...).
    local-repo~/.kobalt/repositoryWhere Kobalt stores all the downloaded dependencies.
    
+
+
    Templates
    
+
    
+  Templates are invoked with the --init parameter and typically used when you are creating
+    a new project and you want Kobalt to generate a few files to get you started. Plug-ins can provide multiple
+    templates and you can invoke as many as you need to get your project started. You can get a list of available
+    templates with the --listTemplates parameter:
+
    
+
    +$ kobaltw --listTemplates
+Available templates
+  Plug-in: Kobalt
+    "java"              Generate a simple Java project
+    "kotlin"            Generate a simple Kotlin project
+    "kobaltPlugin"      Generate a sample Kobalt plug-in project
    
+
    
+    You can then invoke any of these templates with --init:
+    
    +$ kobaltw --init kobaltPlugin
+Build this project with `./kobaltw assemble`
    
+
    
+    Kobalt just generated a full project that will create a simple Kobalt plug-in. This plug-in adds
+    a simple task to Kobalt, so let's build it and test it:
+
    
+
    +$ ./kobaltw assemble
+----- kobalt-line-count:compile
+----- kobalt-line-count:assemble
+Created .\kobaltBuild\libs\kobalt-line-count-0.18.jar
+Created .\kobaltBuild\libs\kobalt-line-count-0.18-sources.jar
+Created .\kobaltBuild\libs\kobalt-line-count-0.18-javadoc.jar
+Wrote .\kobaltBuild\libs\kobalt-line-count-0.18.pom
+BUILD SUCCESSFUL (5 seconds)
    
+
    
+    We can test this plug-in with another useful command line parameter: --pluginJarFiles. You give this parameter a comma-separated list of jar files, each of which is expected to be a Kobalt plug-in. Let's invoke
+    Kobalt with it and ask for a list of available tasks (some of the output was elided):
+
    
+
    +$ ./kobaltw --pluginJarFiles kobaltBuild/libs/kobalt-line-count-0.18.jar --tasks
+...
+  ===== kobalt-line-count =====
+    dynamicTask         Dynamic task
+    lineCount           Count the lines
+...
+
    
           
    
-              You can create settings that will apply to all your Kobalt builds by creating
-              a file in ~/kobalt/settings.xml:
+              Kobalt loaded this plug-in and added the tasks that it provides. The parameter
+              --pluginJarFiles is mostly targeted at Kobalt plug-in developers so you can test
+              your plug-ins on your local file system without having to upload them to a Maven repo. More commonly,
+              you will run templates from plug-ins published in a Maven repository, and for this,
+              you use the --plugins parameter. For example, let's see what templates the
+              Android Kobalt plug-in offers:
           
    
           
    -<kobalt-settings>
-    <localRepo>/Users/beust/my-kobalt-repo</localRepo>
-</kobalt-settings>
-          
    
-          
    
-              Here is a list of the parameters you can configure:
-          
    
-          
-              -                  -                  -                  -              
-              
-                  
-                      
-                      
-                      
-                  
-              
-              
-                  
-                  
-                  
-              
-          
    




    NameDefaultDescription
    localRepo~/.kobalt/repositoryWhere Kobalt stores all the downloaded dependencies.
    
+$ ./kobaltw --plugins com.beust:kobalt-android: --listTemplates
+Available templates
+  Plug-in: Kobalt
+    "java"              Generates a simple Java project
+    "kotlin"            Generates a simple Kotlin project
+    "kobaltPlugin"      Generate a sample Kobalt plug-in project
+  Plug-in: Android
+    "androidJava"       Generate a simple Android Java project
+    "androidKotlin"     Generate a simple Android Kotlin project
    +

    +We see the same plug-ins we just reviewed and a new one provided by the Android plug-in called +"androidJava". The --plugins parameter expects a comma-separated list of plug-in +id's and it acts as if you had specified these Maven id's in your Build.kt file. +The reason why this parameter is useful is that typically, when you run a template, you don't +have a build file yet since you are starting a project from scratch. +

    +

    +For a more in-depth description of templates, please refer to this article. +

    -

    Maven repos

    +

    Maven repos

    Unauthenticated repos

    Kobalt already knows the location of the most popular Maven repos (Maven Central, JCenter, JBoss) but you can add repos with the repos() directive: @@ -374,8 +519,8 @@ You can specify more than one project in a build file, simply by declaring them: 

    -val p1 = javaProject { ... }
-val p2 = kotlinProject { ... }
+val p1 = project { ... }
+val p2 = project { ... }

    @@ -383,7 +528,7 @@ If some of your projects need to be built in a certain order, you can specify de 

    -val p2 = kotlinProject(p1) { ... }
+val p2 = project(p1) { ... }

    @@ -408,8 +553,8 @@ Here are the options that you can pass to ./kobaltw: - - + + @@ -432,9 +577,9 @@ Here are the options that you can pass to ./kobaltw: - + - td> + - - - - + + + + + + + + + + + @@ -466,6 +618,28 @@ New versions found: + + + + + + + + + + + + + + + + + + + + + @@ -473,23 +647,59 @@ New versions found: - - - - - - - - - - - - - - + + + + + + + + + + + + + +
    Use this option if you are trying to build a project whose Build.kt is not in kobalt/src.
    --checkVersions--checkVersions Booleanfalsefalse Display all the new versions of your dependencies. This option looks at all the dependencies found in your build file and then contacts all the Maven repositories in order to find out if any of these repos contains a newer version. If any are found, they are displayed: 
    @@ -454,10 +599,17 @@ New versions found:
    --initBooleanfalseInitialize a project for Kobalt.This option will create a build file in the current directory (unless one already exists) and will install the Kobalt wrapper.Comma-separated strings of template names.nullInitialize a project for Kobalt with the given templates.The parameter to this argument is a list of template names separated by commas, e.g. "java,myProject". Each template will be invoked in order so they can generate their files.
    --listTemplatesN/AList all the templates available.Templates displayed by this command can then be passed as an argument to the --init parameter.
    --logSpecify the log level. The default level is 1. Level 0 will quiet everything and 2 and 3 will display increasingly verbose output.
    --noIncrementalBooleanfalseTurn off incremental builds.If this flag is specified, Kobalt will run all the tasks, even those that are incremental and would have + been skipped.
    --pluginsComma-separated list of plugin id'sSpecify the plug-ins to load.This is similar to specifying these plug-in id's in a build file except that no build file is needed.
    --pluginJarFilesComma-separated list of plugin jar filesSpecify the plug-ins to load.This is similar to specifying these plug-in id's in a build file except that no build file is needed.
    --resolve Maven id
    (e.g. "com.beust:kobalt:0.228")    		Display information about the given id. Display which repo this artifact can be found in and the whole graph of its dependencies.
    --tasksBooleanfalseList the tasks available.Note that the available tasks will vary depending on which projects are in your build file.
    --updateBooleanfalseUpdate Kobalt to the latest version available.Use this flag if Kobalt just notified you that a new version is available and you want to update. Another way of doing this is to edit kobalt/wrapper/kobalt-wrapper.properties manually.
    --tasksBooleanfalseList the tasks available.Note that the available tasks will vary depending on which projects are in your build file.
    --updateBooleanfalseUpdate Kobalt to the latest version available.Use this flag if Kobalt just notified you that a new version is available and you want to update. Another way of doing this is to edit kobalt/wrapper/kobalt-wrapper.properties manually.
    +

    Testing

    +

    + Kobalt automatically detects how to run your tests based on the test dependencies that you declared: +

    +
    +dependenciesTest {
+    compile("org.testng:testng:6.9.9")
+}
    +

    + By default, Kobalt supports TestNG, JUnit and Spek. You can also configure how your tests run + with the test{} directive: +

    +
    +test {
+    args("-excludegroups", "broken", "src/test/resources/testng.xml")
+}
    +

    + The full list of configuration parameters can be found in the TestConfig class. +

    +

    + Additionally, you can define multiple test configurations, each with a different name. Each + configuration will create an additional task named "test" followed by the name of + that configuration. For example: +

    +
    +test {
+    args("-excludegroups", "broken", "src/test/resources/testng.xml")
+}
 
+test {
+    name = "All"
+    args("src/test/resources/testng.xml")
+}
    +

    + The first configuration has no name, so it will be launched with the task "test", + while the second one can be run with the task "testAll". +

    Publishing

    @@ -502,7 +712,7 @@ First of all, make sure you specified the group, artifactId and version of your 

    -val kobalt = kotlinProject {
+val kobalt = project {
     group = "com.beust"
     artifactId = "kobalt"
     version = "0.72"
@@ -532,7 +742,7 @@ Now, all you need to do is to upload your package:
 
    
 
 
    -./kobaltw uploadJcenter
+./kobaltw uploadBintray
 
    
 
 
    Profiles
    
@@ -551,7 +761,7 @@ Now, all you need to do is to upload your package:
   Then you use this variable wherever you need it in your build file:
 
    
 
    -  val p = javaProject {
+  val p = project {
       name = if (experimental) "project-exp" else "project"
       version = "1.3"
 
    
diff --git a/getting-started/index.html b/getting-started/index.html
index f5f6e6f..cdd797f 100644
--- a/getting-started/index.html
+++ b/getting-started/index.html
@@ -40,97 +40,109 @@
             
             
    
-                
    1. Download Kobalt
    
+                
    1. Install Kobalt
    
+                
    With HomeBrew
    
                 
    
-                Download the zip file then unzip it in a location we'll call KOBALT_HOME:
-                
    
+                    If you are on MacOS and have brew installed:
 
    -cd $KOBALT_HOME
+$ brew install kobalt
+$ which kobaltw
+/usr/local/bin/kobaltw
    
+
    
+
    Manually
    
+
    
+Download the zip file, unzip it and add the bin directory to your $PATH variable so that you can invoke the command kobaltw:
+
    
+
    +cd yourLocation
 unzip kobalt-xxx.zip
+cd kobalt-xxx
+export PATH=$PWD/bin:$PATH
 
    
-                
    
-                    Note: Kobalt doesn't need any environment variable to run, the environment variable used above
-                    is only here for clarity.
-                
    
-                
    2. Initialize your project
    
-                
    
-                Change to your project directory and call the kobaltw command with --init:
-                
    
+
    2. Initialize your project
    
+
    
+Change to your project directory and call the kobaltw command with --init:
+
    
 
     cd ~/java/project
-$KOBALT_HOME/kobaltw --init
-
    
-                
    
-                This command will do two things:
-                
    
-                
      
-                    
    1. Create a default kobalt/src/Build.kt file based on what was found in your project.
-                        
    2. Install the Kobalt Wrapper in your current directory (a script called kobaltw) and a few additional files in the kobalt/wrapper directory. From now on, you can just use ./kobaltw to build and you can ignore $KOBALT_HOME.
-                        
    
-                        
    
-                        You can now attempt to build your project with Kobalt:
-                        
    
+kobaltw --init java
    +to initialize a Java project, or 
    -./kobaltw assemble
-
    - If your project follows a regular build structure (e.g. Maven's hierarchy), this should compile your file and create a .jar file. If not, you will have to make a few edits to your Build.kt. - As of this writing, Kobalt supports Java and Kotlin projects. - -

    3. Edit kobalt/src/Build.kt

    +cd ~/java/project +kobaltw --init kotlin +

    +to initialize a Kotlin project. +

    +
    +

    Note

    - Here is the Build.kt for the Wasabi HTTP framework: + Kobalt supports projects with both Kotlin and Java sources. For such projects, + use either java or kotlin as the --init argument and refer to the mixed projects documentation for more details. +
    +

    +This command will do two things: +

    +
      +
    1. Create a default kobalt/src/Build.kt file based on what was found in your project.
      2. +
    2. Install the Kobalt Wrapper in your current directory (a script called kobaltw) and a few additional files in the kobalt/wrapper directory.
      3. +
    +

    +From now on, you can just use ./kobaltw to build and you can ignore the kobaltw on your path, which is only useful to install Kobalt on new projects. Since you will now build each project with its own ./kobaltw command, they will use their own version of Kobalt. +

    +

    3. Edit kobalt/src/Build.kt

    + +

    + If your project uses a standard folder structure, you can skip this section and try to build your project directly. +

    +

    The build file generated by default might need some editing before you can build your project, so take a look at it and adjust whatever is necessary (e.g. package name, version, etc...)

    +

    +Here is the Build.kt for the JCommander project: +

     import com.beust.kobalt.*
-import com.beust.kobalt.plugin.packaging.assemble
-import com.beust.kobalt.plugin.kotlin.*
+import com.beust.kobalt.plugin.java.*
+import com.beust.kobalt.plugin.packaging.*
+import com.beust.kobalt.plugin.publish.*
 
-val kotlinVersion = "1.0.0-beta-4583"
-
-val p = kotlinProject {
-
-    name = "wasabi"
-    group = "com.example"
+val jcommander = project {
+    name = "jcommander"
+    group = "com.beust"
     artifactId = name
-    version = "0.1"
+    version = "1.54"
 
-    // Tell Kobalt to also search here for dependencies
-    val repos = repos("http://oss.sonatype.org/content/repositories/snapshots") 
-
-    dependencies {
-        compile("org.jetbrains.kotlin:kotlin-stdlib:" + kotlinVersion,
-            "org.jetbrains.kotlin:kotlin-reflect:" + kotlinVersion,
-
-            "io.netty:netty-all:4.0.31.Final",
-            "commons-codec:commons-codec:1.6",
-            "commons-logging:commons-logging:1.1.1",
-            "joda-time:joda-time:2.3")
-    }
-
-    // Test dependencies
     dependenciesTest {
-        compile("junit:junit:4.9",
-            "org.mockito:mockito-all:1.9.5",
-            "org.apache.httpcomponents:httpclient:4.5.1")
+        compile("org.testng:testng:")
     }
 
-    // Tell kobalt to produce a fat jar and also the artifacts required for Maven
     assemble {
-        jar {
-            fatJar=true
-            name = "wasabi-fat-" + version + ".jar"
-        }
-        mavenJars{
+        mavenJars {
         }
     }
-}
-
    -

    4. Sync your build file

    + jcenter { + publish = true + } +} +

    4. Build your project

    - If you're using Intellij IDEA, make sure you've installed the Kobalt plugin and then go to Kobalt -> Sync Build File. This will download dependencies in a way that IDEA understand so you no longer get errors. + You can now attempt to build your project with Kobalt: +

    +
    +./kobaltw assemble
    +

    5. IDEA users: Import your project in IDEA

    +

    + +

    +You can now open your project in IDEA and if you have the Kobalt IDEA plug-in installed, you +will be asked whether you want to import that project as a Kobalt project. +

    +

    6. IDEA users: Sync your build file

    +

    + Once your project has been imported as a Kobalt project in IDEA, bring up the Kobalt window (sideways on the + right side) and click the Sync icon, which will synchronize your build file with IDEA.

    -

    5. Next steps

    +

    7. Next steps

    From this point, you can either learn how to install the Kobalt IDEA plug-in or read Kobalt's documentation.

    diff --git a/home/index.html b/home/index.html index 5dbb999..c56d83c 100644 --- a/home/index.html +++ b/home/index.html @@ -62,7 +62,7 @@

    - + Kobalt is a build system inspired by Gradle and Maven. It reuses the best concepts from these two successful and popular build systems while adding a few modern features of its own. Kobalt is written entirely in Kotlin and its build files are valid Kotlin files as well. Thanks to IDEA's top notch @@ -71,33 +71,12 @@

    - + Here are some of Kobalt's most prominent features.

    Features

    -

    Build file auto-completion in your IDE

    -

    - Since Kobalt's build files are actual Kotlin files, not only can you leverage auto-completion - to write your build files but the full power of your IDEA is at your fingertips to write - these files in any way you see fit: using expressions, conditionals, classes, extension functions, - constants... The sky is the limit! -

    -

    - Kobalt uses Kotlin's type safe builder pattern to offer a DSL that's extremely similar to Gradle - and minimalistic while allowing you to switch to full Kotlin code whenever necessary. -

    -

    - Here is an example of the auto-completion dialog: -

    -

    - -

    -

    - And see the following section to get a feel for Kobalt's build file syntax. -

    -

    Clean, minimal syntax for build files

    For example, here is JCommander's entire build file: @@ -109,7 +88,7 @@ import com.beust.kobalt.plugin.java.* import com.beust.kobalt.plugin.packaging.* import com.beust.kobalt.plugin.publish.* -val jcommander = javaProject { +val jcommander = project { name = "jcommander" group = "com.beust" artifactId = name @@ -133,7 +112,31 @@ val jcommander = javaProject {

    This build file also includes a directive to upload your artifacts to Bintray automatically.

    -

    Incremental tasks

    + + +

    Build file auto-completion in your IDE

    +

    + Since Kobalt's build files are actual Kotlin files, not only can you leverage auto-completion + to write your build files but the full power of your IDEA is at your fingertips to write + these files in any way you see fit: using expressions, conditionals, classes, extension functions, + constants... The sky is the limit! +

    +

    + Kobalt uses Kotlin's type safe builder pattern to offer a DSL that's extremely similar to Gradle + and minimalistic while allowing you to switch to full Kotlin code whenever necessary. +

    +

    + Here is an example of the auto-completion dialog: +

    +

    + +

    +

    + And see the following section to get a feel for Kobalt's build file syntax. +

    + + +

    Incremental tasks

    Most of Kobalt's core tasks are incremental, which means that if you run them without having changed anything, they will be skipped. The support for incremental tasks is also trivial to add for plug-in developers, which guarantees that your builds with Kobalt will always be as fast as they can be.

    @@ -172,6 +175,7 @@ Kobalt is currently in Beta but already used in several projects. Here are links
  • JCommander.
  • TestNG (this build file shows an example of adding a custom task in the build itself).
  • Klaxon
    • +
  • u2020 (Android show case application)
  • ... and of course, Kobalt itself (this build file demonstrates multi projects and project dependencies).
    • diff --git a/idea-plug-in/index.html b/idea-plug-in/index.html index ba7b668..7f93119 100644 --- a/idea-plug-in/index.html +++ b/idea-plug-in/index.html @@ -64,7 +64,7 @@

    How to install and use the Kobalt IDEA plug-in

    -

    Installation

    +

    Installation

    Open the "Plugins" section of the IDEA preferences and find the "Kobalt" plug-in.

    @@ -72,13 +72,26 @@

    - Install it and restart IDEA. If the plug-in was correctly installed, you should see a new menu called "Kobalt" juste before the "Help" menu: + Install it and restart IDEA. Next time you open a project with a Build.kt build file in it, IDEA + will offer to import it as a Kobalt project.

    -

    - +

    + +

    +

    + +

    + +

    +Once you accept, a new window will be available on the right +side of your main IDEA window. Clicking it will reveal the whole Kobalt window. +You can then click on the Sync icon in the upper left corner to update your dependencies:

    -

    Features

    +

    + +

    +

    Features

    The Kobalt IDEA plug-in offers the following features:

      @@ -86,7 +99,7 @@
    • Automatic completion of Build.kt

    -

    Synchronization of build files

    +

    Synchronization of build files

    The plug-in will locate your kobalt/src/Build.kt file and automatically update your project's libraries and dependencies to reflect it. For example, suppose you have the following dependencies: @@ -140,7 +153,7 @@ dependencies {

    -

    Auto completion of Build.kt

    +

    Auto completion of Build.kt

    The plug-in will automatically turn on auto-completion of your kobalt/src/Build.kt file. Once this is @@ -165,7 +178,7 @@ val lc = lineCount { -

    Source code and bug reports

    +

    Source code and bug reports

    The source code can be found on github. If you need to report a bug, please make sure you include the log file, which you can find under diff --git a/pics/kobalt-import-1.png b/pics/kobalt-import-1.png new file mode 100644 index 0000000..d7ca8d7 Binary files /dev/null and b/pics/kobalt-import-1.png differ diff --git a/pics/kobalt-import-2.png b/pics/kobalt-import-2.png new file mode 100644 index 0000000..1ffe193 Binary files /dev/null and b/pics/kobalt-import-2.png differ diff --git a/pics/kobalt-main-window.png b/pics/kobalt-main-window.png new file mode 100644 index 0000000..712b010 Binary files /dev/null and b/pics/kobalt-main-window.png differ diff --git a/plug-in-development/index.html b/plug-in-development/index.html index e96eb76..a051701 100644 --- a/plug-in-development/index.html +++ b/plug-in-development/index.html @@ -30,54 +30,120 @@ --> - -

    - - - -

    How to write a Kobalt plug-in

    - -
    -

    Tutorial

    -

    - If you are curious to get a quick feel for what a Kobalt plug-in looks like, I suggest you go read how to - write and publish a plug-in in ten minutes and then you can come back here - and keep reading. -

    + +
    + + + +

    How to write a Kobalt plug-in

    + +
    +

    Tutorial

    +

    +If you are curious to get a quick feel for what a Kobalt plug-in looks like, I suggest you go read how to +write and publish a plug-in in ten minutes and then you can come back here +and keep reading. +

    +

    Setting up IDEA

    +

    Launch configuration

    +

    + The simplest way to run your plug-in in your IDE is to create a main function in the main class of your + plug-in as follows: +

    +
    +fun main(argv: Array<String>) {
+    com.beust.kobalt.main(argv)
+}
+
    +

    + In order for this code to compile, you will have to switch the dependency of your plug-in from + kobalt-plugin-api to just kobalt, which is the actual application (and which + therefore contains the main() entry point). +

    +
    +        // Normal dependency
+        compile("com.beust:kobalt-plugin-api:$KOBALT_VERSION")
 
-                
    Plug-in architecture
    
-                
    
-                
    
-                Plug-ins often produce files and data that other plug-ins need to use in order for a build to succeed. For example,
-                the Android plug-in needs to generate a file called R.java and then make this file available at
-                compile time by the Java or Kotlin (or any other language) plug-in. Since plug-ins have no idea about what other
-                plug-ins are currently enabled and running, they can't directly talk to each other so instead of calling into
-                Kobalt, Kobalt calls into them. This is done by declaring various "actors" that Kobalt will invoke whenever
-                it needs the information that your plug-in produced. This is a design pattern often referred to as the
-                "Hollywood Principle": "Don't call us, we'll call you".
-                
    
-                
    
-                These "actors" are exactly what the kobalt-plugin.xml file describes. This file informs Kobalt about
-                the various ways in which your plug-in participates in the build system by specifying 1) plug-ins, 2) contributors
-                or 3) interceptors.
-                
    
-                
    
+        // Development dependency
+        compile("com.beust:kobalt:$KOBALT_VERSION")
+
    +

    + You might find it convenient to leverage Kobalt's ability to use regular Kotlin variables to make things easier: +

    +
    +val dev = false
+val kobaltDependency = if (dev) "kobalt" else "kobalt-plugin-api"
 
-                
    Parts
    
-                
    
-                
      
-                    
    • kobalt-plugin.xml. A file that describes all the components (called "plug-in actors") of your plug-in, such as contributors.
      • 
-                    
    • Directives. Kotlin functions that users of your plug-in can invoke in their build file, such as kotlinProject or dependencies. These functions typically configure some data that your plug-in will later use to perform its functions.
      • 
-                    
    • Tasks. These tasks are invoked from the command line and ask your plug-ins to perform certain actions.
      • 
-                    
    • Properties. Plug-ins can export properties and read properties from other plug-ins.
      • 
-                
    
-                
    
-                
-                
    kobalt-plugin.xml
    
-                
    
-                The kobalt-plugin.xml file (stored in META-INF in the jar file of your plug-in) is mandatory and describes all the actors of your plug-in. This file contains a list of class names, each of which is expected to implement at least one of IPluginActor's interfaces:
-                
    
+val p = project {
+    // ...
+
+    compile("com.beust:$kobaltDependency:$KOBALT_VERSION")
+}
+
    +

    + Then you can simply set the dev to true during development and back to false + when you are ready to publish your plug-in. + +

    +

    + Then resync your build file in IDEA and your main() function should now build and be launchable. + You can right click on that class file and select "Debug <your class name>", which will launch Kobalt + with your plug-in. You can set a breakpoint in one of your tasks or anywhere that gets invoked. Don't forget + to invoke this launch configuration with the regular parameters passed to Kobalt (e.g. "assemble"). +

    +

    Local dependencies

    +

    + In the process of building your plug-in, you will probably be invoking it from test projects and since + you will be making changes to your plug-in and generating jar files often, you might find it more convenient + to have these test projects point to your local jar file instead of the Maven one (which would require you + to upload your plug-in all the time). For this, you might find the file() and homeDir + () directives convenient: +

    +
    +    // Regular dependency
+    compile("com.example:myPlugin:0.1")
+
+    // Development dependency
+    compile(file(homeDir("kotlin/myPlugin/kobaltBuild/libs/myPlugin-0.1.jar"))
+
    +

    + With this latter configuration, simply build your plug-in to generate the jar file with ./kobaltw + assemble, switch to your test project and invoke Kobalt on it so that your plug-in will get invoked + and you should see the latest version of your code being invoked. +

    +

    Plug-in architecture

    +

    +

    +Plug-ins often produce files and data that other plug-ins need to use in order for a build to succeed. For example, +the Android plug-in needs to generate a file called R.java and then make this file available at +compile time by the Java or Kotlin (or any other language) plug-in. Since plug-ins have no idea about what other +plug-ins are currently enabled and running, they can't directly talk to each other so instead of calling into +Kobalt, Kobalt calls into them. This is done by declaring various "actors" that Kobalt will invoke whenever +it needs the information that your plug-in produced. This is a design pattern often referred to as the +"Hollywood Principle": "Don't call us, we'll call you". +

    +

    +These "actors" are exactly what the kobalt-plugin.xml file describes. This file informs Kobalt about +the various ways in which your plug-in participates in the build system by specifying 1) plug-ins, 2) contributors +or 3) interceptors. +

    +

    + +

    Parts

    +

    +

      +
    • kobalt-plugin.xml. A file that describes all the components (called "plug-in actors") of your plug-in, such as contributors.
      • +
    • Directives. Kotlin functions that users of your plug-in can invoke in their build file, such as project or dependencies. These functions typically configure some data that your plug-in will later use to perform its functions.
      • +
    • Tasks. These tasks are invoked from the command line and ask your plug-ins to perform certain actions.
      • +
    • Properties. Plug-ins can export properties and read properties from other plug-ins.
      • +
    +

    + +

    kobalt-plugin.xml

    +

    +The kobalt-plugin.xml file (stored in META-INF in the jar file of your plug-in) is mandatory and describes all the actors of your plug-in. This file contains a list of class names, each of which is expected to implement at least one of IPluginActor's interfaces: +

     <plugin-actors>
   <class-name>com.beust.kobalt.plugin.java.JavaPlugin</class-name>
@@ -109,9 +175,9 @@ class JavaPlugin : ICompilerContributor, IDocContributor {
    With this declaration, we know that the JavaPlugin contributes a compiler and a doc generator. 

    -class JavaBuildGenerator: IInitContributor {
    +class JavaBuildGenerator: ITemplateContributor {

    - This class is declaring that it wants to take part in the --init selection process, discussed below. + This class is declaring that it wants to take part in the --init process (i.e. it can generate a template), discussed below.

    List of plug-in actors

    @@ -124,85 +190,105 @@ class JavaBuildGenerator: IInitContributor { Description - - IBuildConfigFieldContributor - IInterceptor + IAssemblyContributor + IContributor + + Plug-ins that want be invoked when the assemble task is called. + + + + + IBuildConfigContributor + IContributor + + Plug-ins that want to generate their own BuildConfig file. + + + + + IBuildConfigFieldContributor + IInterceptor Plug-ins that want to add custom fields to the generated BuildConfig class. - IBuildDirectoryInterceptor - IInterceptor + IBuildDirectoryInterceptor + IInterceptor Plug-ins that need to generate class files in a different directory than the default one should implement this interface. - IClasspathContributor + IClasspathContributor - IContributor + IContributor Classpath contributors let you specify additional jar files or directories that will be used by the "compile" task. - IClasspathInterceptor + IClasspathInterceptor - IInterceptor + IInterceptor Plug-ins that want to modify the classpath before Kobalt uses it should implement this interface. - ICompilerContributor - IContributor + ICompilerContributor + IContributor - Plug-ins that know how to turn files into bytecodes should implement this interface. + Plug-ins that want be invoked when the compile task is called. - ICompilerFlagContributor - IContributor + ICompilerFlagContributor + IContributor Plug-ins that need to add flags to the compiler. - ICompilerInterceptor - IInterceptor + IIncrementalTaskContributor + IContributor + + Plug-ins that implement this interface provide incremental tasks. + + + + ICompilerInterceptor + IInterceptor Plug-ins that implement this interface get a chance to alter the dependencies of a project (dependencies{}, dependenciesTest{}, ...) before Kobalt sees them. - IDocContributor - IContributor + IDocContributor + IContributor Plug-ins that know how to generate documentation out of source files should implement this interface. - IInitContributor - IContributor - Kobalt supports the --init command line parameter, which generates a default build file - based on the files found in the current directory. Any plug-in that wants to be part of this process need - to implement this interface. In this case, both the Java and Kotlin plug-ins define such a contributor - but future plug-ins might use this contributor to generate their own build file: Android, Ceylon, Spring, etc... + IMavenIdInterceptor + IInterceptor + + Plug-ins that need to rewrite Maven id's should implement this interface. - IProjectContributor - IContributor + IProjectContributor + IContributor Some plug-ins produce projects (Java, Kotlin) while others don't (Packaging, Application, etc...). The ones that do need to register themselves as project contributors. This is how Kobalt collects all the projects defined after a build file was parsed. - IRepoContributor - IContributor + IRepoContributor + IContributor Some plug-ins might want to add their own repository to the list of repositories that Kobalt already supports. This is the case of the Android plug-in which, once the ANDROID_HOME environment variable has been @@ -211,61 +297,78 @@ class JavaBuildGenerator: IInitContributor { - IRunnerContributor - IContributor + IRunnerContributor + IContributor Plug-ins that can operate when the "run" task gets invoked should implement that interface. - + ISourceDirectoryContributor - IContributor + IContributor Plug-ins that add source directories. - - - ISourceDirectoryInterceptor - IInterceptor - - Plug-ins that want to add, remove or alter the source directories should implement this interface. - - - - - ITestRunnerContributor - IContributor - - Plug-ins that can operate when the "test" task gets invoked should implement that interface. - - - - - ITestSourceDirectoryContributor - IContributor - - - Plug-ins that add test source directories. - - + + + ISourceDirectoryInterceptor + IInterceptor + + Plug-ins that want to add, remove or alter the source directories should implement this interface. + + + + ITaskContributor + IContributor + + Plug-ins that implement this interface provide tasks. + + + + ITemplateContributor + IContributor + When invoked with --init followed by template names separated by commas, + Kobalt will invoke each of these contributors so they can generate their files. + Templates are useful to create projects from scratch with a minimal number of + files to get started. For example, the "java" template will generate a Build.kt + file suitable for a brand new Java project. + + + + + ITestRunnerContributor + IContributor + + Plug-ins that can operate when the "test" task gets invoked should implement that interface. + + + + + ITestSourceDirectoryContributor + IContributor + + + Plug-ins that add test source directories. + + -

    Selection process

    -

    - Several plug-ins might want to contribute to a specific task where only one participant should be allowed, - such as running tests or generating documentation. Even the simple task of compiling should probably only - ever be performed by no more than one plug-in for a given project. Therefore, when comes the time to - compile a project, - Kobalt needs to find which plug-in is the most suitable for that task and pick it. In order to do that, - plug-ins that contribute to tasks that can only be performed by one candidate need to declare their - affinity to that task for a given project. -

    -

    - Contributors that want to participate in a selection process need to implement the following interface: -

    +

    Selection process

    +

    +Several plug-ins might want to contribute to a specific task where only one participant should be allowed, +such as running tests or generating documentation. Even the simple task of compiling should probably only +ever be performed by no more than one plug-in for a given project. Therefore, when comes the time to +compile a project, +Kobalt needs to find which plug-in is the most suitable for that task and pick it. In order to do that, +plug-ins that contribute to tasks that can only be performed by one candidate need to declare their +affinity to that task for a given project. +

    +

    +Contributors that want to participate in a selection process need to implement the following interface: +

     interface IProjectAffinity {
     /**
@@ -274,39 +377,39 @@ interface IProjectAffinity {
      */
     fun affinity(project: Project, context: KobaltContext) : Int
 }
    -

    - For example, the JavaPlugin implements the ICompilerContributor interface and then overrides - the affinity() method to make sure it gets run for Java projects but ignored for others: -

    +

    +For example, the JavaPlugin implements the ICompilerContributor interface and then overrides +the affinity() method to make sure it gets run for Java projects but ignored for others: +

     override fun affinity(project: Project, context: KobaltContext) =
 if (project.sourceSuffix == ".java") 1 else 0
    -

    Directives

    -

    - Directives are functions that users of your plug-in can use in their build file in order to configure your plug-in. These can be any kind of Kotlin function but in the interest of preserving a clean syntax in the build file, it's recommended to use the type safe builder pattern, as described here. -

    -

    - Imagine that you want to offer a boolean parameter publish to users of your plug-in, you start by creating a class to hold that parameter: -

    +

    Directives

    +

    +Directives are functions that users of your plug-in can use in their build file in order to configure your plug-in. These can be any kind of Kotlin function but in the interest of preserving a clean syntax in the build file, it's recommended to use the type safe builder pattern, as described here. +

    +

    +Imagine that you want to offer a boolean parameter publish to users of your plug-in, you start by creating a class to hold that parameter: +

     class Info(val publish: Boolean)
    -

    - Next, you create a directive that returns such a class and which also allows to configure it via the type safe builder pattern: -

    +

    +Next, you create a directive that returns such a class and which also allows to configure it via the type safe builder pattern: +

     @Directive
 public fun myConfig(init: Info.() -> Unit) = Info().apply { init() }
    -

    - The @Directive annotation is not enforced but you should always use it in order to help future tools (e.g. an IDEA plug-in) identify Kobalt directives so they can be treated differently from regular Kotlin functions. The code above defines a myConfig function that accepts a closure as an argument. It creates an Info - object, calls the init() function on it (which runs all the code inside that closure) and then return that Info object. -

    -

    - Users can now specify the following in their build file: +

    +The @Directive annotation is not enforced but you should always use it in order to help future tools (e.g. an IDEA plug-in) identify Kobalt directives so they can be treated differently from regular Kotlin functions. The code above defines a myConfig function that accepts a closure as an argument. It creates an Info +object, calls the init() function on it (which runs all the code inside that closure) and then return that Info object. +

    +

    +Users can now specify the following in their build file: 

     // Build.kt
-ort.com.example.plugin.myConfig
+import.com.example.plugin.myConfig
 myConfig {
     publish = true
 }
    @@ -333,135 +436,140 @@ public fun myConfig(init: Info.() -> Unit) = Info().apply { (Kobalt.findPlugin("my-plug-in") as MyPlugin).info = info this } -

    - Obviously, you can choose any kind of API to communicate between the directive and its plug-in. In the code - above, I chose to directly override the entire Info field, but you could instead choose to call - a function, just set one boolean instead of the whole object, etc... -

    -

    Tasks

    -

    - Tasks are provided by plug-ins and can be invoked from the command line, e.g. ./kobaltw assemble. There are two kinds of tasks: static and dynamic. -

    -

    Static tasks

    -

    - Static tasks are functions declared directly in your plug-in class and annotated with the @Task annotation. Here is an example: -

    +

    +Obviously, you can choose any kind of API to communicate between the directive and its plug-in. In the code +above, I chose to directly override the entire Info field, but you could instead choose to call +a function, just set one boolean instead of the whole object, etc... +

    +

    Tasks

    +

    +Tasks are provided by plug-ins and can be invoked from the command line, e.g. ./kobaltw assemble. There are two kinds of tasks: static and dynamic. +

    +

    Static tasks

    +

    +Static tasks are functions declared directly in your plug-in class and annotated with the @Task annotation. Here is an example: +

    -@Task(name = "lineCount", description = "Count the lines", runBefore = arrayOf("compile"))
+@Task(name = "lineCount", description = "Count the lines", dependsOn = arrayOf("compile"))
 fun lineCount(project: Project): TaskResult {
     // ...
     return TaskResult()
 }
    -

    - A Kobalt task needs to accept a Project in parameter and return a TaskResult, which indicates whether this task completed successfully. -

    -

    - The @Task annotation accepts the following attributes: -

    -
    name
    -
    The name of the task, which will be used to invoke it from the command line.
    -
    description
    -
    The description of this command, which will be displayed if the user invokes the usage for the kobaltw command.
    -
    runBefore
    -
    A list of all the tasks that this task should run prior to.
    -
    runAfter
    -
    A list of all the tasks that should run before this task does.
    -
    alwaysRunAfter
    -
    A list of all the tasks that will always be run after this task if it's invoked.
    -
    -

    -

    - The difference between runAfter and alwaysRunAfter is subtle but important. runAfter - is just a declaration of dependency. It's basically the reverse of runBefore but it's useful in case - you are not the author of the task you want to run before (if you were, you would just use the runBefore - annotation on it). Since you can't say "a runBefore b" because you don't own task "a", - you say "b runAfter a". -

    -

    - For example, compileTest is declared as a runAfter for the task compile. - This means that it doesn't make sense to run compileTest unless compile has run first. - However, if a user invokes the task compile, they probably don't want to invoke compileTest, - so a dependency is exactly what we need here: invoking compileTest will trigger compile - but not the other way around. -

    -

    - However, there are times where you want to define a task that will always run after a given task. - For example, you could have a signJarFile task that should always be invoked if someone builds a jar - file. You don't expect users to invoke that target explicitly, but whenever they invoke the assemble - target, you want your signJarFile target to be invoked. When you want such a task to always be invoked - even if the user didn't explicitly request it, you should use alwaysRunAfter. - Note that there is no alwaysRunBefore annotation since runBefore - achieves the same functionality. -

    -

    - Here are a few different scenarios to illustrate how the three attributes work for the task exampleTask: -

    -

    - Result of the command ./kobaltw --dryRun compile -

    - - - - - - - - - - - - - - - - - -
    Configuration for exampleTaskResult
    runBefore = "compile" -
    kobalt-line-count:clean
-kobalt-line-count:exampleTask
-kobalt-line-count:compile
    -
    runAfter = "compile" - 
    kobalt-line-count:clean
-kobalt-line-count:compile
    -
    alwaysRunAfter = "compile" - 
    kobalt-line-count:clean
-kobalt-line-count:compile
-kobalt-line-count:exampleTask
    -
    -

    Dynamic tasks

    -

    - Dynamic tasks are useful when you want your plug-in to generate one or several tasks that depend on - some other runtime information (therefore, you can't declare a method and put a @Task - annotation on it). Plug-ins declare dynamic tasks by implementing the ITaskContributor - intrface: -

    +

    +A Kobalt task needs to accept a Project in parameter and return a TaskResult, which indicates whether this task completed successfully. +

    +

    +The @Task annotation accepts the following attributes: +

    +
    name
    +
    The name of the task, which will be used to invoke it from the command line.
    +
    description
    +
    The description of this command, which will be displayed if the user invokes the usage for the kobaltw command.
    +
    dependsOn
    +
    A list of all the tasks that this task depends on.
    +
    reverseDependsOn
    +
    Make the following tasks depend on this task.
    +
    runBefore
    +
    A list of all the tasks that this task should run prior to.
    +
    runAfter
    +
    A list of all the tasks that should run before this task does.
    +
    +

    +

    + Kobalt defines two different concepts for tasks: dependencies and orderings. And for each of this concept, + you can define the relation to go in one direction or the other. +

    +

    + If your task cannot run until another task has run, you need to declare a dependency. Dependencies cause + additional tasks than those requested to be executed. For example, "assemble" depends on "compile", which means that whenever you invoke "assemble", "compile" + will be automatically run first. This is a dependency and it is controlled by "dependsOn" and + "reverseDependsOn". You can see "reverseDependsOn" as a way to insert your task before an existing task. +

    +

    + Orderings, controlled by "runBefore" and "runAfter" merely specify an ordering + but do not pull new tasks in. This is how you tell Kobalt "In case the user asks for my task to run, + here is when it should be invoked", but your task will run only if it's explicitly invoked by the user. +

    +

    +Here are a few different scenarios to illustrate how the three attributes work for the task example: +

    +

    +Result of the command ./kobaltw --dryRun compile +

    + + + + + + + + + + + + + + + + + + + + + + +
    Configuration for exampleResultNote
    dependsOn = "compile" +
    clean
+compile
+example
    +     		+ Make the "example" task depend on "compile". +
    reverseDependsOn = "compile" +
    clean
+example
+compile
    +     		+ Insert the "example" task before "compile". +
    runAfter = "compile" +
    clean
+compile
    +     		+ Make "example" run after "compile" but only if it's invoked explicitly. +
    +

    Dynamic tasks

    +

    +Dynamic tasks are useful when you want your plug-in to generate one or several tasks that depend on +some other runtime information (therefore, you can't declare a method and put a @Task +annotation on it). Plug-ins declare dynamic tasks by implementing the ITaskContributor +intrface: +

     interface ITaskContributor {
-    fun tasksFor(context: KobaltContext) : List<DynamicTask>
+fun tasksFor(context: KobaltContext) : List<DynamicTask>
 }
    -

    - For example: -

    +

    +For example: +

     override fun tasksFor(context: KobaltContext) = listOf(
     DynamicTask(
         name = "dynamicTask",
         description = "Description",
-        alwaysRunAfter = listOf("compile"),
+        reverseDependsOn = listOf("compile"),
         closure = { project: Project ->
             println("Running dynamicTask")
             TaskResult()
 }))
    -

    - DynamicTask mirrors the @Task attributes: name, description and - dependencies. The only addition is the closure parameter, which specifics the code that will - run if your task gets invoked. That closure needs to follow the same constraints that a @Task method - obeys: it takes a Project parameter and returns a TaskResult. -

    -

    - Once you have implemented ITaskContributor, you can see your dynamic task in the list of tasks and run it directly: -

    +

    +DynamicTask mirrors the @Task attributes: name, description and +dependencies. The only addition is the closure parameter, which specifics the code that will +run if your task gets invoked. That closure needs to follow the same constraints that a @Task method +obeys: it takes a Project parameter and returns a TaskResult. +

    +

    +Once you have implemented ITaskContributor, you can see your dynamic task in the list of tasks and run it directly: +

     $ ./kobaltw --tasks
   ===== kobalt-line-count =====
@@ -470,32 +578,38 @@ $ ./kobaltw --tasks
 $ ./kobaltw dynamicTask
 Running dynamictask
    -

    Properties

    -

    - Properties are the mechanism that plug-ins can use to export values and also read values that other - plug-ins have exported. There are two kinds of properties that plug-ins can manipulate: -

    -
      -
    • Project properties: project-specific properties.
      • -
    • Plug-in properties: general properties that are applicable to no project - in particular.
      • -
    -

    Project properties

    -

    - Project instances have a property called projectProperties that is an - instance of the ProjectProperties class. Plugins can put and get values on this - object in order to store project specific properties. -

    - 
    +
    Properties
    
+
    
+Properties are the mechanism that plug-ins can use to export values and also read values that other
+plug-ins have exported. There are two kinds of properties that plug-ins can manipulate:
+
    
+
      
+    
    • Project properties: project-specific properties.
      • 
+    
    • Plug-in properties: general properties that are applicable to no project
+    in particular.
      • 
+
    
+
    Project properties
    
+
    
+Project instances have a property called projectProperties that is an
+instance of the ProjectProperties class. Plugins can put and get values on this
+object in order to store project specific properties.
+
    
+
     fun taskAssemble(project: Project) : TaskResult {
-    project.projectProperties.put(PACKAGES, packages)
+    project.projectProperties.put("packages", packages)
 
    
-                    
    Plug-in properties
    
-                    
    
-                    The PluginProperties instance can be found on the KobaltContext
-                    object that your plug-in receives in its apply() method. Once you have an instance of this
-                    class, you can read or write variables into it:
-                    
    
+
    
+    Another plug-in can then query this property as follows:
+
    
+
    +    val packages = project.projectProperties.put("packages")
+
    
+
    Plug-in properties
    
+
    
+The PluginProperties instance can be found on the KobaltContext
+object that your plug-in receives in its apply() method. Once you have an instance of this
+class, you can read or write variables into it:
+
    
 
     override fun apply(project: Project, context: KobaltContext) {
     // Export a property for other plug-ins to use
@@ -504,33 +618,33 @@ override fun apply(project: Project, context: KobaltContext) {
     val sourceDir = context.pluginProperties.get("pluginName", "somePluginProperty")
 }
 
    
-                    
    Documenting properties
    
-                    
    
-                    Plug-ins that define properties should annotate them with the @ExportedPluginProperty or
-                    @ExportedProjectPropertyannotation:
-                    
    
+            
    Documenting properties
    
+            
    
+            Plug-ins that define properties should annotate them with the @ExportedPluginProperty or
+            @ExportedProjectPropertyannotation:
+            
    
 
    -    companion object {
-        @ExportedProjectProperty
-        const val BUILD_DIR = "buildDir"
+companion object {
+@ExportedProjectProperty
+const val BUILD_DIR = "buildDir"
 
    
-
    - -
    -
    - - - - - - - - - -
    - \ No newline at end of file +
    + +
    +
    + + + + + + + + + +
    + \ No newline at end of file diff --git a/plug-ins/index.html b/plug-ins/index.html index 466b2f2..fc29f04 100644 --- a/plug-ins/index.html +++ b/plug-ins/index.html @@ -50,25 +50,25 @@

    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: + Java and Kotlin are supported by default by Kobalt. You use the directive project{} + to declare a new project and Kobalt will automatically detect how to compile it: 

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

    -Both these directives create an object of type Project. +The project{} directive creates 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). +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").

    @@ -85,6 +85,23 @@ A Project has two mandatory attributes: name and The dependencies for your tests +

    Mixed language projects

    +

    + A Kobalt project can mix Kotlin and Java in it, simply specify all the source + directories you need: +

    +
    +val p = project(wrapper) {
+    name = "kobalt"
+    // ...
+    sourceDirectories {
+        path("src/main/java", "src/main/kotlin")
+    }
+}
    +

    + Kotlin and Java files can be in the same directories. +

    +

    Tasks

    Once you have at least one project configured, the plug-in lets you invoke the following tasks: @@ -99,6 +116,53 @@ Once you have at least one project configured, the plug-in lets you invoke the f

    Clean the project
    +

    Templates

    +

    + Both the Java and Kotlin plug-ins provide templates named respectively "java" and "kotlin". +

    +
    +$ ./kobaltw --listTemplates
+Available templates
+  Plug-in: Kobalt
+    "java"              Generate a simple Java project
+    "kotlin"            Generate a simple Kotlin project
    + +

    + They are both identical templates so we'll just look over the Kotlin one. +

    +

    + If you invoke ./kobaltw --init kotlin, the following will happen: +

    +
      +
    • If a kobalt/src/Build.kt build file doesn't exist, it will be created.
      • +
    • If no Kotlin (or Java) file is found under src, the template will create a simple + class with a main method and also a test class.
      • +
    +
    +$ ./kobaltw --init kotlin
+Template "kotlin" installed
+Now you can run either `./kobaltw test` or `./kobaltw run`
+
+$ ./kobaltw test
+----- example:test
+===============================================
+Command line suite
+Total tests run: 1, Failures: 0, Skips: 0
+===============================================
+
+All tests passed
+BUILD SUCCESSFUL (5 seconds)
+
+$ ./kobaltw run
+----- example:run
+Hello Kotlin world from Kobalt
+BUILD SUCCESSFUL (0 seconds)
+
    + + + + +

    Variants

    Variants let you configure your project to generate different artifacts compiled from different sources depending on the variant you selected. @@ -116,7 +180,7 @@ Once you have at least one project configured, the plug-in lets you invoke the f

  • 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: + Product flavors usually contain 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") {
@@ -146,10 +210,21 @@ 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".

    +

    + Variants can have they own dependencies{} section, which will be used only if this specific + variant is being compiled or assembled: +

    +
    +    productFlavor("debug") {
+        dependencies {
+            compile("joda-time:joda-time:2.9.3")
+        }
+    }
+

    BuildConfig

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

    @@ -377,7 +452,7 @@ assemble {

    install

    - The install section lets you specify how the artifacts get installed. If you don't specify any install directive, then the install task will do nothing on your project when invoked. + The install section lets you specify how the artifacts get installed. If you don't specify any install directive, then the install task will install your artifacts in the lib directory by default. 

         install {
diff --git a/ten-minutes/index.html b/ten-minutes/index.html
index 84897a8..f49cee0 100644
--- a/ten-minutes/index.html
+++ b/ten-minutes/index.html
@@ -75,16 +75,15 @@
 $ mkdir linecount
 $ cd linecount
 $ mkdir -p src/main/kotlin/com/beust/plugin/linecount
-$ touch src/main/kotlin/com/beust/plugin/linecount/Main.kt
-$ $KOBALT_HOME/kobaltw --init
+$ $KOBALT_HOME/kobaltw --init kotlin
    -

    - I create an empty Main.kt in the example above so that calling ./kobaltw --init will detect the project as a Kotlin one. This way, the Build.kt file generated is already configured for Kotlin. Since we will be publishing this project to a Maven repository, we need to make sure that its group, artifactId and version are correct. The only thing that the generator can't guess is the group, so let's go ahead and fix it: -

    +

    + ./kobaltw --init kotlin creates an empty Kotlin project. Since we will be publishing this project to a Maven repository, we need to make sure that its group, artifactId and version are correct. The only thing that the generator can't guess is the group, so let's go ahead and fix it: +

    -val project = kotlinProject {
+val project = project {
     name = "kobalt-line-count"
     group = "com.beust.kobalt"
     artifactId = name