erik/kobalt-doc
erik/kobalt-doc
1
0
Fork 0
mirror of https://github.com/ethauvin/kobalt-doc.git synced 2025-04-25 03:57:11 -07:00
Code Releases Activity

Merge from upstream.

Browse source
This commit is contained in:
Erik C. Thauvin 2016-07-09 10:41:10 -07:00
commit b4cf88c58d
11 changed files with 950 additions and 498 deletions
Download patch file Download diff file Expand all files Collapse all files

31
contributing/index.html
View file

@ -37,7 +37,7 @@
<!-- Main component for a primary marketing message or call to action -->
<!-- Main content -->
<div class="col-md-9">
<h2 class="section" id="launch_configuration">License, Source code & Issues</h2>
<h2 class="section" id="license">License, Source code & Issues</h2>
<p>
Kobalt is <a href="https://github.com/cbeust/kobalt/blob/master/LICENSE.txt">licensed under Apache 2.0</a>
</p>
@ -53,8 +53,33 @@
<li><a href="https://groups.google.com/forum/#!forum/kobalt-dev">Join <code>kobalt-dev</code>, the mailing-list for Kobalt developers</a>. 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.</li>
</ul>
<h2 class="section" id="launch_configuration">Launch configuration</h2>
<p>Here is how to configure your development environment.</p>
<h2 class="section" id="idea">Configuring IDEA</h2>
<p>
Working on the Kobalt code base with Intellij IDEA is very easy.
</p>
<h3 class="section" id="version" indent="1">Edit kobalt.version</h3>
<p>
First of all, edit the file <code>src/main/resources/kobalt.properties</code> and set it
to a nonexistent version. For example, if the current version is <code>0.399</code>,
set it to <code>0.400</code>.
</p>
<pre class="brush:plain">
kobalt.version=0.400
</pre>
<p>
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:
</p>
<pre class="brush:plain">
Couldn't find .../kobalt-0.400.jar, using ...
</pre>
<p>
Note that at the moment, Kobalt expects to be located in <code>$HOME/kotlin/kobalt</code>.
</p>
<h3 class="section" id="launch_configuration" indent="1">Launch configuration</h3>
<p>Next, create a launch configuration in IDEA.</p>
<p>
Kobalt's main class is <code>com.beust.kobalt.MainKt</code>. Here is a typical launch configuration:
</p>

284
documentation/index.html
View file

