| layout | title | short_title |
|---|---|---|
default |
Using Miniboxing in the Command Line |
Command Line |
This page will explain how to use the miniboxing plugin from the command line.
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 artifacts:
- the miniboxing runtime support library and
- the miniboxing compiler plugin
Fortunately, both artifacts are published nightly on sonatype, so you can easily get them.
The two artifacts are hosted on the Sonatype OSS snapshots repository. You can either download them manually or ask your dependency manager to fetch them:
Runtime support library: {% highlight xml %} org.scala-miniboxing.plugins miniboxing-runtime_2.11 0.4-SNAPSHOT {% endhighlight %}
Scala compiler plugin: {% highlight xml %} org.scala-miniboxing.plugins miniboxing-plugin_2.11 0.4-SNAPSHOT {% endhighlight %}
Once the two artifacts have been downloaded, you can use them to run the Scala console:
{% highlight bash %}
$ scala
-bootclasspath miniboxing-runtime.jar:miniboxing-plugin.jar
-Xplugin:miniboxing-plugin.jar
Welcome to Scala version 2.11.1 (...). Type in expressions to have them evaluated. Type :help for more information.
scala> def foo[@miniboxed T](t: T) = | println((new Exception).getStackTrace()(0).getMethodName()) foo: [T](t: T)Unit
scala> foo(3) foo_n_J
scala> foo("x") foo {% endhighlight %}
If you followed the tutorial, you will know this means miniboxing is optimizing your code. :)
To run the scalac compiler, you only need to swap scalac for scala and indicate the files you want to compile.
You know everything you need to add your first @miniboxed annotation! If you haven't read the introduction and the tutorial, it's a good time to do so!
The next section describes the miniboxing plugin command line arguments in detail and shows an example.
The miniboxing plugin can be controlled using command-line arguments. The most useful command-line argument is -P:minibox:hijack, which allows a program using specialization (@specialized) to automatically be converted to miniboxing, without any annotation change.
Another very useful flag is -P:minibox:log which explains how classes are transformed.
A full list of flags can be obtained by calling either scala or scalac with the plugin and -help:
{% highlight text %} Options for plugin 'minibox': -P:minibox:warn-off do not show performance and specialization warnings for your code -P:minibox:warn-all show cross-project warnings, aka warn for the libraries as well -P:minibox:hijack hijack the @specialized(...) notation for miniboxing -P:minibox:mark-all implicitly add @miniboxed annotations to all type parameters -P:minibox:log log miniboxing signature transformations {% endhighlight %}
An example of using -P:minibox:log and -P:minibox:hijack (notice the @specialized annotation instead of @miniboxed):
{% highlight scala %} $ cat C.scala class C[@specialized T]
$ scalac
-bootclasspath miniboxing-runtime.jar:miniboxing-plugin.jar
-Xplugin:miniboxing-plugin.jar
-P:minibox:hijack
-P:minibox:log
C.scala
Specializing class C...
// interface: abstract trait C[T] extends Object { }
// specialized class: class C_J[Tsp] extends C[Tsp] { def (val C_J|T_TypeTag: Byte): C_J[Tsp] // is a specialized implementation of constructor C private[this] val C_J|T_TypeTag: Byte // no info }
// specialized class: class C_L[Tsp] extends C[Tsp] { def (): C_L[Tsp] // is a specialized implementation of constructor C } {% endhighlight %}