# Copyright: 2001-2004 The Perl Foundation.  All Rights Reserved.
# $Id: running.pod 6508 2004-08-09 07:42:58Z leo $

=head1 NAME

docs/running.pod - 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.

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

=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

=back
