=head1 TITLE

Running Parrot

=head1 Running Parrot code

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

=over 3

=item C<assemble.pl>

Converts a Parrot Assembly file to Parrot bytecode.

  perl assemble.pl foo.pasm > foo.pbc

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

=item C<parrot>

Interprets a Parrot bytecode file.

  parrot foo.pbc

C<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 C<-g> flag to C<parrot> to use the normal dispatcher even if you
have computed goto available. Prederef mode is specified with C<-P>,
JIT mode with C<-j>.

Prederef mode previously only worked as a shared library. To revert to
that state, add C<#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 C<make shared>.

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

=item C<optimizer.pl>

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

  perl optimizer.pl foo.pasm

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

=item C<pbc2c.pl>

Converts a bytecode file to a native .c file.

  perl pbc2c.pl foo.pbc > foo.c

For more information, type C<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
  ./foo # Runs it

=item B<make test>

C<make test> will compile anything that needs to be compiled and run
all standard regression tests. To look at a test more closely, run the
appropriate test file in the t/ directory:

  perl -Ilib t/op/basic.t

To keep a copy of all of the test C<.pasm> and C<.pbc> files
generated, set the environment variable POSTMORTEM to 1 (THIS IS NOW
THE DEFAULT):

  env POSTMORTEM=1 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

=item B<make quicktest>

C<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 C<make test> should be performed before
submitting patches, just in case it is affected.

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

C<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 C<make quicktest> fails to work properly, C<make test> is always
available as a fallback.

=back
