=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 two alternate modes of operation: prederef mode
(C<parrot -P>) and jit mode (C<parrot -j>).

Jit mode works for any program that doesn't use the stack ops.
That's because we use fixed address for registers, this problem will
be solved soon.

Prederef mode only works as a shared library. For example, 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:

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

To run tests with a different dispatcher, edit
C<$Parrot::Config::PConfig{test_prog}> in lib/Parrot/Config.pm:

               'test_prog' => 'parrot -P',

and then use any of the above methods for running tests.

=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
