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. First you have to compile Shumway:

grunt shu

Then you can run .abc and .swf files from the command line using the build/ts/shell.js script:

js build/ts/shell.js -s -x test/avm2/pass/xml.abc

Usually you'll want to pass the -x and -s flags for executing a file and loading the shell infrastructure, respectively. A full list of command line arguments is available using -h.

Running Hello World

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

src/avm2/bin/shu.py asc -builtin src/avm2/tests/hello-world.as

This should generate a file named hello-world.abc in the same directory as the source file. You can now, if you have built Shumway as described above, execute it using Shumway AVM2:

js build/ts/shell.js -x src/avm2/tests/hello-world.abc

Running Regression Tests

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

cd src/avm2/bin
./shu.py build-tests

To execute them use the numbers.js script (from the repository's top-level directory:

node src/shell/numbers.js -i src/avm2/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 src/shell/numbers.js -i src/avm2/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 src/shell/numbers.js -i src/avm2/tests/tamarin/ -e src/avm2/bin/tamarin.i.passed -c i -j 8

This runs all tests in the src/avm2/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 src/shell/numbers.js -i src/avm2/tamarin.i.passed -c i -j 8

Before You Submit a PR

The commit hook on GitHub runs the following command in the repository's top-level directory:

grunt test

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.