How to write a Kobalt plug-in


If you are curious to get a quick feel for what a Kobalt plug-in looks like, I suggest you go read how to write and publish a plug-in in ten minutes and then you can come back here and keep reading.

Setting up IDEA

Launch configuration

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:

fun main(argv: Array<String>) {

In order for this code to compile, you will have to switch the dependency of your plug-in from kobalt-plugin-api to just kobalt, which is the actual application (and which therefore contains the main() entry point):

val dev = false // or true for development
val kobaltDependency = if (dev) "kobalt" else "kobalt-plugin-api"

val p = project {
    dependencies {

Open the Kobalt side bar and sync your build file in IDEA. Your main() function should now build and be launchable. You can right click on that class file and select "Debug <your class name>", 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. "assemble").

Local dependencies

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 file() and homeDir () directives convenient:

    // Regular dependency

    // Development dependency

With this latter configuration, simply build your plug-in to generate the jar file with ./kobaltw assemble, 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.

Plug-in architecture

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 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 "Hollywood Principle": "Don't call us, we'll call you".

These "actors" are exactly what the kobalt-plugin.xml 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.



The kobalt-plugin.xml file (stored in META-INF 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 IPluginActor's interfaces:


IPluginActors can be split in several categories:

All plug-in actors are interfaces that extend IPluginActor. Plug-ins extend IPlugin, interceptors extend IInterceptor and contributors extend IContributor. When Kobalt parses your kobalt-plugin.xml, it instantiates all the classes found in the <plugin-actors> tag and then introspects them to find out which IPluginActor interfaces that class implements.

If we look a the declarations of these classes, we can get an idea what they do

class JavaPlugin : ICompilerContributor, IDocContributor {

With this declaration, we know that the JavaPlugin contributes a compiler and a doc generator.

class JavaBuildGenerator: ITemplateContributor {

This class is declaring that it wants to take part in the --init process (i.e. it can generate a template), discussed below.

List of plug-in actors

Here is a list of actors (contributors and interceptors) that you can define in your plug-in.

Interface name Type Description
IAssemblyContributor IContributor Plug-ins that want be invoked when the assemble task is called.
IBuildConfigContributor IContributor Plug-ins that want to generate their own BuildConfig file.
IBuildConfigFieldContributor IInterceptor Plug-ins that want to add custom fields to the generated BuildConfig class.
IBuildDirectoryInterceptor IInterceptor Plug-ins that need to generate class files in a different directory than the default one should implement this interface.
IClasspathContributor IContributor Classpath contributors let you specify additional jar files or directories that will be used by the "compile" task.
IClasspathInterceptor IInterceptor Plug-ins that want to modify the classpath before Kobalt uses it should implement this interface.
ICompilerContributor IContributor Plug-ins that want be invoked when the compile task is called.
ICompilerFlagContributor IContributor Plug-ins that need to add flags to the compiler.
IIncrementalTaskContributor IContributor Plug-ins that implement this interface provide incremental tasks.
ICompilerInterceptor IInterceptor Plug-ins that implement this interface get a chance to alter the dependencies of a project (dependencies{}, dependenciesTest{}, ...) before Kobalt sees them.
IDocContributor IContributor Plug-ins that know how to generate documentation out of source files should implement this interface.
IMavenIdInterceptor IInterceptor Plug-ins that need to rewrite Maven id's should implement this interface.
IProjectContributor IContributor 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.
IRepoContributor IContributor 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 ANDROID_HOME environment variable has been defined, will automatically add the repository inside the Android distribution so that support libraries and other artifacts can be found.
IRunnerContributor IContributor Plug-ins that can operate when the "run" task gets invoked should implement that interface.
ISourceDirectoryContributor IContributor Plug-ins that add source directories.
ISourceDirectoryInterceptor IInterceptor Plug-ins that want to add, remove or alter the source directories should implement this interface.
ITaskContributor IContributor Plug-ins that implement this interface provide tasks.
ITemplateContributor IContributor When invoked with --init 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 Build.kt file suitable for a brand new Java project.
ITestRunnerContributor IContributor Plug-ins that can operate when the "test" task gets invoked should implement that interface.
ITestSourceDirectoryContributor IContributor Plug-ins that add test source directories.

Selection process

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 affinity to that task for a given project.

Contributors that want to participate in a selection process need to implement the following interface:

interface IProjectAffinity {
     * @return an integer indicating the affinity of your actor for the given project. The actor that returns
     * the highest affinity gets selected.
    fun affinity(project: Project, context: KobaltContext) : Int

For example, the JavaPlugin implements the ICompilerContributor interface and then overrides the affinity() method to make sure it gets run for Java projects but ignored for others:

override fun affinity(project: Project, context: KobaltContext) =
if (project.sourceSuffix == ".java") 1 else 0


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, as described here.

Imagine that you want to offer a boolean parameter publish to users of your plug-in, you start by creating a class to hold that parameter:

class Info(val publish: Boolean)

Next, you create a directive that returns such a class and which also allows to configure it via the type safe builder pattern:

public fun myConfig(init: Info.() -> Unit) = Info().apply { init() }

The @Directive 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 myConfig function that accepts a closure as an argument. It creates an Info object, calls the init() function on it (which runs all the code inside that closure) and then return that Info object.

Users can now specify the following in their build file:

// Build.kt
myConfig {
    publish = true

If you need access to the project being built, just declare an additional parameter of type Project to your directive and have the user pass that project:

public fun myConfig(project: Project, init: Info.() -> Unit) : Info {
// ...
myConfig(project) {
    publish = true

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 Plugins registry and invoke whatever function you need to run:

public fun myConfig(init: Info.() -> Unit) = Info().apply {
    (Kobalt.findPlugin("my-plug-in") as MyPlugin).info = info

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 Info field, but you could instead choose to call a function, just set one boolean instead of the whole object, etc...


Tasks are provided by plug-ins and can be invoked from the command line, e.g. ./kobaltw assemble. There are two kinds of tasks: static and dynamic.

Static tasks

Static tasks are functions declared directly in your plug-in class and annotated with the @Task annotation. Here is an example:

@Task(name = "lineCount", description = "Count the lines", dependsOn = arrayOf("compile"))
fun lineCount(project: Project): TaskResult {
    // ...
    return TaskResult()

A Kobalt task needs to accept a Project in parameter and return a TaskResult, which indicates whether this task completed successfully.

The @Task annotation accepts the following attributes:

The name of the task, which will be used to invoke it from the command line.
The description of this command, which will be displayed if the user invokes the usage for the kobaltw command.
A list of all the tasks that this task depends on.
Make the following tasks depend on this task.
A list of all the tasks that this task should run prior to.
A list of all the tasks that should run before this task does.

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.

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, "assemble" depends on "compile", which means that whenever you invoke "assemble", "compile" will be automatically run first. This is a dependency and it is controlled by "dependsOn" and "reverseDependsOn". You can see "reverseDependsOn" as a way to insert your task before an existing task.

Orderings, controlled by "runBefore" and "runAfter" 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.

Here are a few different scenarios to illustrate how the three attributes work for the task example:

Result of the command ./kobaltw --dryRun compile

Configuration for example Result Note
dependsOn = "compile"
Make the "example" task depend on "compile".
reverseDependsOn = "compile"
Insert the "example" task before "compile".
runAfter = "compile"
Make "example" run after "compile" but only if it's invoked explicitly.

Dynamic tasks

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 @Task annotation on it). Plug-ins declare dynamic tasks by implementing the ITaskContributor intrface:

interface ITaskContributor {
    fun tasksFor(project: Project, context: KobaltContext) : List<DynamicTask>

For example:

override fun tasksFor(project: Project, context: KobaltContext) = listOf(
        name = "dynamicTask",
        description = "Description",
        group = "other",
        project = project,
        reverseDependsOn = listOf("compile"),
        closure = { project ->
            println("Running dynamicTask")

DynamicTask mirrors the @Task attributes: name, description and dependencies. The only addition is the closure parameter, which specifics the code that will run if your task gets invoked. That closure needs to follow the same constraints that a @Task method obeys: it takes a Project parameter and returns a TaskResult.

Once you have implemented ITaskContributor, you can see your dynamic task in the list of tasks and run it directly:

$ ./kobaltw --tasks
  ===== kobalt-line-count =====
    dynamicTask         Description
    lineCount           Count the lines
$ ./kobaltw dynamicTask
Running dynamictask


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:

Project properties

Project instances have a property called projectProperties that is an instance of the ProjectProperties class. Plugins can put and get values on this object in order to store project specific properties.

fun taskAssemble(project: Project) : TaskResult {
    project.projectProperties.put("packages", packages)

Another plug-in can then query this property as follows:

    val packages = project.projectProperties.put("packages")

Plug-in properties

The PluginProperties instance can be found on the KobaltContext object that your plug-in receives in its apply() method. Once you have an instance of this class, you can read or write variables into it:

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")

Documenting properties

Plug-ins that define properties should annotate them with the @ExportedPluginProperty or @ExportedProjectPropertyannotation:

companion object {
const val BUILD_DIR = "buildDir"