mirror of
https://github.com/ethauvin/kobalt-doc.git
synced 2025-04-24 11:37:11 -07:00
New hierarchy.
This commit is contained in:
Cedric Beust
parent
6d784ca363
commit
c7f726f1e6
20 changed files with 59 additions and 474 deletions
|
Before Width: | Height: | Size: 106 KiB After Width: | Height: | Size: 106 KiB |
0
dist/js/npm.js → bootstrap/dist/js/npm.js
vendored
0
dist/js/npm.js → bootstrap/dist/js/npm.js
vendored
|
|
@ -8,16 +8,18 @@
|
|||
|
||||
<!-- Bootstrap core CSS -->
|
||||
|
||||
<link href="../../dist/css/bootstrap.min.css" rel="stylesheet">
|
||||
<link href="../bootstrap/dist/css/bootstrap.min.css" rel="stylesheet">
|
||||
|
||||
|
||||
<!-- Optional Bootstrap Theme -->
|
||||
|
||||
<link href="data:text/css;charset=utf-8," data-href="../dist/css/bootstrap-theme.min.css" rel="stylesheet" id="bs-theme-stylesheet">
|
||||
<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="../../dist/assets/js/ie-emulation-modes-warning.js"></script>
|
||||
<!--
|
||||
<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]>
|
||||
|
|
@ -271,6 +273,35 @@ $ ./kobaltw --tasks
|
|||
|
||||
Notice the new <code>"coverage"</code> task, provided by the plug-in <code>kobalt-example-plugin</code> that we just included. With the simple action of declaring the plug-in, it is now fully loaded and available right away. Of course, such plug-ins can allow or require additional configuration with their own directives. Please read the plug-in developer documentation for more details.
|
||||
|
||||
<h2 id="multiple-projects"></h2>
|
||||
|
||||
You can specify more than one project in a build file, simply by declaring them:
|
||||
|
||||
<pre>
|
||||
val p1 = javaProject { ... }
|
||||
val p2 = kotlinProject { ... }
|
||||
</pre>
|
||||
|
||||
If some of your projects need to be built in a certain order, you can specify this when you create your project. For example:
|
||||
|
||||
<pre>
|
||||
val p2 = kotlinProject(p1) { ... }
|
||||
</pre>
|
||||
|
||||
<p>
|
||||
This declares that the Kotlin project <code>p2</code> depends on <code>p1</code>, which means that the project <code>p1</code> will be built first.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
You can also run tasks for a specific project only as follows:
|
||||
</p>
|
||||
|
||||
<pre>
|
||||
./kobaltw p2:assemble
|
||||
</pre>
|
||||
|
||||
This will run the <code>assemble</code> task only for the <code>p2</code>, instead of running it for all projects.
|
||||
|
||||
<h2 id="publishing">Publishing</h2>
|
||||
|
||||
<p>
|
||||
|
|
@ -353,7 +384,9 @@ A plug-in typically has three components:
|
|||
|
||||
<h3 id="base-plugin">BasePlugin</h3>
|
||||
|
||||
<p>
|
||||
The main class of your plugin extends <code>BasePlugin</code> and implements its <code>apply()</code> method and <code>name</code> variable:
|
||||
</p>
|
||||
|
||||
<pre>
|
||||
public class ExamplePlugin : BasePlugin() {
|
||||
|
|
@ -367,7 +400,9 @@ public class ExamplePlugin : BasePlugin() {
|
|||
|
||||
<h3 id="plugin-tasks">Plugin tasks</h3>
|
||||
|
||||
<p>
|
||||
Next, you can declare tasks with the <code>@Task</code> annotation:
|
||||
</p>
|
||||
|
||||
<pre>
|
||||
@Task(name = "coverage", description = "Run coverage",
|
||||
|
|
@ -456,6 +491,7 @@ val p = kotlinProject {
|
|||
<li><a href="#maven-repos">Maven repos</a>
|
||||
<li><a href="#using-plug-ins">Using plug-ins</a>
|
||||
<li><a href="#publishing">Publishing</a>
|
||||
<li><a href="#multiple-projects">Multiple projects</a>
|
||||
<li><a href="#writing-a-plug-in">Writing a plug-in</a>
|
||||
<ul>
|
||||
<li><a href="#building">Building</a>
|
||||
|
|
@ -473,9 +509,13 @@ val p = kotlinProject {
|
|||
================================================== -->
|
||||
<!-- 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="../../dist/js/bootstrap.min.js"></script>
|
||||
<script src="../../assets/js/docs.min.js"></script>
|
||||
<script src="../bootstrap/dist/js/bootstrap.min.js"></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>
|
||||
|
|
@ -8,16 +8,18 @@
|
|||
|
||||
<!-- Bootstrap core CSS -->
|
||||
|
||||
<link href="../../dist/css/bootstrap.min.css" rel="stylesheet">
|
||||
<link href="../bootstrap/dist/css/bootstrap.min.css" rel="stylesheet">
|
||||
|
||||
|
||||
<!-- Optional Bootstrap Theme -->
|
||||
|
||||
<link href="data:text/css;charset=utf-8," data-href="../dist/css/bootstrap-theme.min.css" rel="stylesheet" id="bs-theme-stylesheet">
|
||||
<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="../../dist/assets/js/ie-emulation-modes-warning.js"></script>
|
||||
<!--
|
||||
<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]>
|
||||
|
|
@ -136,9 +138,13 @@ Just a personal thing. After toying with the language for almost four years now,
|
|||
================================================== -->
|
||||
<!-- 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="../../dist/js/bootstrap.min.js"></script>
|
||||
<script src="../bootstrap/dist/js/bootstrap.min.js"></script>
|
||||
<!--
|
||||
<script src="../../assets/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>
|
||||
469
index.html
469
index.html
|
|
@ -1,467 +1,6 @@
|
|||
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<meta name="description" content="Kobalt">
|
||||
<html>
|
||||
<head>
|
||||
<title>Kobalt</title>
|
||||
<link rel="stylesheet" href="http://yui.yahooapis.com/pure/0.6.0/pure-min.css">
|
||||
<!--[if lte IE 8]>
|
||||
<link rel="stylesheet" href="/combo/1.18.13?/css/layouts/side-menu-old-ie.css">
|
||||
<![endif]-->
|
||||
<!--[if gt IE 8]><!-->
|
||||
<link rel="stylesheet" href="css/side-menu.css">
|
||||
<!--<![endif]-->
|
||||
<!--[if lt IE 9]>
|
||||
<script src="http://cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7/html5shiv.js"></script>
|
||||
<![endif]-->
|
||||
</head>
|
||||
<body>
|
||||
<div id="layout">
|
||||
<!-- Menu toggle -->
|
||||
<a href="#menu" id="menuLink" class="menu-link">
|
||||
<!-- Hamburger icon -->
|
||||
<span></span>
|
||||
</a>
|
||||
|
||||
<div class="pure-menu pure-menu-horizontal">
|
||||
<a href="#" class="pure-menu-heading pure-menu-link">BRAND</a>
|
||||
<ul class="pure-menu-list">
|
||||
<li class="pure-menu-item"><a href="#" class="pure-menu-link">News</a></li>
|
||||
<li class="pure-menu-item"><a href="#" class="pure-menu-link">Sports</a></li>
|
||||
<li class="pure-menu-item"><a href="#" class="pure-menu-link">Finance</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div id="menu">
|
||||
<div class="pure-menu">
|
||||
<a class="pure-menu-heading" href="#">Kobalt</a>
|
||||
|
||||
<ul class="pure-menu-list">
|
||||
<li class="pure-menu-item"><a href="#why-kobalt" class="pure-menu-link">Why Kobalt?</a></li>
|
||||
<li class="pure-menu-item"><a href="#documentation" class="pure-menu-link">Documentation</a></li>
|
||||
<ul>
|
||||
<li><a href="#downloading">Downloading</li>
|
||||
</ul>
|
||||
<li class="pure-menu-item" class="menu-item-divided pure-menu-selected">
|
||||
<a href="#" class="pure-menu-link">Services</a>
|
||||
</li>
|
||||
|
||||
<li class="pure-menu-item"><a href="#resize" class="pure-menu-link">Contact</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div id="main">
|
||||
<div class="header">
|
||||
<h1>Kobalt</h1>
|
||||
<h2>A build tool for the exigent developer</h2>
|
||||
</div>
|
||||
|
||||
<div class="content">
|
||||
<h2 id="why-kobalt" class="content-subhead">Why Kobalt?</h2>
|
||||
<p>
|
||||
Kobalt is a build system heavily inspired from Gradle and entirely 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.
|
||||
|
||||
<h3>Design goals</h3>
|
||||
|
||||
<ul>
|
||||
<li>Completely written in Kotlin: core, plug-ins and build files.
|
||||
<li>Auto completion from the IDE (possibly enhanced by a soon-to-come thin Kobalt IDE plug-in to present suggestions ordered more sensibly).
|
||||
<li>Reusing all the good ideas from Gradle, such as the DSL and the wrapper.
|
||||
<li>Fast builds.
|
||||
<li>Streamlining the build file, applying default over configuration as much as possible (for example, to install a plug-in, Gradle forces you to both declare it and apply it, something I've never understood).
|
||||
<li>A turnkey solution with all the common plug-ins pre-installed. No need to go hunting through dozens of outdated results for the elusive JCenter plug-in: with Kobalt, you can create a package and upload it to JCenter within ten minutes.
|
||||
<li>An agnostic build tool. Kobalt can be used to build Kotlin and Java projects today but it's capable to build anything: any language (JVM or not) or platform (Android, Spring, etc...).
|
||||
<li>The opportunity to have features that I've always missed from Gradle, such as Kobalt's <tt>--checkVersions</tt> command which will check for you if any of your dependencies have newer versions available.
|
||||
</ul>
|
||||
|
||||
<h3>Why Kobalt</h4>
|
||||
|
||||
As of this writing (October 2015), Kobalt is in alpha and changing a lot so I am mostly interested in getting the attention of developers who are interested in
|
||||
|
||||
<ul>
|
||||
<li>helping with Kobalt's core
|
||||
<li>writing plug-ins or extending existing ones
|
||||
<li>discussing the architecture and the design of Kobalt on the mailing-list
|
||||
</ul>
|
||||
|
||||
Kobalt is complete enough to build three of my personal projects (TestNG, JCommander and, of course, itself) but it will most likely come short of filling everyone's build needs at this time. That's the end goal but we're not there yet. You are welcome to use it on your own projects as long as you're okay with encountering issues and reporting them.
|
||||
|
||||
<p>
|
||||
|
||||
With this disclaimer, why did I decide to write Kobalt?
|
||||
|
||||
<h4>1. Scratching an itch</h4>
|
||||
|
||||
I give a lot of credit to Gradle for having open a brand new avenue in build tools but despite all its power and flexibility and the fact that I've used Gradle for more than five years, I've never really felt comfortable or fluent with it. Even today, I regularly find myself spending a lot of time on StackOverflow whenever I need to do something a bit out of the ordinary with my Gradle builds.
|
||||
|
||||
I suspect a part of it is due to Groovy which, even though it started gaining some static type features these past years, remains at its heart a dynamically typed language. This has two consequences:
|
||||
|
||||
<ul>
|
||||
<li>You don't receive a lot of assistance from your IDE when writing Gradle build files (auto completion broken most of the time).
|
||||
<li>Building is slow and hard to diagnose because of Gradle's mixed Java/Groovy code base.
|
||||
</ul>
|
||||
|
||||
<h4>2. An experiment</h4>
|
||||
|
||||
I wanted to see for myself if my discomfort with Gradle was justified or if, by trying to write a build tool myself, I would end up with a very similar tool with similar strengths and weaknesses. I still haven't made up my mind about this but I will certainly by the time Kobalt reaches 1.0.
|
||||
|
||||
<h4>3. A proof of concept</h4>
|
||||
|
||||
I have been a fervent believer that there is nothing that dynamically typed languages can do today that statically typed languages can't. Groovy's meta model and features have enabled a lot of clever tricks (DSL and others) for Gradle builds and I was really curious if I could put money where my mouth is by creating a similar project with Kotlin. This experiment is still ongoing but by now, I'm pretty convinced that the answer is a resounding "yes".
|
||||
|
||||
<h4>4. An excuse to write Kotlin</h4>
|
||||
|
||||
Just a personal thing. After toying with the language for almost four years now, I wanted to take my efforts to the next level and push the language to the limit. So far, the language has held all its promises and then some.
|
||||
|
||||
</p>
|
||||
|
||||
<h2 id="Documentation" class="content-subhead">Documentation</h2>
|
||||
|
||||
<h3 id="downloading">Downloading and installing Kobalt</h3>
|
||||
|
||||
<a href="https://bintray.com/cbeust/generic/kobalt/view">Download the zip file</a> (bottom left of the screen) then unzip it in a location we'll call <code>KOBALT_HOME</code>:
|
||||
|
||||
<pre>
|
||||
cd $KOBALT_HOME
|
||||
unzip kobalt-xxx.zip
|
||||
</pre>
|
||||
|
||||
Change to your project directory and call the <code>kobaltw</code> command with <code>--init</code>:
|
||||
|
||||
<pre>
|
||||
cd ~/java/project
|
||||
$KOBALT_HOME/kobaltw --init
|
||||
</pre>
|
||||
|
||||
This command will do two things:
|
||||
|
||||
<ol>
|
||||
<li>Create a default <code>Build.kt</code> file in your current directory 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>
|
||||
|
||||
You can now attempt to build your project with Kobalt:
|
||||
|
||||
<pre>
|
||||
./kobaltw assemble
|
||||
</pre>
|
||||
|
||||
If your project follows a regular build structure (e.g. Maven's hierarchy), this should compile your file and create a .jar file. If not, you will have to make a few edits to your <code>Build.kt</code>.
|
||||
|
||||
As of this writing, Kobalt supports Java and Kotlin projects.
|
||||
|
||||
<h2>Structure of a build file</h2>
|
||||
|
||||
<h3>General concepts</h3>
|
||||
|
||||
The build file is typically called <code>Built.kt</code> and it is a valid Kotlin file. Typically, it contains imports, the declaration of one or more projects and the declaration of additional configurations (e.g. packaging, publishing, etc...). Since it's a Kotlin file, it can also contain any class or function you need:
|
||||
|
||||
<pre>
|
||||
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>
|
||||
|
||||
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 (see below).
|
||||
<li>You can specify the directory of the project, 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 sometimes referred to as "directives"
|
||||
</ul>
|
||||
|
||||
<h3>Directives</h3>
|
||||
|
||||
Now that we have declared a project, we can use it to configure additional steps of our build, such as the packaging:
|
||||
|
||||
<pre>
|
||||
import com.beust.kobalt.plugin.packaging.packaging
|
||||
|
||||
// ...
|
||||
|
||||
val packKobalt = packaging(kobalt) {
|
||||
jar {
|
||||
}
|
||||
}
|
||||
</pre>
|
||||
|
||||
This is the simplest jar declaration you can have. You can trigger the creation of this jar file by invoking the task <code>"assemble"</code>. Note that we passed the <code>kobalt</code> variable to the <code>packaging</code> function, so we make it clear which project we are currently configuring for packaging. The <code>jar</code> directive accepts various settings, so let's be a bit more specific. And let's add a zip file too:
|
||||
|
||||
<pre>
|
||||
val packKobalt = packaging(kobalt) {
|
||||
jar {
|
||||
fatJar = true
|
||||
manifest {
|
||||
attributes("Main-Class", "com.beust.kobalt.KobaltPackage")
|
||||
}
|
||||
}
|
||||
zip {
|
||||
include("kobaltw")
|
||||
include(from("${kobalt.buildDirectory}/libs"),
|
||||
to("kobalt/wrapper"),
|
||||
"${kobalt.name}-${kobalt.version}.jar",
|
||||
"${kobalt.name}-wrapper.jar")
|
||||
}
|
||||
}
|
||||
</pre>
|
||||
|
||||
Our jar file is now declared to be a "fat jar" (which means it will include all its dependencies) and we specified a <code>Main-Class</code> to the jar Manifest, which means we will be able to invoke it with <code>java -jar kobalt-0.61.jar</code>. If you don't like this name, you can override it with a <code>name = "myName.jar"</code> statement.
|
||||
|
||||
<p>
|
||||
|
||||
The zip directive follows a similar structure, although here we are specifying which file we want to include. For more details on the <code>packaging</code> plug-in, please see its documentation.
|
||||
|
||||
<h3>Dependencies</h3>
|
||||
|
||||
You can declare compile and test dependencies as follows:
|
||||
|
||||
<pre>
|
||||
dependencies {
|
||||
compile("com.beust:jcommander:1.48",
|
||||
"com.beust:klaxon:0.14")
|
||||
}
|
||||
|
||||
dependenciesTest {
|
||||
compile("org.testng:testng:6.9.5")
|
||||
}
|
||||
</pre>
|
||||
|
||||
<h3>Maven repos</h3>
|
||||
|
||||
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:
|
||||
|
||||
<pre>
|
||||
val repos = repos("https://dl.bintray.com/cbeust/maven/")
|
||||
</pre>
|
||||
|
||||
<h2 id="plug-ins">Using plug-ins</h2>
|
||||
|
||||
Kobalt comes with a few preconfigured plug-ins but you will want to include external ones as well, which can be downloaded either from a Maven repository (Sonatype, JCenter, ...) or from a local file.
|
||||
|
||||
<p>
|
||||
|
||||
First of all, let's take a quick look at the tasks available in the default distribution (your actual output might differ somewhat):
|
||||
|
||||
<pre>
|
||||
$ ./kobaltw --tasks
|
||||
===== java =====
|
||||
compile Compile the project
|
||||
compileTest Compile the tests
|
||||
test Run the tests
|
||||
clean Clean the project
|
||||
|
||||
===== publish =====
|
||||
generatePom Generate the .pom file
|
||||
uploadJcenter Upload the artifacts to JCenter
|
||||
|
||||
===== packaging =====
|
||||
assemble Package the artifacts
|
||||
</pre>
|
||||
|
||||
Let's modify our build to include a plug-in. We do this by adding a call to the <code>plugins</code> directive on top of the build file:
|
||||
|
||||
<pre>
|
||||
val repos = repos("https://dl.bintray.com/cbeust/maven/")
|
||||
val p = plugins("com.beust:kobalt-example-plugin:0.42")
|
||||
</pre>
|
||||
|
||||
Now, run the <code>--tasks</code> command again:
|
||||
|
||||
<pre>
|
||||
$ ./kobaltw --tasks
|
||||
===== java =====
|
||||
compile Compile the project
|
||||
|
||||
===== publish =====
|
||||
generatePom Generate the .pom file
|
||||
uploadJcenter Upload the artifacts to JCenter
|
||||
|
||||
===== kobalt-example-plugin =====
|
||||
coverage Run coverage
|
||||
|
||||
===== packaging =====
|
||||
assemble Package the artifacts
|
||||
</pre>
|
||||
|
||||
Notice the new <code>"coverage"</code> task, provided by the plug-in <code>kobalt-example-plugin</code> that we just included. With the simple action of declaring the plug-in, it is now fully loaded and available right away. Of course, such plug-ins can allow or require additional configuration with their own directives. Please read the plug-in developer documentation for more details.
|
||||
|
||||
<h2 id="publishing">Publishing</h2>
|
||||
|
||||
Kobalt supports JCenter natively so you can upload your project and make it available on JCenter very easily.
|
||||
|
||||
<p>
|
||||
|
||||
First of all, make sure you specified the group, artifactId and version of your project, as required by Maven:
|
||||
|
||||
<pre>
|
||||
val kobalt = kotlinProject {
|
||||
group = "com.beust"
|
||||
artifactId = "kobalt"
|
||||
version = "0.72"
|
||||
</pre>
|
||||
|
||||
Next, create a file <code>local.properties</code> in the root directory of your project with the following keys:
|
||||
|
||||
<pre>
|
||||
bintray.user=...
|
||||
bintray.apikey=...
|
||||
</pre>
|
||||
|
||||
The values for the <code>user</code> and <code>apikey</code> keys can be found in your bintray profile, as described <a href="https://bintray.com/docs/usermanual/interacting/interacting_editingyouruserprofile.html#anchorAPIKEY">here</a>. Note that you should <b>not</b> check this <code>local.properties</code> file into your source control (so add it to <code>.gitignore</code>).
|
||||
|
||||
<p>
|
||||
|
||||
Make sure that your build creates a jar file (using `packaging`, as explained above).
|
||||
|
||||
<p>
|
||||
|
||||
Now, all you need to do is to upload your package:
|
||||
|
||||
<pre>
|
||||
./gradlew uploadJcenter
|
||||
</pre>
|
||||
|
||||
<h2 id="writing-plug-in">Writing a plug-in</h2>
|
||||
|
||||
A good starting point to write a plug-in is the <a href="https://bitbucket.org/cbeust/kobalt-example-plugin">kobalt-example-plugin project</a>, which shows a minimalistic plug-in.
|
||||
|
||||
<h3>Building</h3>
|
||||
|
||||
You only need to do two things to build a Kobalt plug-in:
|
||||
|
||||
<h4>1. Add Kobalt as a dependency:</h4>
|
||||
|
||||
<pre>
|
||||
dependencies {
|
||||
compile("com.beust:kobalt:0.61")
|
||||
}
|
||||
</pre>
|
||||
|
||||
<h4>2. Declare the main class of your plug-in in the Jar file's manifest:</h4>
|
||||
|
||||
<pre>
|
||||
val p = packaging(examplePlugin) {
|
||||
jar {
|
||||
manifest {
|
||||
attributes("Kobalt-Plugin-Class", "com.beust.kobalt.example.ExamplePlugin")
|
||||
}
|
||||
}
|
||||
}
|
||||
</pre>
|
||||
|
||||
<h3>Implementing</h3>
|
||||
|
||||
A plug-in typically has three components:
|
||||
|
||||
<ul>
|
||||
<li>Extending and implementing the methods of `BasePlugin`.
|
||||
<li>Specifying one or more tasks.
|
||||
<li>Specifying directives (functions that will be used from the build file).
|
||||
</ul>
|
||||
|
||||
<h4><code>BasePlugin</code></h4>
|
||||
|
||||
The main class of your plugin extends <code>BasePlugin</code> and implements its <code>apply()</code> method and <code>name</code> variable:
|
||||
|
||||
<pre>
|
||||
public class ExamplePlugin : BasePlugin() {
|
||||
override val name = "kobalt-example-plugin"
|
||||
|
||||
override fun apply(project: Project) {
|
||||
println("Applying plugin ${name} with project ${project}")
|
||||
}
|
||||
}
|
||||
</pre>
|
||||
|
||||
<h4>Plugin tasks</h4>
|
||||
|
||||
Next, you can declare tasks with the <code>@Task</code> annotation:
|
||||
|
||||
<pre>
|
||||
@Task(name = "coverage", description = "Run coverage",
|
||||
runAfter = arrayOf("compile"))
|
||||
public fun coverage(project: Project): TaskResult {
|
||||
println("Running the coverage on project ${project}")
|
||||
return TaskResult()
|
||||
}
|
||||
</pre>
|
||||
|
||||
<ul>
|
||||
<li>Tasks return a <code>TaskResult</code> object, which can be initialized with <code>false</code> if the task didn't succeed for some reason.
|
||||
<li>The name of the task is the same name that can be passed to the <code>kobaltw</code> command (e.g. <code>"./kobaltw coverage"</code>)
|
||||
<li>The description is what is displayed with <code>"./kobaltw --tasks"</code>
|
||||
<li><code>runAfter</code> and <code>runBefore</code> let you specify the dependencies of your task. In this example plug-in, we want to calculate the coverage of the project so it makes sense to run after the <code>"compile"</code> task.
|
||||
|
||||
<h4>Directives</h4>
|
||||
|
||||
Finally, you need to define functions that can be used from the build file (directives). You are encouraged to use the <a href="https://confluence.jetbrains.com/display/Kotlin/Type-safe+Groovy-style+builders">Kotlin DSL approach</a> to expose these functions so that the build file syntax can remain consistent. Typically, these functions will update data that your tasks can then use to do their job.
|
||||
|
||||
<p>
|
||||
|
||||
These can be either straight functions or extension functions. For example, here is the <code>kotlinProject</code> directive:
|
||||
|
||||
<pre>
|
||||
@Directive
|
||||
public fun kotlinProject(init: KotlinProject.() -> Unit): KotlinProject {
|
||||
val result = KotlinProject()
|
||||
result.init()
|
||||
return result
|
||||
}
|
||||
</pre>
|
||||
|
||||
This function returns a <code>KotlinProject</code> and the user can then override variables or invoke methods from this class in their build file:
|
||||
|
||||
<pre>
|
||||
val kobalt = kotlinProject {
|
||||
name = "kobalt"
|
||||
group = "com.beust"
|
||||
...
|
||||
</pre>
|
||||
|
||||
Using an extension function to define a directive allows you to add new functions to Kobalt classes. For example, currently, a project can have <code>"dependencies"</code> and <code>"dependenciesTest"</code>. For a coverage plug-in, we would want to add a <code>"dependenciesCoverage"</code> section, which can be easily done by defining an extension function on <code>Project<c/ode>:
|
||||
|
||||
<pre>
|
||||
@Directive
|
||||
public fun Project.dependenciesCoverage(ini: Dependencies.() -> Unit) : Dependencies {
|
||||
val result = Dependencies()
|
||||
result.init()
|
||||
return result
|
||||
}
|
||||
</pre>
|
||||
|
||||
And we can now use:
|
||||
|
||||
<pre>
|
||||
val p = kotlinProject {
|
||||
dependenciesCoverage("com.example:foo:0.1")
|
||||
}
|
||||
```
|
||||
</pre>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<script src="js/ui.js"></script>
|
||||
|
||||
|
||||
</body>
|
||||
<META http-equiv="refresh" content="0;URL=home/index.html">
|
||||
</head>
|
||||
</html>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue