Setup ~ Local

In this section we describe the steps required to run the ildl-plugin locally.

Requirements

The following minimum specs are necessary for the local installation:

• amd64 processor architecture (64-bit processor, 64-bit operating system)
• 2 GB hard-drive space
• 4 GB of RAM (the benchmarks require 3G heap sizes)
• a *nix operating system (runners and the test suite require a *nix operating system)

We strongly recommend replicating the benchmarks directly on the host machine. We tried to replicate the benchmarks in the virtual machine and were unable to, most likely due to the 32-bit system architecture and the overhead of virtualization.

Prerequisites

Before you can install the ildl-plugin locally, you should have:

• Minimum installation:

  • git
  • Oracle Java 7 or OpenJDK7 (the benchmarks have been executed on Oracle Java 7 update 80)
  • sbt 0.13

• Full installation (running examples, browsing the source code)

  • minimum installation prerequisites
  • Scala 2.11.6
  • ScalaIDE for Scala 2.11.6

If you already have other versions of these prerequisites (e.g. Java 8 or a different version of sbt) you should still be able to replicate the benchmarks. However, in case of disagreements or errors, we kindly ask you to use the provided versions, which have been thoroughly tested on different machines and can reliably replicate the benchmark results.

Build

First clone the github repository:

$ git clone git@github.com:miniboxing/ildl-plugin.git

Then switch to the plugin directory and start sbt:

$ cd ildl-plugin
$ sbt package

Now go grab coffee while sbt downloads the internet and compiles the code:

Runner (Optional)

Optionally, if you are running a *nix operating system, you can use the ildl-scalac and ildl-scala scripts to run the Scala compiler/runner with the ildl-plugin activated. This is not necessary if you only plan to replicate the benchmarks and the scripts are already set up in the virtual machine.

To set up the Scala runner scripts, you first need the Scala distribution:

$ scala
Welcome to Scala version 2.11.6 (Java HotSpot(TM) 64-Bit Server VM, Java 1.7.0_80).
Type in expressions to have them evaluated.
Type :help for more information.

scala> 

Then, set the following environment variables:

$ cd ildl-plugin
$ export SCALA_PATH=$(dirname `which scala`) # the path to the distribution bin/ directory
$ export ILDL_PATH=`pwd`                     # the path to the ildl-plugin directory
$ export PATH=$PATH:$SCALA_PATH:$ILDL_PATH

With these environment variables, you should be able to run ildl-scalac:

$ ildl-scalac -Xshow-phases
      phase name  id  description
      ----------  --  -----------
          parser   1  parse source into ASTs, perform simple desugaring
 ildl-postparser   2
           namer   3  resolve names, attach symbols to named trees
  packageobjects   4  load package objects
           typer   5  the meat and potatoes: type the trees
     ildl-inject   6
          patmat   7  translate match expressions
  superaccessors   8  add super accessors in traits and nested classes
      extmethods   9  add extension methods for inline classes
         pickler  10  serialize symbol tables
       refchecks  11  reference/override checking, translate nested objects
         uncurry  12  uncurry, translate function values to anonymous classes
     ildl-bridge  13
     ildl-coerce  14
     ildl-commit  15
       tailcalls  16  replace tail calls by jumps
      specialize  17  @specialized-driven class and method specialization
   explicitouter  18  this refs to outer pointers
         erasure  19  erase types, add interfaces for traits
     posterasure  20  clean up erased inline classes
ildl-tweakera...  21
        lazyvals  22  allocate bitmaps, translate lazy vals into lazified defs
      lambdalift  23  move nested functions to top level
    constructors  24  move field definitions into constructors
         flatten  25  eliminate inner classes
           mixin  26  mixin composition
         cleanup  27  platform-specific cleanups, generate reflective calls
      delambdafy  28  remove lambdas
           icode  29  generate portable intermediate code
             jvm  30  generate JVM bytecode
        terminal  31  the last phase during a compilation run

Note the phases beginning with ildl. These are phases introduced by the ildl compiler plugin. You can read more about them in the Transformation page.

IDE Setup (Optional)

If you installed ScalaIDE, you can use it to browse the source code (the same works for the other artifacts as well):

$ cd ildl-plugin # or another artifact's directory
$ sbt
...
> eclipse with-source=true
...
[info] Successfully created Eclipse project files for project(s):
[info] ildl-tests
[info] ildl-plugin
[info] ildl-benchmarks
[info] ildl-runtime

Now you can start the ScalaIDE and import the project:

• from the menu bar, choose File > Import...
• in the window that appears, choose General and Existing Projects into Workspace and hit Next
• select the directory the ildl-plugin directory (or the artifact directory)
• select all projects and hit Finish

For the ildl-plugin you should have 4 projects:

• ildl-benchmarks are the benchmarks
• ildl-plugin is the compiler extension
• ildl-runtime contains API classes (such as TransformationDescription)
• ildl-tests contains the tests

This is what the ScalaIDE should look like:

Tests (Optional)

Once the plugin is compiled, if you are running a *nix operating system, you can run the test suite (only on *nix systems):

$ sbt test
...
Compiling benchmark-lazylist.scala                                     ... [ OK ]
Compiling bridges-1-repr.scala                                         ... [ OK ]
Compiling bridges-2-reprs.scala                                        ... [ OK ]
Compiling coerce-complex-1.scala                                       ... [ OK ]
Compiling coerce-complex-2.scala                                       ... [ OK ]
Compiling coerce-simple.scala                                          ... [ OK ]
Compiling constructors.scala                                           ... [ OK ]
Compiling error-high-1.scala                                           ... [ OK ]
Compiling error-high-2.scala                                           ... [ OK ]
Compiling error-high-3.scala                                           ... [ OK ]
Compiling extensions-basic-implicit.scala                              ... [ OK ]
Compiling extensions-basic.scala                                       ... [ OK ]
Compiling extensions-generic-implicit.scala                            ... [ OK ]
Compiling extensions-generic.scala                                     ... [ OK ]
Compiling feature-high.scala                                           ... [ OK ]
Compiling freestyle-1.scala                                            ... [ OK ]
Compiling freestyle-2.scala                                            ... [ OK ]
Compiling freestyle-3.scala                                            ... [ OK ]
Compiling hamming-issue.scala                                          ... [ OK ]
Compiling inject-accessors-2.scala                                     ... [ OK ]
Compiling inject-accessors.scala                                       ... [ OK ]
Compiling scopes-collaborating-2.scala                                 ... [ OK ]
Compiling scopes-collaborating.scala                                   ... [ OK ]
Compiling scopes-conflicting-cascade.scala                             ... [ OK ]
Compiling scopes-conflicting-repr.scala                                ... [ OK ]
Compiling scopes-conflicting-same-high.scala                           ... [ OK ]
Compiling scopes-nested.scala                                          ... [ OK ]
Compiling scopes-pickling.scala                                        ... [ OK ]

  28 tests ran, all good :)

(hint: don't run the miniboxing test suite, it has 300+ tests)

Congratulations! You have installed the ildl-plugin locally! Now you can run the benchmarks as well.

From Here:

• now that the ildl-plugin is up and running, check out the [[Step by Step Guide|OOPSLA-~-Step-by-step]].
• or jump to using the demo virtual machine
• return to the home page