TITLE

Running Parrot

Running Parrot code

This file briefly describes the current set of executables and what they're for.

assemble.pl

Converts a Parrot Assembly file to Parrot bytecode.

  perl assemble.pl foo.pasm > foo.pbc

Usage information: assemble.pl -h. Detailed documentation on the underlying module can be read with perldoc -F lib/Parrot/Assembler.pm.

parrot

Interprets a Parrot bytecode file.

  parrot foo.pbc

parrot has four different opcode dispatchers: normal, computed goto, prederef, and JIT. The default mode is normal, or computed goto if that is supported by your compiler (gcc supports it). You may pass the -g flag to parrot to use the normal dispatcher even if you have computed goto available. Prederef mode is specified with -P, JIT mode with -j.

Prederef mode previously only worked as a shared library. To revert to that state, add #define DYNAMIC_OPLIBS to the top of interpreter.c. Then, on most Unix platforms:

  make clean
  make shared
  LD_LIBRARY_PATH=blib/lib ./parrot -P foo.pbc

You will not be able to use any of the automatic testing targets after running make shared.

parrot also has several debugging and tracing flags; see the usage description (generated by parrot -h) for details.

optimizer.pl

Performs some basic optimizations on Parrot assembly files. Use it by running

  perl optimizer.pl foo.pasm

This will generate a foo.pasm.opt file containing the optimized version.

pbc2c.pl

Converts a bytecode file to a native .c file.

  perl pbc2c.pl foo.pbc > foo.c

For more information, type perldoc -F pbc2c.pl.

To convert the generated foo.c file to a binary, do (on Unix only):

  make libparrot.a
  gcc -O3 -g -Iinclude -c foo.c -o foo.o
  gcc -g -o foo foo.o -L. -lparrot -ldl -lm
  ./foo # Runs it

make test

make test will compile anything that needs to be compiled and run all standard regression tests, with garbage collection/memory management debugging enabled. (Collectively called GC_DEBUG, this is accomplished by either passing the --gc-debug flag to the parrot binary, or setting the environment variable $PARROT_GC_DEBUG.)

To speed up the test, compile imcc (in languages/imcc), and then use it to compile the test files:

  make -C languages/imcc
  make test IMCC=languages/imcc/imcc

To look at a test more closely, run the appropriate test file in the t/ directory:

  perl -Ilib t/op/basic.t

To avoid keeping copies of all of the test .pasm and .pbc files generated, set the environment variable $POSTMORTEM to 0:

  env POSTMORTEM=0 perl -Ilib t/op/basic.t
  ls t/op/basic*

To run makefile tests with a different dispatcher, set the $TEST_PROG_ARGS variable:

  make test TEST_PROG_ARGS=-P # Use prederef mode

For running individual tests, set the environment variable $TEST_PROG_ARGS:

  env TEST_PROG_ARGS=-j perl -Ilib t/op/basic.t

To run the tests under all available dispatchers, use the 'fulltest' target:

  make fulltest

make quicktest

make quicktest is similar to make test, except that it skips some steps that are unnecessary most of the time, allowing for a significant speed gain. It's intended to be used as a quick check during development, lowering the barrier to checking tests. A make test should be performed before submitting patches, just in case it is affected.

These days, quicktest is rapidly becoming (already?) obsoleted by the IMCC= flag to 'make test'. IMCC takes so little time to compile the tests that the quick* targets don't offer any advantages.

Instead of recompiling the .pasm files to .pbc files each time the test is run, make quicktest checks to see if the .pasm file is identical to the test, and if so, it uses the previously-generated .pbc file.

make quicktest can fail under the following circumstances:

- it is cancelled before the generation of the .pbc file can be completed - the .pbc file format changes - the numbering of opcodes used in the tests is changed - the assembler changes in a manner that would affect its output on tests

If make quicktest fails to work properly, make test is always available as a fallback.

make quickfulltest may be used to run all tests under all available dispatchers. This actually doesn't take all that long, since the *.pbc files are guaranteed to be reused after the first complete test pass.