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

try to make site more intuitive

Browse source
This commit is contained in:
Juan Liska 2016-01-05 05:23:50 -06:00
parent de753349e3
commit 6112dda189
5 changed files with 614 additions and 558 deletions
Download patch file Download diff file Expand all files Collapse all files

47
documentation/index.html
View file

@ -57,9 +57,7 @@
<!-- Main component for a primary marketing message or call to action -->
<div class="jumbotron">
<h1>Kobalt</h1>
<p>A universal build system for the exigent developer.</p>
<img src="../pics/auto-completion.png" class="img-rounded"/>
<h1>Documentation</h1>
<!--
<p>
@ -71,47 +69,6 @@
<div class="col-md-9">
<h2 class="section" id="downloading">Downloading and installing Kobalt</h2>
<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>
<pre class="brush:plain">
cd $KOBALT_HOME
unzip kobalt-xxx.zip
</pre>
<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 there.
<li>Install the Kobalt Wrapper in your current directory (script `kobaltw`) and in the <code>kobalt/</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>
<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.
<h2 class="section" id="structure">Structure of a build file</h2>
<h3 class="section" indent="1" id="general-concepts">General concepts</h3>
@ -628,7 +585,7 @@ If you are interested in discussing Kobalt related topics with other fellow user
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
<script src="../bootstrap/dist/js/bootstrap.min.js"></script>
<script src="../js/kobalt.js"></script>
<script>generateKobalt(1);</script>
<script>generateKobalt();</script>
<!--
<script src="../bootstrap/dist/js/docs.min.js"></script>

156
getting-started/index.html Normal file
View file

@ -0,0 +1,156 @@
<html>
<head>
<title>
Kobalt, by Cedric Beust
</title>
<script type="text/javascript" src="../sh/scripts/shCore.js"></script>
<script type="text/javascript" src="../sh/scripts/shBrushJScript.js"></script>
<script type="text/javascript" src="../sh/scripts/shBrushJava.js"></script>
<script type="text/javascript" src="../sh/scripts/shBrushPlain.js"></script>
<script>
SyntaxHighlighter.defaults['gutter'] = false;
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
</script>
<!--[if lt IE 9]><script src="../assets/js/ie8-responsive-file-warning.js"></script><![endif]-->
<!--
<script src="../bootstrap/assets/js/ie-emulation-modes-warning.js"></script>
-->
<!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]-->
<!-- Favicons -->
<!--
<link rel="icon" href="/favicon.ico">
-->
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-238215-6', 'auto');
ga('send', 'pageview');
</script>
</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 -->
<div class="jumbotron">
<h1>Kobalt</h1>
<p>A universal build system for the exigent developer.</p>
<img src="../pics/auto-completion.png" class="img-rounded"/>
<!--
<p>
<a class="btn btn-lg btn-primary" href="../../components/#navbar" role="button">Download &raquo;</a>
</p>
-->
</div>
<div class="col-md-9">
<h2 class="section" id="downloading">1. Download Kobalt</h2>
<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>
<pre class="brush:plain">
cd $KOBALT_HOME
unzip kobalt-xxx.zip
</pre>
<h2 class="section" id="downloading">2. Initialize your project for Kobalt</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 there.
<li>Install the Kobalt Wrapper in your current directory (script `kobaltw`) and in the <code>kobalt/</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>
<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.
<h2 class="section" id="structure">3. Edit Build.kt</h2>
<pre class="brush:java">
import com.beust.kobalt.*
import com.beust.kobalt.plugin.kotlin.kotlinProject
val kobalt = kotlinProject {
name = "kobalt"
group = "com.beust"
artifactId = name
version = "0.62"
directory = homeDir("kotlin/kobalt")
}
</pre>
</div>
<!-- Table of contents -->
<div class="col-md-3" id="table-of-contents">
</div>
</div> <!-- /container -->
<!-- Bootstrap core JavaScript
================================================== -->
<!-- Placed at the end of the document so the pages load faster -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
<script src="../bootstrap/dist/js/bootstrap.min.js"></script>
<script src="../js/kobalt.js"></script>
<script>generateKobalt(1);</script>
<!--
<script src="../bootstrap/dist/js/docs.min.js"></script>
-->
<!-- IE10 viewport hack for Surface/desktop Windows 8 bug -->
<!--
<script src="../../assets/js/ie10-viewport-bug-workaround.js"></script>
-->
</body>

