Improve development experience for plugin authors

There are a number of things I noticed when I was playing with Kobalt plugins. I’m not a fan of big issues but I don’t feel that I have the technical insights to break it down into separate issues. Please feel free to split topics as you see fit.

I’ll be using kobalt jar for the full jar (e.g. kobalt-1.0.26.jar) and api jar (e.g. kobalt-plugin-api-1.0.26.jar) in the following description.

Documentation Please specify clearly how a plugin needs to depend on Kobalt (when to use the api jar and when to use the kobalt jar).

Things a plugin author should know:

• where to find the kobalt jar and the api jar (i.e. which repository they are published to and the exact coordinates).
• there are two versions out there (i.e. the api jar usually has a version that differs from the version of the kobalt jar)
• KOBALT_VERSION as specified in the current documentation does not work (because that variable is not available by default).

The result of the discussion was that the following coordinates should be used:

• compile("com.beust:kobalt:")
• compile("com.beust:kobalt-plugin-api:")

This resulted in weird problems that wrong versions of kobalt would be pulled in. I’m not sure what the result of the discussion really was, there probably need to be followup issues for that.

It might be a nice idea to have helper functions (something like kobaltAPI() and kobaltJAR()) for that.

Running your plugin The documentation currently states:

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>) { com.beust.kobalt.main(argv) }

The documentation should mention that you need to add the following block to your build script:

val bs = buildScript {
  plugins(file(homeDir("projects/linecount/kobaltBuild/libs/linecount-0.3-SNAPSHOT.jar")))
}

It should also mention that the path here needs to be absolute to work.

Source.

[cbeust]

@ethauvin Good suggestion. I just updated the documentation, although I decided not to use profile() just yet since it’s not properly supported in the IDEA plug-in yet.

Take a look:

http://beust.com/kobalt/plug-in-development/index.html#launch-configuration

[ethauvin]

I would suggest changing the docs to:

val dev by profile()
val kobaltDependency = if (dev) "kobalt" else "kobalt-plugin-api"
...
    dependencies {
        compile("com.beust:$kobaltDependency:")
    }