Moby
------
Danny Yoo (dyoo@cs.wpi.edu)


----------------------------------------------------------------------

What is Moby?

Moby is a project from the PLT Scheme team.  The Moby compiler
consumes Beginner Student Language (BSL) programs that use World
primitives, and produces applications for mobile platforms.  The
current prototype supports the Android platform.  Our long-term goal
is to make Scheme the premiere reactive scripting language for mobile
phones.

Shriram Krishnamurthi presented the ideas behind Moby at ILC 2009;
his talk "The Moby Scheme Compiler for Smartphones" can be found here:

    http://www.cs.brown.edu/~sk/Publications/Talks/Moby-Bootstrap/


----------------------------------------------------------------------

How does it work?

The compiler takes a BSL program and translates it to Java code.
We've reimplemented the BSL primitives in a Java runtime library
that's included with the compiled application.  To implement the World
primitives, we use the graphical components in the J2ME platform.

To support Android, we use bridge classes between J2ME and Android.
In this way, we should be able to support both platforms with a lot of
code reuse.  We handle the other libraries (tilt, location) similarly,
though with support only for the Android platforms for now.


----------------------------------------------------------------------

Dependencies

You need the following:

  Java >=1.6 (http://java.sun.com/)
  Apache Ant >=1.7.1 (http://ant.apache.org/)
  PLT Scheme >=4.1.3 (http://plt-scheme.org/)
  Google Android SDK >= 1.0 (http://developer.android.com/)
  GUI-World (http://github.com/dyoo/gui-world/tree/master)


----------------------------------------------------------------------

What needs to be implemented?

See moby/doc/TODO.

----------------------------------------------------------------------

Installation

One prerequisite collection that needs to be installed is GUI-World.
We host GUI-World under github.

    1.  Grab the GUI-World source.  For example:

        git clone git://github.com/dyoo/gui-world.git

    2.  Add a symbolic link from the gui-world directory into the
    collects directory of your PLT Scheme installation.



To install Moby:

    1.  Grab the Moby source, currently hosted on github at:

        http://github.com/dyoo/moby-scheme/tree/master

    For example:

        $ git clone git://github.com/dyoo/moby-scheme.git moby


    2.  Edit moby/src/config.ss.  The system hardcodes
        paths to Apache Ant and Android SDK embedded as parameters
        within src/config.ss.  You should change those paths to the
        ones on your system.

    3.  Add a symbolic link from moby to the collects directory of
    your PLT Scheme installation.

        For example, if moby is under the home directory, and PLT Scheme
        under the ~/local/plt directory, then the command:

            $ ln -s ~/moby ~/local/plt/collects/moby

        will set up the necessary symbolic link.


----------------------------------------------------------------------

Running Moby from the command line

At this point, you can run the Moby command line utility
(moby/src/moby.ss) on a BSL program.

For example, let's run it on the falling-ball.ss example in moby/examples/falling-ball.ss:

    $ cd moby/examples
    $ mred ../src/moby.ss falling-ball.ss
    $ cd FallingBall
    $ ls
    AndroidManifest.xml  bin  build.xml  libs  res  src
    $ ls bin
    classes  classes.dex  FallingBall.ap_  FallingBall-debug.apk

FallingBall-debug.apk is the compiled Android binary.  The Ant
build.xml build-script in the FallingBall directory can install,
uninstall, and reinstall the application if the Android emulator
is online.

    $ ant install
Buildfile: build.xml

dirs:
     [echo] Creating output directories if needed...

resource-src:
     [echo] Generating R.java / Manifest.java from the resources...

aidl:
     [echo] Compiling aidl files into Java classes...

compile:
    [javac] Compiling 142 source files to /home/dyoo/work/moby/examples/FallingBall/bin/classes
    [javac] Note: Some input files use unchecked or unsafe operations.
    [javac] Note: Recompile with -Xlint:unchecked for details.

dex:
     [echo] Converting compiled files and external libraries into bin/classes.dex...

package-res:

package-res-no-assets:
     [echo] Packaging resources...

debug:
     [echo] Packaging bin/FallingBall-debug.apk, and signing it with a debug key...
     [exec] Using keystore: /home/dyoo/.android/debug.keystore

install:
     [echo] Installing bin/FallingBall-debug.apk onto default emulator...
     [exec] 726 KB/s (157611 bytes in 0.211s)
     [exec] 	pkg: /data/local/tmp/FallingBall-debug.apk
     [exec] Success

BUILD SUCCESSFUL
Total time: 19 seconds


After this, you can look at the Android emulator, which should now
have the FallingBall application installed.


----------------------------------------------------------------------

Regression test suite


We've got the beginnings of a regression test suite in
moby/src/test-compile-world.ss.  The test suite compiles several
applications in moby/src/test/; the suite saves compiled executables
in src/bin for manual inspection.

To run the regression test suite, open the
moby/src/test-compile-world.ss module in DrScheme.  You can then run
the run-all-tests function.  If everything runs successfully, every
sub-subdirectory in moby/src/bin will contain a compiled application.
Each application will have an ant file that you can use to install the
application into the Android emulator.

For Android, first start the emulator, then use

    ant install

or

    ant reinstall

For example:

## Running in DrScheme:

    Welcome to DrScheme, version 4.1.3 [3m].
    Language: Module.
    > (run-all-tests)


## This should take some time.  Afterwards, at your shell, cd into
   moby/src.

~/moby/src$


## Let's try out the falling-ball example.  The source for the 
## falling ball example is in test/falling-ball.ss.


~/moby/src$ cd bin
~/moby/src/bin$ ls
android
## Let's test the Android binary.  If you haven't started up the
## emulator, do so now.

~/moby/src/bin$ cd android/falling-ball
~/moby/src/bin/android/falling-ball$ ant install

## The application should deploy into the emulator.  Try running the
   program, and you should see a red ball descend.


----------------------------------------------------------------------

Unit tests

Minimal unit tests for the Java runtime live in moby/src/test.  To run
the unit tests, run the build.xml in src/test with ant.  Here's an
example run of the test suite:

######################################################################
~/moby$ cd src/test
~/moby/src/test$ ant
Buildfile: build.xml

init:

compile:
    [javac] Compiling 1 source file to /home/dyoo/moby/src/test/build

test:
    [junit] Testsuite: org.plt.TestKernel
    [junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.041 sec
    [junit] 
    [junit] Testcase: testEmpty took 0.011 sec
    [junit] Testsuite: org.plt.TestMath
    [junit] Tests run: 9, Failures: 0, Errors: 0, Time elapsed: 0.05 sec
    [junit] 
    [junit] Testcase: testAdd took 0.003 sec
    [junit] Testcase: testSymbol took 0.001 sec
    [junit] Testcase: testModulo took 0 sec
    [junit] Testcase: testCeiling took 0 sec
    [junit] Testcase: testFloor took 0 sec
    [junit] Testcase: testAbs took 0.008 sec
    [junit] Testcase: testAcos took 0 sec
    [junit] Testcase: testAsin took 0 sec
    [junit] Testcase: testAtan took 0 sec

BUILD SUCCESSFUL
Total time: 1 second
######################################################################