=head1 NAME

Parrot - running

=head1 VERSION

=over 4

=item 0.0.1 initial

=item 0.0.9.10 changed run options

=item 0.0.9.12 changed debug options

=item 0.0.10.0 imcc is parrot

=item 0.0.10.1 add -E switch

=item 0.0.11 added runtime options

=back

=head1 OVERVIEW

This document describes parrot's command line options.

=head1 SYNOPSIS

 parrot [-options] <file> [arguments ...]

=head1 OPTIONS

=head2 Assembler options

=over 4

=item -a, --pasm

Assume PASM input on stdin.

=item -c, --pbc

Assume PBC file on stdin, run it.

=item -d, --debug [hexbits]

The B<-d> switch takes an optional argument which is considered to hold
a hex value of debug bits. Without a value, debug is set to 1.

The individual bits are:

 DEBUG_PARROT         0001
 DEBUG_LEXER          0002
 DEBUG_PARSER         0004
 DEBUG_IMC            0008
 DEBUG_CFG            0010
 DEBUG_OPT1           0020
 DEBUG_OPT2           0040
 DEBUG_PBC            1000
 DEBUG_PBC_CONST      2000
 DEBUG_PBC_FIXUP      4000

To produce really huge output on F<stderr> run "imcc B<-d 0ffff> ...".
Note: if the argument is separated by whitespace from the B<-d> switch,
it has to start with a number.

=item -h, --help

=item -o outputfile, --output=outputfile

Act like assembler. Don't run code, unless B<-r> is given too. If the
outputfile ends with B<.pbc>, a PBC file is written. If it ends with
B<.pasm>, a PASM output is generated, even from PASM input. This can be
handy to check various optimizations, including B<-Op>.

=item --output-pbc

Act like assembler, but always output a bytecode even though the outputfile
does not end in B<.pbc>

=item -r, --run-pbc

Only useful after B<-o> or B<--output-pbc>. Run the program from the compiled
in-memory image. If two B<-r> options are given, the B<.pbc> file is read
from disc and run. This is mainly needed for tests.

=item -v, --verbose

One B<-v> shows which files are worked on and prints a summary
over register usage and optimization stats per I<compilation unit>.
With two B<-v> switches, IMCC prints a line per individual processing
step too.

=item -y, --yydebug

Turn on yydebug in F<yacc>/F<bison>.

=item -V, --version

=item -Ox

Optimize

 -O0 no optimization (default)
 -O1 optimizations w/o life info (e.g. branches)
 -O  same
 -O2 optimizations with life info
 -Op rewrite I and N PASM registers most used first
 -Ot select fastest run core (default with -O1 and -O2)

This will probably change.

=item -E, --pre-process-only

Preprocess source file (i.e. expand macros) and print result to stdout. E.g.

  $ parrot -E t/op/macro_10.pasm
  $ parrot -E t/op/macro_10.pasm | parrot -- -

=back

=head2 Run Core Options

=over 4

=item -b, --bounds-checks, --slow-core

Select the bounds-checking slow clore.

=item -C, --CGP-core

Select the CGP (CGoto Predereferenced) core.

=item -f, --fast-core

Select the fast (or function) core.

=item -g, --computed-goto-core

Select the CGoto core.

=item -j, --jit-core

Run with the JIT subsystem.

=item -p, --profile

Run with the slow core and do print an execution profile.

=item -P, --predereferenced-core

Prederefernce opcode function arguments on the fly.

=item -t, --trace

Run with the slow core and do print trace information to B<stderr>.

=back

=head2 VM Options

=over 4

=item -w, --warnings

Turn on warnings.

=item --gc-debug

Turn on GC (Garbage Collection) debugging. This imposes some stress on the
GC subsystem and can slow down execution considerably.

=item -G, --no-gc

This turns of DOD (Dead Object Detection) and GC. This may be useful to find GC
related bugs. DOn't use this option for longer running programs, this will
exhaust memory quickly, as it isn't recycled.

=item --leak-test, --destroy-at-end

Free all memory of the last interpreter, so that leak checkers can be run.

=item -., --wait

Read a keystroke before starting.

=back

=head1 <file>

If the file ends in B<.pbc> it will be interpreted immediately.

If the file ends in B<.pasm>, then it is parsed as PASM code. Otherwise,
it is parsed as PIR code. In both cases, it will then be run, unless the
B<-o> flag was given.
If the B<file> is a single dash, input from B<stdin> is read.

=head2 Generated files

If debugging is enabled these files are generated:

  file.stabs.s ... stabsfile for the program
  file.o ... object file with debug information
  EVAL_n ... source of B<compile> op nr. I<n>
  EVAL_n.stabs.s ... stabsfile for this block
  EVAL_n.o ... object file with debug information

=head1 [arguments ...]

Optional arguments passed to the running program as ARGV, only useful
for running the program.

=head1 Operation table

 Command line		Action		Output
 ---------------------------------------------
 parrot x.imc		run
 parrot x.pasm		run
 parrot x.pbc		run
 -o x.pasm x.imc	ass		x.pasm
 -o x.pasm y.pasm	ass		x.pasm
 -o x.pbc  x.imc	ass		x.pbc
 -o x.pbc  x.pasm	ass		x.pbc
 -o x.pbc -r x.pasm	ass/run pasm	x.pbc
 -o x.pbc -r -r x.pasm	ass/run pbc	x.pbc
 -o x.o    x.pbc        obj

Actions above are:

  run ... yes run the program
  ass ... assemble sourcefile
  obj ..  produce native (ELF) object file for the EXEC subsystem

=head1 BUGS

Yes.

=head1 FILES

F<main.c>

=head1 AUTHOR

Leopold Toetsch <lt@toetsch.at>


