/ 
parrot-0.1.1
/ docs/running.pod

NAME

docs/running.pod - Running Parrot

Running Parrot code

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

parrot

Interprets a Parrot bytecode file:

parrot foo.pbc

or a Parrot assembly file:

parrot foo.pasm

In the latter case, the file is assembled into an internally-resident bytecode file and then immediately run. To alternatively create a bytecode file on disk, use the -o flag:

parrot -o foo.pbc foo.pasm

This creates a bytecode file called foo.pbc, but does not execute it.

Any command line arguments from the filename on (i.e. the rest of argv) are placed into an SArray PMC which is passed into the program in PMC register P5. For the invocation:

parrot foo.pbc --foo_arg process_me.foo

the PMC in P5 would have three string elements: foo.pbc, --foo_arg, and process_me.foo.

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.

For example parrot -t will trace the execution of the Parrot opcodes. The values of the registers are shown as they are before the opcode is executed.

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 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