18
home/index.html
View file

@ -55,14 +55,20 @@
<!-- Main component for a primary marketing message or call to action -->
<div class="jumbotron">
<h1>What is Kobalt?</h1>
<h1>Kobalt: friendly, fast build system</h1>
<img src="../pics/auto-completion.png" class="img-rounded"/>
</div>
<!-- Main content -->
<div class="col-md-9">
<h2 class="section" id="overview">Overview</h2>
Kobalt is a build system system featuring build files written in Kotlin. It's focused on offering an intuitive DSL and plug-in architecture, fast builds and build file auto completion from your favorite IDE.
<h2 class="section" id="overview">Features</h2>
<ul>
<li><h4>Intuitive DSL and plug-in architecture</h4></li>
<li><h4>Fast builds</h4></li>
<li><h4>Build file auto-completion from your favorite IDE</h4></li>
<li><h4>A cleaner syntax than Ant, Maven, Gradle, or SBT</h4></li>
</ul>
</p>
<p>
@ -123,10 +129,6 @@ Kobalt is currently in Beta but I'm already using it to build most of my project
<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>
<p>
Where to next? Are you interested in writing some cool Kotlin code and contribute to Kobalt? Or maybe just download and run Kobalt on your own projects just to get a feel for it? Then proceed to <a href="../documentation/index.html">Kobalt's main documentation!</a>
</p>
<p>
</p>
@ -142,7 +144,7 @@ Kobalt is currently in Beta but I'm already using it to build most of my project
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
<script src="../bootstrap/dist/js/bootstrap.min.js"></script>
<script src="../js/kobalt.js"></script>
<script>generateKobalt(0);</script>
<script>generateKobalt();</script>
<!--
<script src="../../assets/js/docs.min.js"></script>

25
js/kobalt.js
View file

