Getting Started with AVM2

Follow development environment installation.

Once you are done, export the following environment variables:

export ASC=Shumway/utils/asc.jar
export AVM=Shumway/utils/tamarin-redux/shell/avmshell
export BUILTINABC=Shumway/utils/tamarin-redux/generated/builtin.abc
export SHELLABC=Shumway/src/avm2/generated/shell/shell.abc

NOTE: If you have some problems with the tamarin install, you can skip it and replace

make install-utils

in the development setup with

make -C utils/ install-asc install-closure install-js install-node-modules install-flex-sdk

Then you can install and configure Tamarin separately, replacing your environment variables with the following (where tamarin-redux is the location of your tamarin installation):

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

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.

Running Hello World

First you will need to compile tests/hello-world.as using ASC. You can use ASC directly or via 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

Note: if you have trouble executing this command, try the following instead (export your local js in utils to JS):

export JS=Shumway/utils/jsshell/js
cd src/avm2/bin
$JS avm.js -x ../tests/hello-world.abc

Running Regression Tests

To run the regression tests you will first need to compile them using:

./shu.py build-tests

To execute them use the numbers.js script:

node numbers.js -i ../tests/regress/correctness/pass/ -c i -j 8

This will run all the tests in the tests in the tests/regress/correctness/pass/ directory under the interpreter 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, [v]erifier.

Finding Bugs

There are many features that are not implemented. To find something to work on download compiled Tamarin Test Suite, unpack it in the avm2/tests directory and rename the acceptance folder to tamarin.

To find bugs to fix, run all the tamarin test cases using:

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

You can exclude the tests that pass by maintaining a list of passing tests 'tamarin.i.passed' and then use the command:

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.

When you're done, quickly rerun all the passing tests to make sure nothing regressed:

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

Before You Submit a PR

The commit hook on GitHub runs the following command:

node numbers.js -i ../tests/regress/correctness/pass/ -c icv -j 8

This tests AVM2 in all three configurations, if you can't pass this your PR will not be accepted.

If you fix a bug, make sure to include a test case for it in the tests/regress/correctness/pass directory.