=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<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 C<-o> flag:

  parrot -o foo.pbc foo.pasm

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

Any command line arguments from the filename on (i.e. the rest of
C<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: C<foo.pbc>, C<--foo_arg>, and
C<process_me.foo>.

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 F<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 B<make test>

C<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 C<.pasm> and C<.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

=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. If so, it uses the previously-generated .pbc file.

This option was originally developed when C<assemble.pl> was being used as
the primary Parrot assembler, as the assembly step dominated the runtime of
the test suite. Now that C<assemble.pl> is no longer being used, the gain
that one gets from C<make quicktest> is much smaller, and this option may
well disappear at some point in the future.

WARNING: 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.

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

=back
