Getting Started with AVM2

Getting Started with AVM2

NOTE: You can skip the "Installing" section if you cloned the repository and performed https://github.com/mozilla/shumway/wiki#development-environment(development environment installation). This method more preferable than in the section below.

Installing

• Shumway: Download the latest version of Shumway:

  cd ~
  git clone --recursive https://github.com/mozilla/shumway.git Shumway
  

• SpiderMonkey Shell: Check out the latest version of SpiderMonkey and follow the build instructions. Make sure the compiled js shell command is on your path:

  js -h
  

  You should have at least Version: JavaScript-C 1.8.5+.

• Node.js: Install the latest version of Node.js along with the following modules:

  Install the temp module using:

  npm install "temp"
  

  We only use Node.js for the testing harness and miscellaneous utilities.

• Tamarin Shell: Check out the latest version of Tamarin and follow the build instructions. It's best to build a "debugger" build (not the same thing as "debug") since it will give you more descriptive error messages.

  hg clone http://hg.mozilla.org/tamarin-redux
  cd tamarin-redux
  mkdir release-debugger
  cd release-debugger
  python ../configure.py --enable-debugger
  make
  

  Once you're done, export the following environment variables:

  export AVM=~/tamarin-redux/release-debugger/shell/avmshell
  export BUILTINABC=~/tamarin-redux/generated/builtin.abc
  

  If you're building on OSX specify the --mac-sdk:

  python ../configure.py --mac-sdk=106 --target=x86_64-darwin --enable-debugger
  

  Mountain Lion moved the default location of the SDKs to /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs. You'll need to patch the ../configure.py script to reflect this for SDK version 108.

  We do all our testing against Tamarin since that's the de facto specification for ActionScript 3. The --enable-debugger flag builds Tamarin with verbose error messages but should not affect performance.

• ActionScript Compiler: Download the ActionScript compiler:

  cd ~
  curl ftp://ftp.mozilla.org/pub/js/tamarin/builds/asc/latest/asc.jar > ~/Shumway/utils/asc.jar
  export ASC=~/Shumway/utils/asc.jar
  

Running AVM2

Normally AVM2 runs as part of the Flash player, but you can also run it from the command line directly using the avm.js script in the ~/Shumway/src/avm2/bin directory.

Hello World

First you will need to compile tests/hello-world.as using ASC. You can use ASC directly or the provided ./shu.py asc script:

./shu.py asc -builtin ../tests/hello-world.as

This should generate a file named hello-world.abc in the same directory as the source file. You can now execute it using Shumway AVM2:

js avm.js -x ../tests/hello-world.abc

Running Regression Tests

Most of the regression tests we use are borrowed from the Tamarin project. You'll first need to compile the Tamarin tests before running them. (Use the --rebuildtests flag to build the tests without running them.)Once you're done, copy the acceptance tests to the avm2/tests/tamarin directory:

cp -R ~/tamarin-redux/test/acceptance ~/Shumway/src/avm2/tests/tamarin

To run the regression tests use the numbers.js script:

node numbers.js -i tamarin.i.passed -c i -j 8

This will run all the tests that are known to pass (tamarin.i.passed) under the [i]nterpreter configuration using 8 threads.

The -i and -e commands let you include or exclude sets of tests to run. You can specify a single test file, a set of files in a given directory or a list of files from a text file. The -c command lets you control the test configurations you want to run: [i]nterpreter, [c]ompiler, [o]ptimizer, [v]erifier.

To find bugs to fix, run all the tests that don't pass using:

node numbers.js -i ../tests/tamarin/ -e tamarin.i.passed -c i -j 8

This runs all tests in the ../tests/tamarin directory except for those listed in tamarin.i.passed. If you get a test case to pass, append it to the tamarin.i.passed list.

The testing framework simply compares Shumway's standard output with Tamarin's. Sometimes Shumway may still be "correct" even if the output doesn't match exactly. To make such test cases pass create a patch file with the .diff extension in the same directory as the test case. This will be applied against Shumway's output before comparing it with Tamarin's. (E.g. hello-world.abc.diff). You can generate .diff files automatically using the -gp command. This will create patch files for every test that does not pass. The second time you run the test case the patch is applied and the test should pass.

For long running benchmarks it pays off to enable SpiderMonkey optimizations with the -jo flag. Short lived bencharmks run a bit faster if you disable (default) this.