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

And editing TAMARIN_HOME inside utils/Makefile to point to the appropriate Tamarin installation.

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.