From 6d784ca363063266f24f317d3fe8e7634644b6a6 Mon Sep 17 00:00:00 2001 From: Cedric Beust Date: Sat, 3 Oct 2015 03:25:35 -0700 Subject: [PATCH] Fixes. --- bootstrap/documentation/index.html | 55 ++++++++++++++++++++++++++---- 1 file changed, 48 insertions(+), 7 deletions(-) diff --git a/bootstrap/documentation/index.html b/bootstrap/documentation/index.html index 73606bd..aaaa4b1 100644 --- a/bootstrap/documentation/index.html +++ b/bootstrap/documentation/index.html @@ -72,28 +72,36 @@

Downloading and installing Kobalt

+

Download the zip file (bottom left of the screen) then unzip it in a location we'll call KOBALT_HOME: +

 cd $KOBALT_HOME
 unzip kobalt-xxx.zip
+

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 Build.kt file in your current directory based on what was found there.
  2. Install the Kobalt Wrapper in your current directory (script `kobaltw`) and in the kobalt/ 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 assemble
@@ -107,7 +115,9 @@ As of this writing, Kobalt supports Java and Kotlin projects.
 
 
General concepts

 
+

 The build file is typically called Built.kt and it is a valid Kotlin file. Typically, it contains imports, the declaration of one or more projects and the declaration of additional configurations (e.g. packaging, publishing, etc...).  Since it's a Kotlin file, it can also contain any class or function you need:
+

  
 
 import com.beust.kobalt.*
@@ -132,7 +142,9 @@ Here are a few noteworthy details about this small build file:
 
 
Directives

 
+

 Now that we have declared a project, we can use it to configure additional steps of our build, such as the packaging:
+

 
 
 import com.beust.kobalt.plugin.packaging.packaging
@@ -145,7 +157,9 @@ val packKobalt = packaging(kobalt) {
 }
 

 
+

 This is the simplest jar declaration you can have. You can trigger the creation of this jar file by invoking the task "assemble". Note that we passed the kobalt variable to the packaging function, so we make it clear which project we are currently configuring for packaging. The jar directive accepts various settings, so let's be a bit more specific. And let's add a zip file too:
+

 
 
 val packKobalt = packaging(kobalt) {
@@ -165,15 +179,19 @@ val packKobalt = packaging(kobalt) {
 }
 

 
+

 Our jar file is now declared to be a "fat jar" (which means it will include all its dependencies) and we specified a Main-Class to the jar Manifest, which means we will be able to invoke it with java -jar kobalt-0.61.jar. If you don't like this name, you can override it with a name = "myName.jar" statement.
+

 
 

-
 The zip directive follows a similar structure, although here we are specifying which file we want to include. For more details on the packaging plug-in, please see its documentation.
+

 
 
Dependencies

 
+

 You can declare compile and test dependencies as follows:
+

 
 
 dependencies {
@@ -188,7 +206,9 @@ dependenciesTest {
 
 
Maven 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:
+

 
 
 val repos = repos("https://dl.bintray.com/cbeust/maven/")
@@ -196,11 +216,13 @@ val repos = repos("https://dl.bintray.com/cbeust/maven/")
 
 
Using plug-ins

 
+

 Kobalt comes with a few preconfigured plug-ins but you will want to include external ones as well, which can be downloaded either from a Maven repository (Sonatype, JCenter, ...) or from a local file.
+

 
 

-
 First of all, let's take a quick look at the tasks available in the default distribution (your actual output might differ somewhat):
+

 
 
 $ ./kobaltw --tasks
@@ -218,14 +240,18 @@ $ ./kobaltw --tasks
     assemble         Package the artifacts
 

 
+

 Let's modify our build to include a plug-in. We do this by adding a call to the plugins directive on top of the build file:
+

 
 
 val repos = repos("https://dl.bintray.com/cbeust/maven/")
 val p = plugins("com.beust:kobalt-example-plugin:0.42")
 

 
+

 Now, run the --tasks command again:
+

 
 
 $ ./kobaltw --tasks
@@ -247,11 +273,14 @@ Notice the new "coverage" task, provided by the plug-in kobal
 
 
Publishing

 
+

 Kobalt supports JCenter natively so you can upload your project and make it available on JCenter very easily.
+

 
 

 
 First of all, make sure you specified the group, artifactId and version of your project, as required by Maven:
+

 
 
 val kobalt = kotlinProject {
@@ -260,23 +289,26 @@ val kobalt = kotlinProject {
     version = "0.72"
 

 
+

 Next, 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. Note that you should not check this local.properties file into your source control (so add it to .gitignore).
-
 

+The values for the user and apikey keys can be found in your bintray profile, as described here. Note that you should not check this local.properties file into your source control (so add it to .gitignore). Next, make sure that your build creates a jar file (using the packaging directive, as explained above).
 
-Make sure that your build creates a jar file (using `packaging`, as explained above).
+

 
 

 
 Now, all you need to do is to upload your package:
 
+

+
 
 ./gradlew uploadJcenter
 

@@ -314,12 +346,12 @@ val p = packaging(examplePlugin) {
 A plug-in typically has three components:
 
 
    
-    
  • Extending and implementing the methods of `BasePlugin`.
+    
  • Extending and implementing the methods of BasePlugin.
     
  • Specifying one or more tasks.
     
  • Specifying directives (functions that will be used from the build file).
 

 
-
BasePlugin

+
BasePlugin

 
 The main class of your plugin extends BasePlugin and implements its apply() method and name variable:
 
@@ -355,7 +387,9 @@ public fun coverage(project: Project): 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.
+

 
 

 
@@ -370,7 +404,9 @@ public fun kotlinProject(init: KotlinProject.() -> Unit): KotlinProject {
 }
 

 
+

 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 {
@@ -379,7 +415,10 @@ val kobalt = kotlinProject {
 ...
 

 
+

 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
@@ -390,7 +429,9 @@ public fun Project.dependenciesCoverage(ini: Dependencies.() -> Unit) : Dependen
 }
 

 
+

 And we can now use:
+

 
 
 val p = kotlinProject {