mirror of
https://github.com/ethauvin/kobalt-doc.git
synced 2025-04-25 12:07:10 -07:00
268 lines
8.4 KiB
HTML
268 lines
8.4 KiB
HTML
<html>
|
|
<head>
|
|
<title>
|
|
|
|
Kobalt, by Cedric Beust
|
|
|
|
</title>
|
|
|
|
<!-- Bootstrap core CSS -->
|
|
|
|
<link href="../bootstrap/dist/css/bootstrap.min.css" rel="stylesheet">
|
|
|
|
|
|
<!-- 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]>
|
|
<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>
|
|
|
|
|
|
<div class="container">
|
|
|
|
<!-- Static navbar -->
|
|
<nav class="navbar navbar-default">
|
|
<div class="container-fluid">
|
|
<div class="navbar-header">
|
|
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar">
|
|
<span class="sr-only">Toggle navigation</span>
|
|
<span class="icon-bar"></span>
|
|
<span class="icon-bar"></span>
|
|
<span class="icon-bar"></span>
|
|
</button>
|
|
<a class="navbar-brand">Kobalt<br></a>
|
|
</div>
|
|
<div id="navbar" class="navbar-collapse collapse">
|
|
<ul class="nav navbar-nav">
|
|
<li><a href="../home/index.html">Home</a></li>
|
|
<li><a href="../documentation/index.html">Documentation</a></li>
|
|
<li class="active"><a href="../plug-in/index.html">A plug-in in 10mn</a></li>
|
|
</ul>
|
|
</div><!--/.nav-collapse -->
|
|
</div><!--/.container-fluid -->
|
|
</nav>
|
|
|
|
<!-- Main component for a primary marketing message or call to action -->
|
|
<div class="jumbotron">
|
|
<h1>A Kobalt plug-in in ten minutes</h1>
|
|
<h2>This article demonstrates how to wrote a Kobalt plug-in from scratch and have it published on JCenter in less than ten minutes.</h2>
|
|
</div>
|
|
|
|
<!-- Main content -->
|
|
<div class="col-md-9">
|
|
|
|
|
|
<p>
|
|
In tnis example, we'll write a Kobalt plug-in that simply counts the number of source files and lines in your project. Starting from scratch, we'll have this plug-in published to JCenter and ready to use in ten minutes.
|
|
</p>
|
|
|
|
<p>
|
|
Let's start by creating our project:
|
|
</p>
|
|
|
|
<pre>
|
|
$ mkdir linecount
|
|
$ mkdir -p src/main/kotlin/com/beust/plugin/linecount
|
|
$ touch src/main/kotlin/com/beust/plugin/linecount/Main.kt
|
|
$ $KOBALT_HOME/kobaltw --init
|
|
</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>
|
|
|
|
<pre>
|
|
val project = kotlinProject {
|
|
name = "kobalt-line-count"
|
|
group = "com.beust.kobalt"
|
|
artifactId = name
|
|
version = "0.1"
|
|
...
|
|
</pre>
|
|
|
|
<p>
|
|
Next, we want the manifest of our jar file to point to our main Kobalt plug-in class:
|
|
</p>
|
|
|
|
<pre>
|
|
val packProject = packaging(project) {
|
|
jar {
|
|
manifest {
|
|
attributes("Main-Class", "com.beust.kobalt.plugin.linecount.Main")
|
|
}
|
|
}
|
|
}
|
|
</pre>
|
|
|
|
<p>
|
|
Now we're ready to code.
|
|
</p>
|
|
|
|
<p>
|
|
Let's start by writing the simplest plug-in we can:
|
|
</p>
|
|
|
|
<pre>
|
|
package com.beust.kobalt.plugin.linecount
|
|
|
|
import com.beust.kobalt.api.*
|
|
|
|
public class Main : BasePlugin() {
|
|
override val name = "kobalt-line-count"
|
|
|
|
override fun apply(project: Project, context: KobaltContext) {
|
|
println("*** Applying plugin ${name} with project ${project}")
|
|
}
|
|
}
|
|
</pre>
|
|
|
|
<p>
|
|
Before we can upload it, we need to create the package in bintray, <a href="https://bintray.com/docs/usermanual/uploads/uploads_creatinganewpackage.html">as explained here</a>. Once this is done, we are ready to do our first upload:
|
|
</p>
|
|
|
|
<pre>
|
|
$ ./kobaltw uploadJcenter
|
|
...
|
|
========== kobalt-line-count:uploadJcenter
|
|
kobalt-line-count: Found 2 artifacts to upload
|
|
All artifacts successfully uploaded
|
|
############# Time to Build: 3590 ms
|
|
</pre>
|
|
|
|
<p>
|
|
If you go to the maven section of your bintray account, you will now see that the new package has two unpublished files. Your new plug-in won't be visible by clients until you publish those files, so let's update our build file to automatically publish files from now on:
|
|
</p>
|
|
|
|
<pre>
|
|
val jc = jcenter(project) {
|
|
publish = true
|
|
}
|
|
</pre>
|
|
|
|
<p>
|
|
And now, let's implement our logic, which is pretty simple:
|
|
</p>
|
|
|
|
<pre>
|
|
// Main.kt
|
|
@Task(name = "lineCount", description = "Count the lines", runBefore = arrayOf("compile"))
|
|
fun lineCount(project: Project): TaskResult {
|
|
var fileCount = 0
|
|
var lineCount : Long = 0
|
|
val matcher = FileSystems.getDefault().getPathMatcher("glob:**.kt")
|
|
project.sourceDirectories.forEach {
|
|
Files.walkFileTree(Paths.get(it), object: SimpleFileVisitor<Path>() {
|
|
override public fun visitFile(path: Path, attrs: BasicFileAttributes): FileVisitResult {
|
|
if (matcher.matches(path)) {
|
|
fileCount++
|
|
lineCount += Files.lines(path).count()
|
|
}
|
|
return FileVisitResult.CONTINUE
|
|
}
|
|
})
|
|
}
|
|
log(1, "Found ${lineCount} lines in ${fileCount} files")
|
|
return TaskResult()
|
|
}
|
|
</pre>
|
|
|
|
<p>
|
|
We create a task called <code>"lineCount"</code> in which we look for all files ending in ".kt" in all the source directories of the project. Finally, we display a count of files and lines at the end by using <code>KobaltLogger.log()</code>, which is obtained by extending the trait <code>KobaltLogger</code>:
|
|
</p>
|
|
|
|
<pre>
|
|
public class Main : BasePlugin(), KobaltLogger {
|
|
</pre>
|
|
|
|
<p>
|
|
Let's bump our version to 0.2 (since version 0.1 is already uploaded and JCenter won't allow us to overwrite it) and upload our new plug-in:
|
|
</p>
|
|
|
|
|
|
<pre>
|
|
$ ./kobaltw uploadJcenter
|
|
...
|
|
kobalt-line-count: Compilation succeeded
|
|
========== kobalt-line-count:assemble
|
|
Created /Users/beust/kotlin/kobalt-line-count/kobaltBuild/libs/kobalt-line-count-0.2.jar
|
|
========== kobalt-line-count:generatePom
|
|
Wrote /Users/beust/kotlin/kobalt-line-count/kobaltBuild/libs/kobalt-line-count-0.2.pom
|
|
========== kobalt-line-count:uploadJcenter
|
|
kobalt-line-count: Found 2 artifacts to upload
|
|
All artifacts successfully uploaded
|
|
|
|
Time to Build: 5907 ms
|
|
</pre>
|
|
|
|
<p>
|
|
Finally, let's use our plug-in from another project. Since we didn't link this project to JCenter, it's uploaded in the user's maven repository, so we will have to add this maven repository to the build file where we want to use the plug-in. Adjust this line to point to your own maven repo:
|
|
</p>
|
|
|
|
<pre>
|
|
val repos = repos("https://dl.bintray.com/cbeust/maven/")
|
|
val plugins = plugins("com.beust.kobalt:kobalt-line-count:0.2")
|
|
</pre>
|
|
|
|
<p>
|
|
Now let's launch a build:
|
|
</p>
|
|
|
|
<pre>
|
|
```
|
|
$ ./kobaltw assemble
|
|
...
|
|
========== kobalt:lineCount
|
|
Found 4972 lines in 65 files
|
|
========== kobalt:compile
|
|
...
|
|
</pre>
|
|
|
|
<p>
|
|
Note that our plugin ran before the <code>compile</code> task, as we requested in the <code>@Task</code> annotation. We can also verify that it's activated and we can invoke the task directly instead of having it run as part of the build:
|
|
</p>
|
|
|
|
<pre>
|
|
$ ./kobaltw --tasks
|
|
===== kobalt-line-count =====
|
|
lineCount Count the lines
|
|
$ ./kobaltw lineCount
|
|
Found 4972 lines in 65 files
|
|
</pre>
|
|
|
|
<p>
|
|
And that's it! You can now iterate on your plug-in and upload it with additional <code>./kobaltw uploadJcenter</code>. This plug-in is <a href="https://github.com/cbeust/kobalt-linecount">available on github</a>.
|
|
</p>
|
|
|
|
<!-- 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="../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>
|