@ -68,9 +68,8 @@ The build file is located in <code>kobalt/src/Built.kt</code> and it is a valid
<pre class="brush:java">
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:
<ul>
<li>You have now declared a variable called <code>kobalt</code> which you can reuse further in your build file, should you ever need to.
<li>You can specify the directory of the project if it's not in the root, which means that one build file can be used to build multiple projects.
<li>The functions <code>kotlinProject</code> and <code>homeDir</code> are supplied by Kobalt and are referred to as "directives"
<li>The functions <code>project</code> and <code>homeDir</code> are supplied by Kobalt and are referred to as "directives"
</ul>
<p>
@ -124,7 +123,7 @@ Now that we have declared a project, we can use it to configure additional steps
<pre class="brush:java;highlight=5,6,7,8">
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 <code>"@version@"</code> 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 <code>runBefore</code> and <code>runAfter</code>, which specify when this task will run. You can find more information about tasks in the <a href="http://beust.com/kobalt/plug-in-development/index.html#tasks">plug-in development section</a>.
</p>
<h3 class="section" indent="1" id="build-file-classpath">Build file classpath</h3>
<p>
If you are writing code or an inline task in your build file that requires additional libraries,
you can specify these dependencies with the <code>buildFileClasspath()</code> 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:
</p>
<pre class="brush:java">
// Build.kt
val bfc = buildFileClasspath("org.testng:testng:6.9.11")
val t = org.testng.TestNG() // now legal
</pre>
<h3 class="section" indent="1" id="dependencies">Dependencies</h3>
<p>
@ -217,10 +229,37 @@ dependencies {
}
</pre>
<p>
<h4 class="section" indent="2" id="dependency-versions">Dependency versions</h4>
<p>
Kobalt lets you specify Maven coordinates in one line, such as <code>"org.testng:testng:6.9.10"</code>. Note that Kobalt uses the <a href="https://maven.apache.org/pom.html#Maven_Coordinates">Maven Coordinates defined in the Maven specification</a>, which are a little bit different from the ones that Gradle uses.
</p>
<p>
The standard format for such coordinates, as explained in the link above, is:
</p>
<pre class="brush:plain">
groupId:artifactId:packaging:classifier:version</pre>
<p>
<code>packaging</code> (e.g. <code>"jar"</code>) and <code>classifier</code> (usually an arbitrary name) are optional and can be omitted. If <code>version</code>
is omitted, Kobalt will resolve the artifact to its latest version from all the specified repos.
Most of the time, you will only specify <code>groupId</code>, <code>artifactId</code> and <code>version</code>, but if you ever need to specify additional components such as <code>packaging</code> (sometimes referred to as "<code>extension</code>") or <code>classifier</code>,
please take note that these should appear before the version number.
</p>
<p>
Here are a few examples of valid Maven coordinates:
</p>
<pre class="brush:plain">
# No version, resolves to the latest
org.testng:testng:
# Specifies an extension and a qualifier
com.badlogicgames.gdx:gdx-platform:jar:natives-desktop:1.9.2</pre>
<h4 class="section" indent="2" id="dependency-types">Dependency types</h4>
<p>
There are various kinds of dependencies:
</p>
<dl class="dl-horizontal">
</p>
<dl class="dl-horizontal">
<dt>compile</dt>
<dd>Used to compile your project.</dd>
<dt>runtime</dt>
@ -231,22 +270,39 @@ dependencies {
<dd>Exclude the given dependencies from the classpath. You can either
specify a versioned id (e.g. <code>"groupId:artifactId:version"</code>) or a versionless one
(<code>"groupId:artifactId:"</code>).</dd>
</dl>
<dt>native</dt>
<dd>Used to define native dependencies.</dd>
</dl>
<h2 class="section" id="settings">Settings</h2>
<p>
You can create settings that will apply to all your Kobalt builds by creating
a file in <code>~/kobalt/settings.xml</code>:
</p>
<pre class="brush:plain">
<h5 class="section" indent="3" id="native-dependencies">Native dependencies</h5>
<p>
Native dependencies will only be used when you invoke the <code>run</code> task on your project:
</p>
<pre class="brush:java">
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"
)
}</pre>
<h2 class="section" id="settings">Settings</h2>
<p>
You can define settings that will apply to all your Kobalt builds by creating
the file <code>~/.config/kobalt/settings.xml</code>:
</p>
<pre class="brush:plain">
&lt;kobalt-settings&gt;
&lt;localRepo&gt;/Users/beust/my-kobalt-repo&lt;/localRepo&gt;
&lt;/kobalt-settings&gt;
</pre>
<p>
&lt;local-repo&gt;/Users/beust/my-kobalt-repo&lt;/local-repo&gt;
&lt;default-repos&gt;
&lt;repo&gt;http://jcenter.com&lt;/repo&gt;
&lt;repo&gt;http://example.com&lt;/repo&gt;
&lt;/default-repos&gt;
&lt;/kobalt-settings&gt;</pre>
<p>
Here is a list of the parameters you can configure:
</p>
<table style="font-size: 14px" class="table table-striped">
</p>
<table style="font-size: 14px" class="table table-striped">
<colgroup>
<col span="1" style="width: 25%;">
<col span="1" style="width: 25%;">
@ -259,14 +315,103 @@ dependencies {
<td>Description</td>
</tr>
</thead>
<tr>
<td><code>localRepo</code></td>
<td><code>default-repos</code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/Constants.kt#L10">Default repos</a></td>
<td>List of repos overriding the default ones that Kobalt uses.</td>
</tr>
<tr>
<td><code>kobalt-compiler-version</code></td>
<td>1.0.0</td>
<td>The version of the Kotlin compiler that Kobalt uses.</td>
</tr>
<tr>
<td><code>kobalt-compiler-repo</code></td>
<td>None</td>
<td>The Maven repository where to find the compiler. By default, the compiler is looked up in the default repos (JCenter, Maven, ...).</td>
</tr>
<tr>
<td><code>local-repo</code></td>
<td><code>~/.kobalt/repository</code></td>
<td>Where Kobalt stores all the downloaded dependencies.</td>
</tr>
</table>
</table>
<h2 class="section" id="maven-repos">Maven repos</h2>
<h2 class="section" id="templates">Templates</h2>
<p>
Templates are invoked with the <code>--init</code> 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 <code>--listTemplates</code> parameter:
</p>
<pre class="brush:plain">
$ 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</pre>
<p>
You can then invoke any of these templates with <code>--init</code>:
<pre class="brush:plain">
$ kobaltw --init kobaltPlugin
Build this project with `./kobaltw assemble`</pre>
<p>
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:
</p>
<pre class="brush:plain">
$ ./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)</pre>
<p>
We can test this plug-in with another useful command line parameter: <code>--pluginJarFiles</code>. 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):
</p>
<pre class="brush:plain">
$ ./kobaltw --pluginJarFiles kobaltBuild/libs/kobalt-line-count-0.18.jar --tasks
...
===== kobalt-line-count =====
dynamicTask Dynamic task
lineCount Count the lines
...
</pre>
<p>
Kobalt loaded this plug-in and added the tasks that it provides. The parameter
<code>--pluginJarFiles</code> 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 <code>--plugins</code> parameter. For example, let's see what templates the
Android Kobalt plug-in offers:
</p>
<pre class="brush:plain">
$ ./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</pre>
<p>
We see the same plug-ins we just reviewed and a new one provided by the Android plug-in called
<code>"androidJava"</code>. The <code>--plugins</code> 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 <code>Build.kt</code> 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.
</p>
<p>
For a more in-depth description of templates, please refer to <a href="http://beust.com/weblog/2016/02/18/the-kobalt-diaries-templates/">this article</a>.
</p>
<h2 class="section" id="maven-repos">Maven repos</h2>
<h3 class="section" indent="1" id="maven-repos-unauthenticated">Unauthenticated repos</h3>
<p>
Kobalt already knows the location of the most popular Maven repos (Maven Central, JCenter, JBoss) but you can add repos with the <code>repos()</code> directive:
@ -374,8 +519,8 @@ You can specify more than one project in a build file, simply by declaring them:
</p>
<pre class="brush:java">
val p1 = javaProject { ... }
val p2 = kotlinProject { ... }
val p1 = project { ... }
val p2 = project { ... }
</pre>
<p>
@ -383,7 +528,7 @@ If some of your projects need to be built in a certain order, you can specify de
</p>
<pre class="brush:java">
val p2 = kotlinProject(p1) { ... }
val p2 = project(p1) { ... }
</pre>
<p>
@ -408,8 +553,8 @@ Here are the options that you can pass to <code>./kobaltw</code>:
<table style="font-size: 14px" class="table table-striped">
<colgroup>
<col span="1" style="width: 25%;">
<col span="1" style="width: 10%;">
<col span="1" style="width: 30%;">
<col span="1" style="width: 5%;">
<col span="1" style="width: 10%;">
<col span="1" style="width: 20%;">
<col span="1" style="width: 40%;">
@ -432,9 +577,9 @@ Here are the options that you can pass to <code>./kobaltw</code>:
<td>Use this option if you are trying to build a project whose <code>Build.kt</code> is not in <code>kobalt/src</code>.</td>
</tr>
<tr>
<td><code>--checkVersions</code></td>
<td><code><span style="white-space:nowrap">--checkVersions</span></code></td>
<td>Boolean</td>
<td>false</td>td>
<td>false</td>
<td>Display all the new versions of your dependencies.</td>
<td>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:
<pre class="brush:plain">
@ -454,10 +599,17 @@ New versions found:
</tr>
<tr>
<td><code>--init</code></td>
<td>Boolean</td>
<td>false</td>
<td>Initialize a project for Kobalt.</td>
<td>This option will create a build file in the current directory (unless one already exists) and will install the Kobalt wrapper.</td>
<td>Comma-separated strings of template names.</td>
<td>null</td>
<td>Initialize a project for Kobalt with the given templates.</td>
<td>The parameter to this argument is a list of template names separated by commas, e.g. <code>"java,myProject"</code>. Each template will be invoked in order so they can generate their files.</td>
</tr>
<tr>
<td><code><span style="white-space:nowrap">--listTemplates</span></code></td>
<td></td>
<td>N/A</td>
<td>List all the templates available.</td>
<td>Templates displayed by this command can then be passed as an argument to the <code>--init</code> parameter.</td>
</tr>
<tr>
<td><code>--log</code></td>
@ -466,6 +618,28 @@ New versions found:
<td>Specify the log level.</td>
<td>The default level is 1. Level 0 will quiet everything and 2 and 3 will display increasingly verbose output.</td>
</tr>
<tr>
<td><code><span style="white-space:nowrap">--noIncremental</span></code></td>
<td>Boolean</td>
<td>false</td>
<td>Turn off incremental builds.</td>
<td>If this flag is specified, Kobalt will run all the tasks, even those that are incremental and would have
been skipped.</td>
</tr>
<tr>
<td><code>--plugins</code></td>
<td>Comma-separated list of plugin id's</td>
<td></td>
<td>Specify the plug-ins to load.</td>
<td>This is similar to specifying these plug-in id's in a build file except that no build file is needed.</td>
</tr>
<tr>
<td><code><span style="white-space:nowrap">--pluginJarFiles</span></code></td>
<td>Comma-separated list of plugin jar files</td>
<td></td>
<td>Specify the plug-ins to load.</td>
<td>This is similar to specifying these plug-in id's in a build file except that no build file is needed.</td>
</tr>
<tr>
<td><code>--resolve</code></td>
<td>Maven id<br/>(e.g.&nbsp;<code>"com.beust:kobalt:0.228"</code>)</td>
@ -489,7 +663,43 @@ New versions found:
</tr>
</table>
<h2 class="section" id="testing">Testing</h2>
<p>
Kobalt automatically detects how to run your tests based on the test dependencies that you declared:
</p>
<pre class="brush:java">
dependenciesTest {
compile("org.testng:testng:6.9.9")
}</pre>
<p>
By default, Kobalt supports TestNG, JUnit and Spek. You can also configure how your tests run
with the <code>test{}</code> directive:
</p>
<pre class="brush:java">
test {
args("-excludegroups", "broken", "src/test/resources/testng.xml")
}</pre>
<p>
The full list of configuration parameters can be found in the <a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/TestDirective.kt#L6">TestConfig</a> class.
</p>
<p>
Additionally, you can define multiple test configurations, each with a different name. Each
configuration will create an additional task named <code>"test"</code> followed by the name of
that configuration. For example:
</p>
<pre class="brush:java">
test {
args("-excludegroups", "broken", "src/test/resources/testng.xml")
}
test {
name = "All"
args("src/test/resources/testng.xml")
}</pre>
<p>
The first configuration has no name, so it will be launched with the task <code>"test"</code>,
while the second one can be run with the task <code>"testAll"</code>.
</p>
<h2 class="section" id="publishing">Publishing</h2>
<p>
@ -502,7 +712,7 @@ First of all, make sure you specified the group, artifactId and version of your
</p>
<pre class="brush:java">
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:
</p>
<pre class="brush:plain">
./kobaltw uploadJcenter
./kobaltw uploadBintray
</pre>
<h2 class="section" id="profiles">Profiles</h2>
@ -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:
</p>
<pre class="brush:java">
val p = javaProject {
val p = project {
name = if (experimental) "project-exp" else "project"
version = "1.3"
</pre>

146
getting-started/index.html
View file

@ -40,97 +40,109 @@
<nav id="kobalt-navbar" class="navbar navbar-default">
</nav>
<div class="col-md-9">
<h2 class="section" id="downloading">1. Download Kobalt</h2>
<h2 class="section" id="installing">1. Install Kobalt</h2>
<h3 class="section" indent="1" id="homebrew">With HomeBrew</h3>
<p>
<a href="https://github.com/cbeust/kobalt/releases/latest">Download the zip file</a> then unzip it in a location we'll call <code>KOBALT_HOME</code>:
</p>
If you are on MacOS and have <code>brew</code> installed:
<pre class="brush:plain">
cd $KOBALT_HOME
$ brew install kobalt
$ which kobaltw
/usr/local/bin/kobaltw</pre>
</p>
<h3 class="section" indent="1" id="manually">Manually</h3>
<p>
<a href="https://github.com/cbeust/kobalt/releases/latest">Download the zip file</a>, unzip it and add the <code>bin</code> directory to your <code>$PATH</code> variable so that you can invoke the command <code>kobaltw</code>:
</p>
<pre class="brush:plain">
cd yourLocation
unzip kobalt-xxx.zip
cd kobalt-xxx
export PATH=$PWD/bin:$PATH
</pre>
<p>
<em>Note: Kobalt doesn't need any environment variable to run, the environment variable used above
is only here for clarity.</em>
</p>
<h2 class="section" id="initialize">2. Initialize your project</h2>
<p>
Change to your project directory and call the <code>kobaltw</code> command with <code>--init</code>:
</p>
<h2 class="section" id="initialize">2. Initialize your project</h2>
<p>
Change to your project directory and call the <code>kobaltw</code> command with <code>--init</code>:
</p>
<pre class="brush:plain">
cd ~/java/project
$KOBALT_HOME/kobaltw --init
</pre>
<p>
This command will do two things:
</p>
<ol>
<li>Create a default <code>kobalt/src/Build.kt</code> file based on what was found in your project.
<li>Install the Kobalt Wrapper in your current directory (a script called <code>kobaltw</code>) and a few additional files in the <code>kobalt/wrapper</code> directory. From now on, you can just use <code>./kobaltw</code> to build and you can ignore <code>$KOBALT_HOME</code>.
</ol>
<p>
You can now attempt to build your project with Kobalt:
</p>
kobaltw --init java</pre>
to initialize a Java project, or
<pre class="brush:plain">
./kobaltw assemble
</pre>
If your project follows a regular build structure (e.g. <a href="https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html">Maven's hierarchy</a>), this should compile your file and create a .jar file. If not, you will have to make a few edits to your <code>Build.kt</code>.
As of this writing, Kobalt supports Java and Kotlin projects.
cd ~/java/project
kobaltw --init kotlin</pre>
<p>
to initialize a Kotlin project.
</p>
<div class="bs-callout bs-callout-warning">
<h4>Note</h4>
<h2 class="section" id="edit">3. Edit kobalt/src/Build.kt</h2>
Kobalt supports projects with both Kotlin and Java sources. For such projects,
use either <code>java</code> or <code>kotlin</code> as the <code>--init</code> argument and refer to the <a href="../plug-ins/index.html#mixed-projects">mixed projects documentation</a> for more details.
</div>
<p>
This command will do two things:
</p>
<ol>
<li>Create a default <code>kobalt/src/Build.kt</code> file based on what was found in your project.</li>
<li>Install the Kobalt Wrapper in your current directory (a script called <code>kobaltw</code>) and a few additional files in the <code>kobalt/wrapper</code> directory.</li>
</ol>
<p>
From now on, you can just use <code>./kobaltw</code> to build and you can ignore the <code>kobaltw</code> on your path, which is only useful to install Kobalt on new projects. Since you will now build each project with its own <code>./kobaltw</code> command, they will use their own version of Kobalt.
</p>
<h2 class="section" id="edit">3. Edit kobalt/src/Build.kt</h2>
Here is the <code>Build.kt</code> for the <a href="https://github.com/hhariri/wasabi/blob/master/kobalt/src/Build.kt">Wasabi HTTP framework</a>:
<p>
If your project uses a standard folder structure, you can skip this section and try to build your project directly.
</p>
<p>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...)</p>
<p>
Here is the <code>Build.kt</code> for the <a href="https://github.com/cbeust/jcommander/blob/master/kobalt/src/Build.kt">JCommander project</a>:
</p>
<pre class="brush:java">
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 {
}
}
}
</pre>
<h2 class="section" id="idea-plugin">4. Sync your build file</h2>
jcenter {
publish = true
}
}</pre>
<h2 class="section" id="build">4. Build your project</h2>
<p>
If you're using Intellij IDEA, make sure you've <a href="../idea-plug-in/index.html">installed the Kobalt plugin</a> and then go to <code>Kobalt -> Sync Build File</code>. 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:
</p>
<pre class="brush:java">
./kobaltw assemble</pre>
<h2 class="section" id="import-in-idea">5. IDEA users: Import your project in IDEA</h2>
<p>
<p>
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.
</p>
<h2 class="section" id="idea-plugin">6. IDEA users: Sync your build file</h2>
<p>
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.
</p>
<h2 class="section" id="next-steps">5. Next steps</h2>
<h2 class="section" id="next-steps">7. Next steps</h2>
<p>
From this point, you can either <a href="../idea-plug-in/index.html">learn how to install the Kobalt IDEA plug-in</a> or read <a href="../documentation/index.html">Kobalt's documentation</a>.
</p>

