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 @@
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: +
Build.kt
file in your current directory based on what was found there.
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 thekobalt
variable to thepackaging
function, so we make it clear which project we are currently configuring for packaging. Thejar
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 withjava -jar kobalt-0.61.jar
. If you don't like this name, you can override it with aname = "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-inkobal
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 theuser
andapikey
keys can be found in your bintray profile, as described here. Note that you should not check thislocal.properties
file into your source control (so add it to.gitignore
). -+The values for the
user
andapikey
keys can be found in your bintray profile, as described here. Note that you should not check thislocal.properties
file into your source control (so add it to.gitignore
). Next, make sure that your build creates a jar file (using thepackaging
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 extendsBasePlugin
and implements itsapply()
method andname
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 onProject
: +@Directive @@ -390,7 +429,9 @@ public fun Project.dependenciesCoverage(ini: Dependencies.() -> Unit) : Dependen }+And we can now use: +
val p = kotlinProject {