Using in Sbt

This page will explain how to enable miniboxing with your sbt project.

TL;DR:

  resolvers += Resolver.sonatypeRepo("snapshots"),
  libraryDependencies += "org.scala-miniboxing.plugins" %%
                         "miniboxing-runtime" % "0.4-SNAPSHOT",
  addCompilerPlugin("org.scala-miniboxing.plugins" %%
                    "miniboxing-plugin" % "0.4-SNAPSHOT"),

The Long Story

Miniboxing is a Scala compiler plugin and thus performs its transformations as part of the compilation pipeline. In order to use miniboxing, you will need to add two components:

the miniboxing runtime support library and
the miniboxing compiler plugin

Fortunately, both artifacts are published nightly on sonatype, so you can easily get them.

Depending on your project’s size, you may be using the basic project definition (in a .sbt file) or the full project definition (usually in project/Build.scala).

… to a basic project definition

The miniboxing runtime support library is marked as a dependency to the project by adding the following lines to build.sbt:

resolvers += Resolver.sonatypeRepo("snapshots")
libraryDependencies += "org.scala-miniboxing.plugins" %%
                       "miniboxing-runtime" % "0.4-SNAPSHOT"

Just by adding the library, you can already annotate type parameters with @miniboxed. Still, in order to have the code transformed based on the annotations, you need to add the miniboxing compiler plugin:

addCompilerPlugin("org.scala-miniboxing.plugins" %%
                  "miniboxing-plugin" % "0.4-SNAPSHOT")

An example build.sbt file, with the required empty lines between commands, is:

name := "hello-miniboxing-world"

version := "1.0"

scalaVersion := "2.11.4"

resolvers += Resolver.sonatypeRepo("snapshots")

libraryDependencies += "org.scala-miniboxing.plugins" %%
                       "miniboxing-runtime" % "0.4-SNAPSHOT"

addCompilerPlugin("org.scala-miniboxing.plugins" %%
                  "miniboxing-plugin" % "0.4-SNAPSHOT")

This project definition file only works with sbt 0.12 or newer, so you should create project/build.properties to enforce using your desired sbt version:

sbt.version=0.13.5

… to a full project definition

The exact same commands are needed in the full build, except that they are now wrapped in a val and are separated by commas instead of empty lines:

val miniboxingSettings: Seq[Setting[_]] = Seq(
  resolvers += Resolver.sonatypeRepo("snapshots"),
  libraryDependencies += "org.scala-miniboxing.plugins" %%
                         "miniboxing-runtime" % "0.4-SNAPSHOT",
  addCompilerPlugin("org.scala-miniboxing.plugins" %%
                    "miniboxing-plugin" % "0.4-SNAPSHOT"),
)

And you also need to add the val containing settings to your project’s settings:

  lazy val root: Project = Project("miniboxing-example", file("."),
                                   settings = Defaults.defaultSettings ++
                                              miniboxingSettings)

The same requirement stands for full project definitions: sbt 0.12 or newer is required, so you may want to create the project/build.properties file as described in the basic project definition.

Command Line Options

When using the miniboxing plugin in sbt, you can control the compiler plugin and enable logging by adding command line arguments. This is done using the command:

scalacOptions += "-P:minibox:log"

The command can be written directly in build.sbt or added to miniboxingSettings (careful, add a comma to the command before it!). Another trick is to use the sbt prompt to add arguments when needed:

> set scalacOptions += "-P:minibox:log"
[info] Defining *:scalac-options
[info] Reapplying settings...
[info] Set current project to hello-miniboxing-world
>

For the list of all command line arguments, see the command line page.

Example Project

If you want to see these changes in place, or want to just try out the miniboxing plugin without creating a project, have a look at the example project we posted that uses miniboxing. The examples all build on top of this project.

All set!

You’re all set to add your first @miniboxed annotation! If you haven’t read the introduction and tutorial, it’s a good time to do so!

Comments

Comments are always welcome! But to make the best use of them, please consider this:

If you have questions or feedback regarding the content of this page, please leave us a comment!
If you have general questions about the miniboxing plugin, please ask on the mailing List.
If you found a bug, please let us know on the github issue tracker.

Thanks! Looking forward to your messages!