Running | Exploring in Eclipse

Browsing the code allows seeing how complex (or how simple) the miniboxing plugin is. Actually, we do think it's pretty simple after all the refactorings it underwent lately.

• In the DRT Virtual Machine: From the Links directory on the desktop, double-click Eclipse IDE
• In your local installation: You should have installed Eclipse with the Scala IDE for Scala 2.11 on your machine. Then you can run sbt eclipse and import the project as explained in the local installation tutorial.

The project structure mimics the different components of the program is explained in the README file:

• components/plugin - the actual Scala compiler plugin, project miniboxing-plugin
• components/runtime - the runtime support for the transformed code, project miniboxing-runtime
• components/classloader - the classloader used for runtime class specialization, project miniboxing-classloader
• tests/benchmarks - the microbenchmarks for the project, project miniboxing-benchmarks
• tests/benchmarks - the macrobenchmarks for the project, project miniboxing-lib-bench
• tests/correctness - the tests for the plugin transformation, project miniboxing-tests

Building the projects is done either with sbt directly or through the Scala IDE. If you're planning on using Eclipse and sbt in parallel, it is advisable to turn off automatic building from Eclipse: uncheck Build Automatically from the Project menu. After this change, building is done on-demand, upon pressing Ctrl-B. Don't worry about spurious errors popping up sometimes, the project became big enough to give Eclipse some headaches. If they really disturb you, use Clean from the Project menu to clean and recompile all projects.

Exploring the Miniboxing Plugin Code

To explore the code for the miniboxing plugin, open the miniboxing-plugin project in Eclipse. In the src directory, the miniboxing.plugin package should be visible. There, you have:

• the Minibox.scala, which is the entry point in the plugin
• the metadata package, which takes care of creating symbols for the new entities and directing how the tree will be transformed (remember, the miniboxing transformation takes place in two steps: it first generates the new signatures and the metadata of how the tree should be transformed, and then performs the transformations in the minibox-inject phase)
  • MiniboxDefinitions.scala contains the link to the miniboxing runtime-defined methods
  • MiniboxMetadata.scala contains the metadata of how the tree will be transformed
  • MiniboxMetadataAddons.scala defines new custom methods on symbols, types and trees, such as isMiniboxed
  • MiniboxMetadataUtils.scala is the kitchen sink of useful tools for the transformation, neatly packaged into objects
  • MiniboxMethodInfo.scala directs how the methods are duplicated and specialized - it is from this information that the miniboxing transformation prints the output in -P:minibox:log
  • MiniboxNameUtils.scala contains the miniboxing name mangling scheme
• the transform package contains the actual transformation
  • the hijack phase is a technical artifact requires for the -P:minibox:hijack argument, which transforms all @specialized annotations into @miniboxed
  • the inject phase is the most complicated, as it does several things:
    • it creates symbols for the new entities and fills in the metadata (adding the @storage annotation along the way) - MiniboxDuplInfoTransformation.scala
    • it rewrites the tree, duplicating and specializing methods along the way - Duplicators.scala
    • it rewrites method calls and object instantiations to use the most specific specialized variant - MiniboxDuplTreeTransformation.scala / TreeRewriter.scala
  • the coerce phase makes the annotations incompatible via the annotation checker (MiniboxAnnotationChecker.scala) and then introduces coercions where necessary (MiniboxCoerceTreeTransformer.scala)
  • finally, the commit phase transforms the T @storage[X] into X and gives the marker coercions their final semantics. MiniboxCommitInfoTransformer.scala transforms signatures while MiniboxCommitTreeTransformer.scala transforms trees.

This is all the miniboxing plugin! Simple isn't it? :)

Next Steps

You can continue with the following resources:

• The main page of the DRT virtual machine page