@ -9,6 +9,14 @@ var content = [
url: "../home/index.html",
title: "Home"
},
{
url: "../getting-started/index.html",
title: "Getting Started"
},
{
url: "../idea-plug-in/index.html",
title: "IDEA plug-in"
},
{
url: "../documentation/index.html",
title: "Documentation"
@ -21,17 +29,9 @@ var content = [
url: "../plug-in-development/index.html",
title: "Writing a Kobalt plug-in"
},
{
url: "../idea-plug-in/index.html",
title: "IDEA plug-in"
},
{
url: "../ten-minutes/index.html",
title: "Ten minutes"
},
{
url: "../contributing/index.html",
title: "Contributing"
title: "Contribute"
}
];
@ -50,14 +50,15 @@ var after = '</ul>'
+ '</nav>'
;
function generateNavBar(index) {
function generateNavBar() {
var result = before;
for (var i = 0; i < content.length; i++) {
var cls = "";
if (index == i) {
var c = content[i];
var cleanUrl = c.url.replace("../", "")
if (window.location.href.indexOf(cleanUrl) > -1) {
cls = 'class="active"';
}
var c = content[i];
result += '<li ' + cls + '><a href="' + c.url + '">' + c.title + '</a></li>';
}
result += after;

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

@ -1,115 +1,57 @@
<html>
<head>
<title>
<head>
<title>
Kobalt, by Cedric Beust
</title>
</title>
<script type="text/javascript" src="../sh/scripts/shCore.js"></script>
<script type="text/javascript" src="../sh/scripts/shBrushJScript.js"></script>
<script type="text/javascript" src="../sh/scripts/shBrushJava.js"></script>
<script type="text/javascript" src="../sh/scripts/shBrushPlain.js"></script>
<script type="text/javascript" src="../sh/scripts/shBrushXml.js"></script>
<script>
SyntaxHighlighter.defaults['gutter'] = false;
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
</script>
<!-- Optional Bootstrap Theme -->
<link href="data:text/css;charset=utf-8," data-href="../bootstrap/dist/css/bootstrap-theme.min.css" rel="stylesheet" id="bs-theme-stylesheet">
<!--[if lt IE 9]><script src="../assets/js/ie8-responsive-file-warning.js"></script><![endif]-->
<!--
<script src="../bootstrap/assets/js/ie-emulation-modes-warning.js"></script>
-->
<!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->
<!--[if lt IE 9]>
<!--[if lt IE 9]><script src="../assets/js/ie8-responsive-file-warning.js"></script><![endif]-->
<!--
<script src="../bootstrap/assets/js/ie-emulation-modes-warning.js"></script>
-->
<!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]-->
<!-- Favicons -->
<!--
<link rel="icon" href="/favicon.ico">
-->
</head>
<body>
<![endif]-->
<!-- Favicons -->
<!--
<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 -->
<div class="jumbotron">
<h1>Plug-in development</h1>
<p>How to write a Kobalt plug-in.</p>
</div>
<!-- Main content -->
<div class="col-md-9">
<h2 class="section" id="introduction">Introduction</h2>
<p>
Kobalt plug-ins are usually made of several parts:
<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="#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>
<p>
<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>
</p>
<h2 class="section" id="kobalt-plugin-xml">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;kobalt-plugin&gt;
&lt;name>kobalt&lt;/name&gt;
&lt;plugin-actors&gt;
&lt;class-name&gt;com.beust.kobalt.plugin.android.AndroidPlugin&lt;/class-name&gt;
&lt;class-name&gt;com.beust.kobalt.plugin.java.JavaBuildGenerator&lt;/class-name&gt;
&lt;/plugin-actors&gt;
&lt;/kobalt-plugin&gt;
</pre>
<p>
<code>IPluginActors</code> can be split in several categories:
</p>
<ul>
<li><strong>Plugins</strong>, which contain <code>@Task</code> annotations.</li>
<li><strong>Interceptors</strong>, which transform data that Kobalt gives them.</li>
<li><strong>Contributors</strong>, which produce additional data.</li>
</ul>
<p>
All plug-in actors are interfaces that extend <code>IPluginActor</code>. Plug-ins extend <code>IPlugin</code>,
interceptors extend <code>IInterceptor</code> and contributors extend <code>IContributor</code>. When Kobalt parses your
<code>kobalt-plugin.xml</code>, it instantiates all the classes found in the <code>&lt;plugin-actors&gt;</code> tag
and then introspects them to find out which <code>IPluginActor</code> interfaces that class implements.
</p>
<h3 class="section" id="philosophy">Plug-in architecture philosophy</h3>
<p>
<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
@ -117,15 +59,63 @@
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>
</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>
</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="#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>
<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;
&lt;class-name&gt;com.beust.kobalt.plugin.android.AndroidPlugin&lt;/class-name&gt;
&lt;class-name&gt;com.beust.kobalt.plugin.java.JavaBuildGenerator&lt;/class-name&gt;
&lt;class-name&gt;com.beust.kobalt.plugin.kotlin.KotlinBuildGenerator&lt;/class-name&gt;
&lt;/plugin-actors&gt;
</pre>
<p>
<code>IPluginActors</code> can be split in several categories:
</p>
<ul>
<li><strong>Plugins</strong>, which contain <code>@Task</code> annotations.</li>
<li><strong>Interceptors</strong>, which transform data that Kobalt gives them.</li>
<li><strong>Contributors</strong>, which produce additional data.</li>
</ul>
<p>
All plug-in actors are interfaces that extend <code>IPluginActor</code>. Plug-ins extend <code>IPlugin</code>,
interceptors extend <code>IInterceptor</code> and contributors extend <code>IContributor</code>. When Kobalt parses your
<code>kobalt-plugin.xml</code>, it instantiates all the classes found in the <code>&lt;plugin-actors&gt;</code> tag
and then introspects them to find out which <code>IPluginActor</code> interfaces that class implements.
</p>
<p>
If we look a the declarations of these classes, we can get an idea what they do
</p>
<pre class="brush:java">
class JavaPlugin : ICompilerContributor, IDocContributor {</pre>
<p>
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>
<p>
This class is declaring that it wants to take part in the <code>--init</code> selection process, discussed below.
</p>
<h2 class="section" id="actor-list">List of plug-in actors</h2>
<p>
Here is a list of actors (contributors and interceptors) that you can define in your plug-in.
@ -159,7 +149,6 @@
<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
@ -267,37 +256,6 @@
</td>
</tr>
</table>
<h2 class="section" id="example">Example</h2>
<p>
Kobalt itself uses a <code>kobalt-plugin.xml</code> to define contributors and interceptors, here is
an excerpt of it:
</p>
<pre class="brush:xml">
&lt;plugin-actors&gt;
&lt;class-name&gt;com.beust.kobalt.plugin.java.JavaPlugin&lt;/class-name&gt;
&lt;class-name&gt;com.beust.kobalt.plugin.android.AndroidPlugin&lt;/class-name&gt;
&lt;class-name&gt;com.beust.kobalt.plugin.java.JavaBuildGenerator&lt;/class-name&gt;
&lt;class-name&gt;com.beust.kobalt.plugin.kotlin.KotlinBuildGenerator&lt;/class-name&gt;
&lt;/plugin-actors&gt;
</pre>
<p>
In order to find out what these actually do, we just need to take a look at their definition and
see which interfaces they implement. For example:
</p>
<pre class="brush:java">
class JavaPlugin : ICompilerContributor, IDocContributor {</pre>
<p>
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>
<p>
This class is declaring that it wants to take part in the <code>--init</code> selection process, which is
discussed in the next section.
</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,
@ -323,45 +281,41 @@ interface IProjectAffinity {
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>
<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>
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>
</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>
</p>
<pre class="brush:java">
class Info(val publish: Boolean)
</pre>
<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>
</p>
<pre class="brush:java">
@Directive
public fun myConfig(init: Info.() -> Unit) = Info().apply { init() }</pre>
<p>
<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>
</p>
<p>
Users can now specify the following in their build file:
</p>
</p>
<pre class="brush:java">
// Build.kt
<imp></imp>ort.com.example.plugin.myConfig
myConfig {
publish = true
}</pre>
<p>
<p>
If you need access to the project being built, just declare an additional parameter of type <code>Project</code> to your directive and have the user pass that project:
</p>
</p>
<pre class="brush:java">
@Directive
public fun myConfig(project: Project, init: Info.() -> Unit) : Info {
@ -372,10 +326,9 @@ myConfig(project) {
publish = true
}
</pre>
<p>
<p>
The last piece of this puzzle is how you give this data back to your plug-in so it can act on it. In order to do this, you simply look up the name of your plug-in in the <code>Plugins</code> registry and invoke whatever function you need to run:
</p>
</p>
<pre class="brush:java">
@Directive
public fun myConfig(init: Info.() -> Unit) = Info().apply {
@ -383,19 +336,19 @@ public fun myConfig(init: Info.() -> Unit) = Info().apply {
(Kobalt.findPlugin("my-plug-in") as MyPlugin).info = info
this
}</pre>
<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>
</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>
</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>
<pre class="brush:java">
@Task(name = "lineCount", description = "Count the lines", runBefore = arrayOf("compile"))
fun lineCount(project: Project): TaskResult {
@ -403,11 +356,10 @@ fun lineCount(project: Project): TaskResult {
return TaskResult()
}
</pre>
<p>
<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>
</p>
<p>
The <code>@Task</code> annotation accepts the following attributes:
<dl class="dl-horizontal">
<dt>name</dt>
@ -421,22 +373,22 @@ fun lineCount(project: Project): TaskResult {
<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>
</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>
</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>
</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>
@ -444,19 +396,18 @@ fun lineCount(project: Project): TaskResult {
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>
</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">
</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">Result</td>
</thead>
<tr>
<td align="center">runBefore = "compile"</td>
<td>
@ -480,23 +431,21 @@ kobalt-line-count:compile
kobalt-line-count:exampleTask</pre>
</td>
</tr>
</table>
<h3 class="section" indent="1">Dynamic tasks</h3>
<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>
</p>
<pre class="brush:java">
interface ITaskContributor {
fun tasksFor(context: KobaltContext) : List&lt;DynamicTask&gt;
}</pre>
<p>
<p>
For example:
</p>
</p>
<pre class="brush:java">
override fun tasksFor(context: KobaltContext) = listOf(
DynamicTask(
@ -506,16 +455,16 @@ override fun tasksFor(context: KobaltContext) = listOf(
closure = { project: Project ->
println("Running dynamicTask")
TaskResult()
}))</pre>
<p>
}))</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>
<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>
<pre class="brush:plain">
$ ./kobaltw --tasks
===== kobalt-line-count =====
@ -524,9 +473,8 @@ $ ./kobaltw --tasks
$ ./kobaltw dynamicTask
Running dynamictask
</pre>
<h2 class="section" id="properties">Properties</h2>
<p>
<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>
@ -536,7 +484,6 @@ Running dynamictask
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
@ -545,55 +492,48 @@ Running dynamictask
<pre class="brush:java">
fun taskAssemble(project: Project) : TaskResult {
project.projectProperties.put(PACKAGES, packages)
</pre>
</pre>
<h3 class="section" indent="1" id="plugin-properties">Plug-in properties</h3>
<p>
<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>
<pre class="brush:java">
override fun apply(project: Project, context: KobaltContext) {
// Export a property for other plug-ins to use
context.pluginProperties.put(PLUGIN_NAME, "somePluginProperty", "someValue")
// Read a property from another plug-in
val sourceDir = context.pluginProperties.get("pluginName", "somePluginProperty")
}
</pre>
<h3 class="section" indent="1" id="documenting-properties">Documenting properties</h3>
<p>
Plug-ins that define properties should annotate them with the <code>@ExportedPluginProperty</code> or
<code>@ExportedProjectProperty</code>annotation:
</p>
</p>
<pre class="brush:java">
companion object {
@ExportedProjectProperty
const val BUILD_DIR = "buildDir"
</pre>
</div>
<!-- Table of contents -->
<div class="col-md-3" id="table-of-contents">
</div>
<!-- Bootstrap core JavaScript
================================================== -->
<!-- Placed at the end of the document so the pages load faster -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
<script src="../bootstrap/dist/js/bootstrap.min.js"></script>
<script src="../js/kobalt.js"></script>
<script>generateKobalt(3);</script>
<!--
<!-- Placed at the end of the document so the pages load faster -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
<script src="../bootstrap/dist/js/bootstrap.min.js"></script>
<script src="../js/kobalt.js"></script>
<script>generateKobalt();</script>
<!--
<script src="../bootstrap/dist/js/docs.min.js"></script>
-->
<!-- IE10 viewport hack for Surface/desktop Windows 8 bug -->
<!--
<script src="../../assets/js/ie10-viewport-bug-workaround.js"></script>
-->
-->
<!-- IE10 viewport hack for Surface/desktop Windows 8 bug -->
<!--
<script src="../../assets/js/ie10-viewport-bug-workaround.js"></script>
-->
</div>
</body>
</body>