AI2 SBT Plugins

The AI2 SBT plugins are intended to minimize build boilerplate accross projects. It is recommended to only enable "Archetype" plugins, which currently include:

• CliPlugin - for command line applications using the scopt library.
• LibraryPlugin - for libraries to be released / published using our Ai2ReleasePlugin
• WebServicePlugin - for web service applications built on spray, akka, and spray-json
• WebappPlugin (docs) - for web applications that have a service layer and a Node.js built web client.

It is fine to enable more than one plugin, including more than one archetype plugin. However, if we find the need to do so it could be an indicator that we have a new archetype to define.

All plugins also enable the CoreSettings plugin (docs), which contains AI2-wide common settings. In particular, this enables the StylePlugin (docs) to help with code formatting & style.

More documentation for individual plugins can be found in the docs directory.

Usage

Add the following to your project's project/plugins.sbt:

addSbtPlugin("org.allenai.plugins" % "allenai-sbt-plugins" % VERSION)

where VERSION is the current release version (see our bintray repo to find available versions).

Our archetype plugins are AutoPlugins. To enable an archetype plugin for a project, do the following:

If you have a root build.sbt

// in build.sbt
val service = project.in(file("service")).enablePlugins(WebServicePlugin)

If you have a project/Build.scala instead of a root build.sbt

import org.allenai.plugins.archetypes._

import sbt.Build

object ProjBuild extends Build {
  lazy val service = project.in(file("service")).enablePlugins(WebServicePlugin)
}

Install Git pre-commit hook to autoformat sources

Once you've added the plugins to a project, you can install a git pre-commit hook that will autoformat your code before allowing a commit via:

sbt generateAutoformatGitHook

Developing AI2 Plugins

Currently, all plugins are defined in the same SBT project. New plugins should be created in:

• src/main/scala/org/allenai/plugins if they are to be part of core settings or if they are a mixin plugin (in other words not an Archetype plugin).

• src/main/scala/org/allenai/plugins/archetypes if they are to be a project Archetype plugin

Testing

We use sbt-scripted for testing our SBT plugins. To run the tests:

$ sbt
> scripted

You could also just run sbt test which will trigger the scripted tests as well.

To keep test execution time down, we prefer to minimize the number of sbt-scripted test projects. If possible, try to write tests in the primary test project in src/sbt-test/sbt-plugins/simple.

If you write an isolated test, you can execute only that test via:

> scripted sbt-plugins/my-test

This assumes you've written your test in src/sbt-test/sbt-plugins/my-test. This is useful to speed up code/test iterating.

Publishing Releases

Following the Typesafe lead, we publish our plugins to a bintray.

Bintray does not like snapshot versions, so all of our published versions are releases.

Bintray Credentials

To publish new versions you will need a ~/.bintray/.credentials file with the following contents. Be sure to chmod 600 it! You can also use a personal Bintray login that has access to the allenai organization.

realm = Bintray API Realm
host = api.bintray.com
user = ai2-dev [or your bintray username]
password = [API Key for ai2-dev user ]

Where [API Key] is the API key for the ai2-dev account (or your account if using personal account) on Bintray. You can find it by asking someone! There is a username & password combo that might work to log in to the account as well.

1. Log into bintray as ai2-dev
2. Click on the ai2-dev account name in top-right corner
3. Click on Edit under ai2-dev
4. Click on API Key in navigation list

Releasing

1. Checkout the master branch of the repository
2. Make sure the upstream-tracking branch is master @ allenai/sbt-plugins

$ git branch --set-upstream-to=upstream/master

3. Cut the release:

$ sbt release

The plugin will set the appropriate defaults so just hit <ENTER> through the prompts. Also, some errors will be logged when the plugin creates a tag and pushes it to the upstream repository. This is not really an error but git outputting some text to stderr.

To verify your release, look for the new version in our bintray repo and also for the tag in the github repository