52
home/index.html
View file

@ -62,7 +62,7 @@
<div class="col-md-9">
<p>
<em style="font-size: 1.5em">
<em style="font-size: 1em">
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 @@
</em>
</p>
<p>
<em style="font-size: 1.5em">
<em style="font-size: 1em">
Here are some of Kobalt's most prominent features.
</em>
</p>
<h2 class="section" id="features">Features</h2>
<h2 class="section" id="buildFile" indent="1">Build file auto-completion in your IDE</h2>
<p>
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!
</p>
<p>
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.
</p>
<p>
Here is an example of the auto-completion dialog:
</p>
<p align="center">
<img src="../pics/auto-completion.png" class="img-rounded"/>
</p>
<p>
And see the following section to get a feel for Kobalt's build file syntax.
</p>
<h2 class="section" id="syntax" indent="1">Clean, minimal syntax for build files</h2>
<p>
For example, here is <a href="http://jcommander.org">JCommander's</a> 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,6 +112,30 @@ val jcommander = javaProject {
<p>
This build file also includes a directive to upload your artifacts to Bintray automatically.
</p>
<h2 class="section" id="buildFile" indent="1">Build file auto-completion in your IDE</h2>
<p>
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!
</p>
<p>
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.
</p>
<p>
Here is an example of the auto-completion dialog:
</p>
<p align="center">
<img src="../pics/auto-completion.png" class="img-rounded"/>
</p>
<p>
And see the following section to get a feel for Kobalt's build file syntax.
</p>
<h2 class="section" id="incremental" indent="1">Incremental tasks</h2>
<p>
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
<li><a href="https://github.com/cbeust/jcommander/blob/master/kobalt/src/Build.kt">JCommander</a>.</li>
<li><a href="https://github.com/cbeust/testng/blob/master/kobalt/src/Build.kt">TestNG</a> (this build file shows an example of adding a custom task in the build itself).</li>
<li><a href="https://github.com/cbeust/klaxon/blob/master/kobalt/src/Build.kt">Klaxon</a></li>
<li><a href="https://github.com/cbeust/kobalt-android">u2020 (Android show case application)</a></li>
<li>... and of course, <a href="https://github.com/cbeust/kobalt/blob/master/kobalt/src/Build.kt">Kobalt itself</a> (this build file demonstrates multi projects and project dependencies).</li>
</ul>

29
idea-plug-in/index.html
View file

@ -64,7 +64,7 @@
<div class="col-md-9">
<h2>How to install and use the Kobalt IDEA plug-in</h2>
<h2 class="section" id="installation">Installation</h2>
<h3 class="section" id="installation">Installation</h3>
<p>
Open the "Plugins" section of the IDEA preferences and find the "Kobalt" plug-in.
</p>
@ -72,13 +72,26 @@
<img src="../pics/install-plugin.png" class="img-rounded kb-wide"/>
</p>
<p>
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 <code>Build.kt</code> build file in it, IDEA
will offer to import it as a Kobalt project.
</p>
<p align="center">
<img src="../pics/kobalt-menu.png" class="img-rounded"/>
<p align="center">
<img src="../pics/kobalt-import-1.png" class="img-rounded"/>
</p>
<p align="center">
<img src="../pics/kobalt-import-2.png" class="img-rounded"/>
</p>
<p>
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:
</p>
<h2 class="section" id="features">Features</h2>
<p align="center">
<img src="../pics/kobalt-main-window.png" class="img-rounded"/>
</p>
<h3 class="section" id="features">Features</h3>
<p>
The Kobalt IDEA plug-in offers the following features:
<ul>
@ -86,7 +99,7 @@
<li>Automatic completion of <code>Build.kt</code></li>
</ul>
</p>
<h3 class="section" indent="1" id="sync-build-file">Synchronization of build files</h3>
<h4 class="section" indent="1" id="sync-build-file">Synchronization of build files</h4>
<p>
The plug-in will locate your <code>kobalt/src/Build.kt</code> 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 {
<img src="../pics/structure-4.png" class="img-rounded"/>
</p>
<h3 class="section" indent="1" id="autocompletion">Auto completion of Build.kt</h3>
<h4 class="section" indent="1" id="autocompletion">Auto completion of Build.kt</h4>
<p>
The plug-in will automatically turn on auto-completion of your <code>kobalt/src/Build.kt</code>
file. Once this is
@ -165,7 +178,7 @@ val lc = lineCount {
</li>
</ul>
<h2 class="section">Source code and bug reports</h2>
<h3 class="section">Source code and bug reports</h3>
<p>
The source code <a href="http://github.com/cbeust/kobalt-intellij-plugin">can be found on github</a>.
If you need to report a bug, please make sure you include the log file, which you can find under

BIN
pics/kobalt-import-1.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 30 KiB

BIN
pics/kobalt-import-2.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 42 KiB

BIN
pics/kobalt-main-window.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 39 KiB

562
plug-in-development/index.html
View file

@ -30,54 +30,120 @@
<link rel="icon" href="/favicon.ico">
-->
</head>
<body>
<div class="container">
<!-- Static navbar -->
<nav id="kobalt-navbar" class="navbar navbar-default">
</nav>
<!-- Main component for a primary marketing message or call to action -->
<h2>How to write a Kobalt plug-in</h2>
<!-- Main content -->
<div class="col-md-9">
<h2 class="section" id="tutorial">Tutorial</h2>
<body>
<div class="container">
<!-- Static navbar -->
<nav id="kobalt-navbar" class="navbar navbar-default">
</nav>
<!-- Main component for a primary marketing message or call to action -->
<h2>How to write a Kobalt plug-in</h2>
<!-- Main content -->
<div class="col-md-9">
<h2 class="section" id="tutorial">Tutorial</h2>
<p>
If you are curious to get a quick feel for what a Kobalt plug-in looks like, I suggest you go read how to
<a href="../ten-minutes/index.html">write and publish a plug-in in ten minutes</a> and then you can come back here
and keep reading.
</p>
<h2 class="section" id="idea-set-up">Setting up IDEA</h2>
<h3 class="section" indent="1" id="launch-configuration">Launch configuration</h3>
<p>
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:
</p>
<pre class="brush:java">
fun main(argv: Array&lt;String&gt;) {
com.beust.kobalt.main(argv)
}
</pre>
<p>
If you are curious to get a quick feel for what a Kobalt plug-in looks like, I suggest you go read how to
<a href="../ten-minutes/index.html">write and publish a plug-in in ten minutes</a> and then you can come back here
and keep reading.
In order for this code to compile, you will have to switch the dependency of your plug-in from
<code>kobalt-plugin-api</code> to just <code>kobalt</code>, which is the actual application (and which
therefore contains the <code>main()</code> entry point).
</p>
<pre class="brush:java">
// Normal dependency
compile("com.beust:kobalt-plugin-api:$KOBALT_VERSION")
<h2 class="section" id="philosophy">Plug-in architecture</h3>
// Development dependency
compile("com.beust:kobalt:$KOBALT_VERSION")
</pre>
<p>
<p>
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 <code>R.java</code> 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
<a href="https://en.wikipedia.org/wiki/Hollywood_principle">"Hollywood Principle"</a>: "Don't call us, we'll call you".
</p>
<p>
These "actors" are exactly what the <code>kobalt-plugin.xml</code> 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.
</p>
You might find it convenient to leverage Kobalt's ability to use regular Kotlin variables to make things easier:
</p>
<pre class="brush:java">
val dev = false
val kobaltDependency = if (dev) "kobalt" else "kobalt-plugin-api"
<h3 class="section" id="introduction" indent="1">Parts</h2>
val p = project {
// ...
compile("com.beust:$kobaltDependency:$KOBALT_VERSION")
}
</pre>
<p>
Then you can simply set the <code>dev</code> to <code>true</code> during development and back to <code>false
</code> when you are ready to publish your plug-in.
</code>
</p>
<p>
Then resync your build file in IDEA and your <code>main()</code> function should now build and be launchable.
You can right click on that class file and select "Debug &lt;your class name&gt;", 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. <code>"assemble"</code>).
</p>
<h3 class="section" indent="1" id="local-dependencies">Local dependencies</h3>
<p>
<ul>
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 <code>file()</code> and <code>homeDir
()</code> directives convenient:
</p>
<pre class="brush:java">
// Regular dependency
compile("com.example:myPlugin:0.1")
// Development dependency
compile(file(homeDir("kotlin/myPlugin/kobaltBuild/libs/myPlugin-0.1.jar"))
</pre>
<p>
With this latter configuration, simply build your plug-in to generate the jar file with <code>./kobaltw
assemble</code>, 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.
</p>
<h2 class="section" id="philosophy">Plug-in architecture</h3>
<p>
<p>
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 <code>R.java</code> 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
<a href="https://en.wikipedia.org/wiki/Hollywood_principle">"Hollywood Principle"</a>: "Don't call us, we'll call you".
</p>
<p>
These "actors" are exactly what the <code>kobalt-plugin.xml</code> 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.
</p>
</p>
<h3 class="section" id="introduction" indent="1">Parts</h2>
<p>
<ul>
<li><a href="#plugin-xml"><b>kobalt-plugin.xml</b></a>. A file that describes all the components (called "plug-in actors") of your plug-in, such as contributors.</li>
<li><a href="#directives"><b>Directives</b></a>. Kotlin functions that users of your plug-in can invoke in their build file, such as <code>kotlinProject</code> or <code>dependencies</code>. These functions typically configure some data that your plug-in will later use to perform its functions.</li>
<li><a href="#directives"><b>Directives</b></a>. Kotlin functions that users of your plug-in can invoke in their build file, such as <code>project</code> or <code>dependencies</code>. These functions typically configure some data that your plug-in will later use to perform its functions.</li>
<li><a href="#tasks"><b>Tasks</b></a>. These tasks are invoked from the command line and ask your plug-ins to perform certain actions.</li>
<li><a href="#properties"><b>Properties</b></a>. Plug-ins can export properties and read properties from other plug-ins.</li>
</ul>
</p>
</ul>
</p>
<h3 class="section" id="kobalt-plugin-xml" indent="1">kobalt-plugin.xml</h2>
<p>
The <code>kobalt-plugin.xml</code> file (stored in <code>META-INF</code> 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 <code>IPluginActor</code>'s interfaces:
</p>
<h3 class="section" id="kobalt-plugin-xml" indent="1">kobalt-plugin.xml</h2>
<p>
The <code>kobalt-plugin.xml</code> file (stored in <code>META-INF</code> 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 <code>IPluginActor</code>'s interfaces:
</p>
<pre class="brush:xml">
&lt;plugin-actors&gt;
&lt;class-name&gt;com.beust.kobalt.plugin.java.JavaPlugin&lt;/class-name&gt;
@ -109,9 +175,9 @@ class JavaPlugin : ICompilerContributor, IDocContributor {</pre>
With this declaration, we know that the <code>JavaPlugin</code> contributes a compiler and a doc generator.
</p>
<pre class="brush:java">
class JavaBuildGenerator: IInitContributor {</pre>
class JavaBuildGenerator: ITemplateContributor {</pre>
<p>
This class is declaring that it wants to take part in the <code>--init</code> selection process, discussed below.
This class is declaring that it wants to take part in the <code>--init</code> process (i.e. it can generate a template), discussed below.
</p>
<h2 class="section" id="actor-list">List of plug-in actors</h2>
<p>
@ -124,85 +190,105 @@ class JavaBuildGenerator: IInitContributor {</pre>
<td>Description</td>
</thead>
<tr>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IBuildConfigFieldContributor.kt">
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IAssemblyContributor.kt">IAssemblyContributor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a> </td>
<td>
Plug-ins that want be invoked when the <code>assemble</code> task is called.
</td>
</tr>
<tr>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IBuildConfigContributor.kt">
IBuildConfigContributor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a> </td>
<td>
Plug-ins that want to generate their own <code>BuildConfig</code> file.
</td>
</tr>
<tr>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IBuildConfigFieldContributor.kt">
IBuildConfigFieldContributor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IInterceptor</code></a> </td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IInterceptor</code></a> </td>
<td>
Plug-ins that want to add custom fields to the generated <code>BuildConfig</code> class.
</td>
</tr>
<tr>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IBuildDirectoryInterceptor.kt">IBuildDirectoryInterceptor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IInterceptor</code></a> </td>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IBuildDirectoryInterceptor.kt">IBuildDirectoryInterceptor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IInterceptor</code></a> </td>
<td>
Plug-ins that need to generate class files in a different directory than the default one should
implement this interface.
</td>
</tr>
<tr>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IClasspathContributor.kt">IClasspathContributor
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IClasspathContributor.kt">IClasspathContributor
</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a> </td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a> </td>
<td> Classpath contributors let you specify additional jar files or directories that will be used by
the <code>"compile"</code> task.
</td>
</tr>
<tr>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IClasspathInterceptor.kt">IClasspathInterceptor
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IClasspathInterceptor.kt">IClasspathInterceptor
</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IInterceptor</code></a> </td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IInterceptor</code></a> </td>
<td>
Plug-ins that want to modify the classpath before Kobalt uses it should implement this interface.
</td>
</tr>
<tr>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/ICompilerContributor.kt">ICompilerContributor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a> </td>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/ICompilerContributor.kt">ICompilerContributor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a> </td>
<td>
Plug-ins that know how to turn files into bytecodes should implement this interface.
Plug-ins that want be invoked when the <code>compile</code> task is called.
</td>
</tr>
<tr>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/ICompilerFlagContributor.kt">ICompilerFlagContributor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/ICompilerFlagContributor.kt">ICompilerFlagContributor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a>
</td>
<td>
Plug-ins that need to add flags to the compiler.
</td>
</tr>
<tr>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/ICompilerInterceptor.kt">ICompilerInterceptor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IInterceptor</code></a> </td>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IIncrementalTaskContributor.kt">IIncrementalTaskContributor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a> </td>
<td>
Plug-ins that implement this interface provide incremental tasks.
</td>
</tr>
<tr>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/ICompilerInterceptor.kt">ICompilerInterceptor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IInterceptor</code></a> </td>
<td>
Plug-ins that implement this interface get a chance to alter the dependencies of a project (<code>dependencies{}</code>, <code>dependenciesTest{}</code>, ...) before Kobalt sees them.
</td>
</tr>
<tr>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IDocContributor.kt">IDocContributor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a> </td>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IDocContributor.kt">IDocContributor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a> </td>
<td>
Plug-ins that know how to generate documentation out of source files should implement this interface.
</td>
</tr>
<tr>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IInitContributor.kt">IInitContributor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a> </td>
<td>Kobalt supports the <code>--init</code> 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...
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IMavenIdInterceptor.kt">IMavenIdInterceptor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IMavenIdInterceptor.kt"><code>IInterceptor</code></a> </td>
<td>
Plug-ins that need to rewrite Maven id's should implement this interface.
</td>
</tr>
<tr>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IProjectContributor.kt">IProjectContributor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a> </td>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IProjectContributor.kt">IProjectContributor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a> </td>
<td>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.</td>
</tr>
<tr>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IRepoContributor.kt">IRepoContributor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a> </td>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IRepoContributor.kt">IRepoContributor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a> </td>
<td>
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 <code>ANDROID_HOME</code> environment variable has been
@ -211,16 +297,16 @@ class JavaBuildGenerator: IInitContributor {</pre>
</td>
</tr>
<tr>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IRunnerContributor.kt">IRunnerContributor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a> </td>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IRunnerContributor.kt">IRunnerContributor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a> </td>
<td>
Plug-ins that can operate when the <code>"run"</code> task gets invoked should implement that interface.
</td>
</tr>
<tr>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/ISourceDirectoryContributor.kt">
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/ISourceDirectoryContributor.kt">
ISourceDirectoryContributor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a>
<td><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a>
</td>
<td>
Plug-ins that add source directories.
@ -228,44 +314,61 @@ class JavaBuildGenerator: IInitContributor {</pre>
</tr>
<tr>
<tr>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/ISourceDirectoryInterceptor.kt">
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/ISourceDirectoryInterceptor.kt">
ISourceDirectoryInterceptor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IInterceptor</code></a> </td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IInterceptor</code></a> </td>
<td>
Plug-ins that want to add, remove or alter the source directories should implement this interface.
</td>
</tr>
<tr>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/ITestRunnerContributor.kt">
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/ITaskContributor.kt">ITaskContributor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a> </td>
<td>
Plug-ins that implement this interface provide tasks.
</td>
</tr>
<tr>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/ITemplateContributor.kt">ITemplateContributor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a> </td>
<td>When invoked with <code>--init</code> 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 <code>Build.kt</code>
file suitable for a brand new Java project.
</td>
</tr>
<tr>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/ITestRunnerContributor.kt">
ITestRunnerContributor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a> </td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a> </td>
<td>
Plug-ins that can operate when the <code>"test"</code> task gets invoked should implement that interface.
</td>
</tr>
<tr>
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/ITestSourceDirectoryContributor.kt">
<td><code><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/ITestSourceDirectoryContributor.kt">
ITestSourceDirectoryContributor</a></code></td>
<td><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a>
<td><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/IPluginActor.kt"><code>IContributor</code></a>
</td>
<td>
Plug-ins that add test source directories.
</td>
</tr>
</table>
<h2 class="section" id="selection-process">Selection process</h2>
<p>
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
<em>affinity</em> to that task for a given project.
</p>
<p>
Contributors that want to participate in a selection process need to implement the following interface:
</p>
<h2 class="section" id="selection-process">Selection process</h2>
<p>
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
<em>affinity</em> to that task for a given project.
</p>
<p>
Contributors that want to participate in a selection process need to implement the following interface:
</p>
<pre class="brush:java">
interface IProjectAffinity {
/**
@ -274,39 +377,39 @@ interface IProjectAffinity {
*/
fun affinity(project: Project, context: KobaltContext) : Int
}</pre>
<p>
For example, the JavaPlugin implements the <code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/ICompilerContributor.kt">ICompilerContributor</a></code> interface and then overrides
the <code>affinity()</code> method to make sure it gets run for Java projects but ignored for others:
</p>
<p>
For example, the JavaPlugin implements the <code><a href="https://github.com/cbeust/kobalt/blob/master/modules/kobalt-plugin-api/src/main/kotlin/com/beust/kobalt/api/ICompilerContributor.kt">ICompilerContributor</a></code> interface and then overrides
the <code>affinity()</code> method to make sure it gets run for Java projects but ignored for others:
</p>
<pre class="brush:java">
override fun affinity(project: Project, context: KobaltContext) =
if (project.sourceSuffix == ".java") 1 else 0</pre>
<h2 class="section" id="directives">Directives</h2>
<p>
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, <a href="https://kotlinlang.org/docs/reference/type-safe-builders.html">as described here</a>.
</p>
<p>
Imagine that you want to offer a boolean parameter <code>publish</code> to users of your plug-in, you start by creating a class to hold that parameter:
</p>
<h2 class="section" id="directives">Directives</h2>
<p>
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, <a href="https://kotlinlang.org/docs/reference/type-safe-builders.html">as described here</a>.
</p>
<p>
Imagine that you want to offer a boolean parameter <code>publish</code> to users of your plug-in, you start by creating a class to hold that parameter:
</p>
<pre class="brush:java">
class Info(val publish: Boolean)
</pre>
<p>
Next, you create a directive that returns such a class and which also allows to configure it via the type safe builder pattern:
</p>
<p>
Next, you create a directive that returns such a class and which also allows to configure it via the type safe builder pattern:
</p>
<pre class="brush:java">
@Directive
public fun myConfig(init: Info.() -> Unit) = Info().apply { init() }</pre>
<p>
The <code>@Directive</code> 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 <code>myConfig</code> function that accepts a closure as an argument. It creates an <code>Info</code>
object, calls the <code>init()</code> function on it (which runs all the code inside that closure) and then return that <code>Info</code> object.
</p>
<p>
Users can now specify the following in their build file:
<p>
The <code>@Directive</code> 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 <code>myConfig</code> function that accepts a closure as an argument. It creates an <code>Info</code>
object, calls the <code>init()</code> function on it (which runs all the code inside that closure) and then return that <code>Info</code> object.
</p>
<p>
Users can now specify the following in their build file:
</p>
<pre class="brush:java">
// Build.kt
<imp></imp>ort.com.example.plugin.myConfig
import.com.example.plugin.myConfig
myConfig {
publish = true
}</pre>
@ -333,135 +436,140 @@ public fun myConfig(init: Info.() -> Unit) = Info().apply {
(Kobalt.findPlugin("my-plug-in") as MyPlugin).info = info
this
}</pre>
<p>
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 <code>Info</code> field, but you could instead choose to call
a function, just set one boolean instead of the whole object, etc...
</p>
<h2 class="section" id="tasks">Tasks</h2>
<p>
Tasks are provided by plug-ins and can be invoked from the command line, e.g. <code>./kobaltw assemble</code>. There are two kinds of tasks: static and dynamic.
</p>
<h3 class="section" indent="1">Static tasks</h3>
<p>
Static tasks are functions declared directly in your plug-in class and annotated with the <code>@Task</code> annotation. Here is an example:
</p>
<p>
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 <code>Info</code> field, but you could instead choose to call
a function, just set one boolean instead of the whole object, etc...
</p>
<h2 class="section" id="tasks">Tasks</h2>
<p>
Tasks are provided by plug-ins and can be invoked from the command line, e.g. <code>./kobaltw assemble</code>. There are two kinds of tasks: static and dynamic.
</p>
<h3 class="section" indent="1">Static tasks</h3>
<p>
Static tasks are functions declared directly in your plug-in class and annotated with the <code>@Task</code> annotation. Here is an example:
</p>
<pre class="brush:java">
@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()
}
</pre>
<p>
A Kobalt task needs to accept a <code>Project</code> in parameter and return a <code>TaskResult</code>, which indicates whether this task completed successfully.
</p>
<p>
The <code>@Task</code> annotation accepts the following attributes:
<dl class="dl-horizontal">
<p>
A Kobalt task needs to accept a <code>Project</code> in parameter and return a <code>TaskResult</code>, which indicates whether this task completed successfully.
</p>
<p>
The <code>@Task</code> annotation accepts the following attributes:
<dl class="dl-horizontal">
<dt>name</dt>
<dd>The name of the task, which will be used to invoke it from the command line.</dd>
<dt>description</dt>
<dd>The description of this command, which will be displayed if the user invokes the usage for the <code>kobaltw</code> command.</dd>
<dt>dependsOn</dt>
<dd>A list of all the tasks that this task depends on.</dd>
<dt>reverseDependsOn</dt>
<dd>Make the following tasks depend on this task.</dd>
<dt>runBefore</dt>
<dd>A list of all the tasks that this task should run prior to.</dd>
<dt>runAfter</dt>
<dd>A list of all the tasks that should run before this task does.</dd>
<dt>alwaysRunAfter</dt>
<dd>A list of all the tasks that will always be run after this task if it's invoked.</dd>
</dl>
</p>
<p>
The difference between <code>runAfter</code> and <code>alwaysRunAfter</code> is subtle but important. <code>runAfter</code>
is just a declaration of dependency. It's basically the reverse of <code>runBefore</code> 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 <code>runBefore</code>
annotation on it). Since you can't say <code>"a runBefore b"</code> because you don't own task "a",
you say <code>"b runAfter a"</code>.
</p>
<p>
For example, <code>compileTest</code> is declared as a <code>runAfter</code> for the task <code>compile</code>.
This means that it doesn't make sense to run <code>compileTest</code> unless <code>compile</code> has run first.
However, if a user invokes the task <code>compile</code>, they probably don't want to invoke <code>compileTest</code>,
so a dependency is exactly what we need here: invoking <code>compileTest</code> will trigger <code>compile</code>
but not the other way around.
</p>
<p>
However, there are times where you want to define a task that will <strong>always</strong> run after a given task.
For example, you could have a <code>signJarFile</code> 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 <code>assemble</code>
target, you want your <code>signJarFile</code> 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 <code>alwaysRunAfter</code>.
Note that there is no <code>alwaysRunBefore</code> annotation since <code>runBefore</code>
achieves the same functionality.
</p>
<p>
Here are a few different scenarios to illustrate how the three attributes work for the task <code>exampleTask</code>:
</p>
<p align="center">
<strong>Result of the command <code>./kobaltw --dryRun compile</code></strong>
</p>
<table width="100%" class="table table-bordered table-condensed">
</dl>
</p>
<p>
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.
</p>
<p>
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, <code>"assemble"</code> depends on <code>"compile"</code>, which means that whenever you invoke <code>"assemble"</code>, <code>"compile"</code>
will be automatically run first. This is a dependency and it is controlled by <code>"dependsOn"</code> and
<code>"reverseDependsOn"</code>. You can see <code>"reverseDependsOn"</code> as a way to insert your task before an existing task.
</p>
<p>
Orderings, controlled by <code>"runBefore"</code> and <code>"runAfter"</code> 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.
</p>
<p>
Here are a few different scenarios to illustrate how the three attributes work for the task <code>example</code>:
</p>
<p align="center">
<strong>Result of the command <code>./kobaltw --dryRun compile</code></strong>
</p>
<table width="100%" class="table table-bordered table-condensed">
<thead>
<td align="center">Configuration for <code>exampleTask</code></td>
<td align="center">Configuration for <code>example</code></td>
<td align="center">Result</td>
<td align="center">Note</td>
</thead>
<tr>
<td align="center">runBefore = "compile"</td>
<td align="center">dependsOn = "compile"</td>
<td>
<pre class="brush:plain">kobalt-line-count:clean
kobalt-line-count:exampleTask
kobalt-line-count:compile</pre>
<pre class="brush:plain">clean
compile
example</pre>
</td>
<td>
Make the <code>"example"</code> task depend on <code>"compile"</code>.
</td>
</tr>
<tr>
<td align="center">reverseDependsOn = "compile"</td>
<td>
<pre class="brush:plain">clean
example
compile</pre>
</td>
<td>
Insert the <code>"example"</code> task before <code>"compile"</code>.
</td>
</tr>
<tr>
<td align="center">runAfter = "compile"</td>
<td>
<pre class="brush:plain">kobalt-line-count:clean
kobalt-line-count:compile</pre>
<pre class="brush:plain">clean
compile</pre>
</td>
</tr>
<tr>
<td align="center">alwaysRunAfter = "compile"</td>
<td>
<pre class="brush:plain">kobalt-line-count:clean
kobalt-line-count:compile
kobalt-line-count:exampleTask</pre>
Make <code>"example"</code> run after <code>"compile"</code> but only if it's invoked explicitly.
</td>
</tr>
</table>
<h3 class="section" indent="1">Dynamic tasks</h3>
<p>
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 <code>@Task</code>
annotation on it). Plug-ins declare dynamic tasks by implementing the <code>ITaskContributor</code>
intrface:
</p>
</table>
<h3 class="section" indent="1">Dynamic tasks</h3>
<p>
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 <code>@Task</code>
annotation on it). Plug-ins declare dynamic tasks by implementing the <code>ITaskContributor</code>
intrface:
</p>
<pre class="brush:java">
interface ITaskContributor {
fun tasksFor(context: KobaltContext) : List&lt;DynamicTask&gt;
fun tasksFor(context: KobaltContext) : List&lt;DynamicTask&gt;
}</pre>
<p>
For example:
</p>
<p>
For example:
</p>
<pre class="brush:java">
override fun tasksFor(context: KobaltContext) = listOf(
DynamicTask(
name = "dynamicTask",
description = "Description",
alwaysRunAfter = listOf("compile"),
reverseDependsOn = listOf("compile"),
closure = { project: Project ->
println("Running dynamicTask")
TaskResult()
}))</pre>
<p>
<code>DynamicTask</code> mirrors the <code>@Task</code> attributes: <code>name</code>, <code>description</code> and
dependencies. The only addition is the <code>closure</code> parameter, which specifics the code that will
run if your task gets invoked. That closure needs to follow the same constraints that a <code>@Task</code> method
obeys: it takes a <code>Project</code> parameter and returns a <code>TaskResult</code>.
</p>
<p>
Once you have implemented <code>ITaskContributor</code>, you can see your dynamic task in the list of tasks and run it directly:
</p>
<p>
<code>DynamicTask</code> mirrors the <code>@Task</code> attributes: <code>name</code>, <code>description</code> and
dependencies. The only addition is the <code>closure</code> parameter, which specifics the code that will
run if your task gets invoked. That closure needs to follow the same constraints that a <code>@Task</code> method
obeys: it takes a <code>Project</code> parameter and returns a <code>TaskResult</code>.
</p>
<p>
Once you have implemented <code>ITaskContributor</code>, you can see your dynamic task in the list of tasks and run it directly:
</p>
<pre class="brush:plain">
$ ./kobaltw --tasks
===== kobalt-line-count =====
@ -470,32 +578,38 @@ $ ./kobaltw --tasks
$ ./kobaltw dynamicTask
Running dynamictask
</pre>
<h2 class="section" id="properties">Properties</h2>
<p>
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:
</p>
<ul>
<h2 class="section" id="properties">Properties</h2>
<p>
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:
</p>
<ul>
<li><strong>Project properties</strong>: project-specific properties.</li>
<li><strong>Plug-in properties</strong>: general properties that are applicable to no project
in particular.</li>
</ul>
<h3 class="section" indent="1" id="project-properties">Project properties</h3>
<p>
<code>Project</code> instances have a property called <code>projectProperties</code> that is an
instance of the <code>ProjectProperties</code> class. Plugins can put and get values on this
object in order to store project specific properties.
</p>
<pre class="brush:java">
</ul>
<h3 class="section" indent="1" id="project-properties">Project properties</h3>
<p>
<code>Project</code> instances have a property called <code>projectProperties</code> that is an
instance of the <code>ProjectProperties</code> class. Plugins can put and get values on this
object in order to store project specific properties.
</p>
<pre class="brush:java">
fun taskAssemble(project: Project) : TaskResult {
project.projectProperties.put(PACKAGES, packages)
project.projectProperties.put("packages", packages)
</pre>
<h3 class="section" indent="1" id="plugin-properties">Plug-in properties</h3>
<p>
The <code>PluginProperties</code> instance can be found on the <code>KobaltContext</code>
object that your plug-in receives in its <code>apply()</code> method. Once you have an instance of this
class, you can read or write variables into it:
</p>
<p>
Another plug-in can then query this property as follows:
</p>
<pre class="brush:java">
val packages = project.projectProperties.put("packages")
</pre>
<h3 class="section" indent="1" id="plugin-properties">Plug-in properties</h3>
<p>
The <code>PluginProperties</code> instance can be found on the <code>KobaltContext</code>
object that your plug-in receives in its <code>apply()</code> method. Once you have an instance of this
class, you can read or write variables into it:
</p>
<pre class="brush:java">
override fun apply(project: Project, context: KobaltContext) {
// Export a property for other plug-ins to use
@ -510,9 +624,9 @@ override fun apply(project: Project, context: KobaltContext) {
<code>@ExportedProjectProperty</code>annotation:
</p>
<pre class="brush:java">
companion object {
@ExportedProjectProperty
const val BUILD_DIR = "buildDir"
companion object {
@ExportedProjectProperty
const val BUILD_DIR = "buildDir"
</pre>
</div>
<!-- Table of contents -->
@ -533,4 +647,4 @@ override fun apply(project: Project, context: KobaltContext) {
<script src="../../assets/js/ie10-viewport-bug-workaround.js"></script>
-->
</div>
</body>
</body>

93
plug-ins/index.html
View file

@ -50,25 +50,25 @@
<h2 class="section" id="java-kotlin">Java and Kotlin</h2>
<p>
The Java and Kotlin plug-ins are extremely similar, the only difference is that you configure a Java project with the <code>javaProject</code> directive and a Kotlin project with <code>kotlinProject</code>:
Java and Kotlin are supported by default by Kobalt. You use the directive <code>project{}</code>
to declare a new project and Kobalt will automatically detect how to compile it:
</p>
<pre class="brush:java">
val p = javaProject(wrapper) {
val p = project(wrapper) {
name = "kobalt"
group = "com.beust"
artifactId = name
version = "0.1"
}
</pre>
}</pre>
<p>
Both these directives create an object of type <code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/Project.kt">Project</code></a>.
The <code>project{}</code> directive creates an object of type <code><a href="https://github.com/cbeust/kobalt/blob/master/src/main/kotlin/com/beust/kobalt/api/Project.kt">Project</code></a>.
</p>
<h3 class="section" id="project" indent="1">Project</h3>
<p>
A <code>Project</code> has two mandatory attributes: <code>name</code> and <code>version</code>. If you are planning to deploy your project to a Maven repository, you also have to specify its <code>group</code> (e.g. <code>com.beust</code>) and <code>artifactId</code> (e.g. <code>kobalt</code>).
A <code>Project</code> has two mandatory attributes: <code>name</code> and <code>version</code>. If you are planning to deploy your project to a Maven repository, you also have to specify its <code>group</code> (e.g. <code>"com.beust"</code>) and <code>artifactId</code> (e.g. <code>"kobalt"</code>).
</p>
<p>
@ -85,6 +85,23 @@ A <code>Project</code> has two mandatory attributes: <code>name</code> and <code
<dd>The dependencies for your tests</dd>
</dl>
<h4 class="section" id="mixed-projects" indent="2">Mixed language projects</h4>
<p>
A Kobalt project can mix Kotlin and Java in it, simply specify all the source
directories you need:
</p>
<pre class="brush:java">
val p = project(wrapper) {
name = "kobalt"
// ...
sourceDirectories {
path("src/main/java", "src/main/kotlin")
}
}</pre>
<p>
Kotlin and Java files can be in the same directories.
</p>
<h3 class="section" id="tasks" indent="1">Tasks</h3>
<p>
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
<dd>Clean the project</dd>
</dl>
<h3 class="section" id="templates" indent="1">Templates</h3>
<p>
Both the Java and Kotlin plug-ins provide templates named respectively "java" and "kotlin".
</p>
<pre class="brush:plain">
$ ./kobaltw --listTemplates
Available templates
Plug-in: Kobalt
"java" Generate a simple Java project
"kotlin" Generate a simple Kotlin project</pre>
<p>
They are both identical templates so we'll just look over the Kotlin one.
</p>
<p>
If you invoke <code>./kobaltw --init kotlin</code>, the following will happen:
</p>
<ul>
<li>If a <code>kobalt/src/Build.kt</code> build file doesn't exist, it will be created.</li>
<li>If no Kotlin (or Java) file is found under <code>src</code>, the template will create a simple
class with a <code>main</code> method and also a test class.</li>
</ul>
<pre class="brush:plain">
$ ./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)
</pre>
<h3 class="section" id="variants" indent="1">Variants</h3>
<p>
Variants let you configure your project to generate different artifacts compiled from different sources depending on the <em>variant</em> you selected.
@ -116,7 +180,7 @@ Once you have at least one project configured, the plug-in lets you invoke the f
<li>The build type.</li>
</ul>
<p>
<strong>Product flavors</strong> usually contains different source files and different logic (e.g. a "free version" and a "pro version". <strong>Build types</strong> 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:
<strong>Product flavors</strong> usually contain different source files and different logic (e.g. a "free version" and a "pro version". <strong>Build types</strong> 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:
</p>
<pre class="brush:java">
productFlavor("free") {
@ -146,10 +210,21 @@ assembleFreeDebug</pre>
<p>
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".
</p>
<p>
Variants can have they own <code>dependencies{}</code> section, which will be used only if this specific
variant is being compiled or assembled:
</p>
<pre class="brush:java">
productFlavor("debug") {
dependencies {
compile("joda-time:joda-time:2.9.3")
}
}
</pre>
<h3 class="section" id="build-config" indent="1">BuildConfig</h3>
<p>
If you defined at least one variant defined, a special file called <code>BuildConfig.java</code> (or
If you have at least one variant defined in your build file, a special file called <code>BuildConfig.java</code> (or
<code>BuildConfig.kt</code>) will be automatically generated.
</p>
<div class="bs-callout bs-callout-warning">
@ -377,7 +452,7 @@ assemble {
<h2 class="section" id="install" indent="1">install</h2>
<p>
The <code>install</code> section lets you specify how the artifacts get installed. If you don't specify any <code>install</code> directive, then the <code>install</code> task will do nothing on your project when invoked.
The <code>install</code> section lets you specify how the artifacts get installed. If you don't specify any <code>install</code> directive, then the <code>install</code> task will install your artifacts in the <code>lib</code> directory by default.
</p>
<pre class="brush:java">
install {

11
ten-minutes/index.html
View file

@ -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
</pre>
<p>
I create an empty <code>Main.kt</code> in the example above so that calling <code>./kobaltw --init</code> will detect the project as a Kotlin one. This way, the <code>Build.kt</code> 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 <code>group</code>, <code>artifactId</code> and <code>version</code> are correct. The only thing that the generator can't guess is the <code>group</code>, so let's go ahead and fix it:
</p>
<p>
<code>./kobaltw --init kotlin</code> creates an empty Kotlin project. Since we will be publishing this project to a Maven repository, we need to make sure that its <code>group</code>, <code>artifactId</code> and <code>version</code> are correct. The only thing that the generator can't guess is the <code>group</code>, so let's go ahead and fix it:
</p>
<pre class="brush:java">
val project = kotlinProject {
val project = project {
name = "kobalt-line-count"
group = "com.beust.kobalt"
artifactId = name