# Copyright (C) 2001-2007, The Perl Foundation.
# $Id: running.pod 22374 2007-10-21 21:35:49Z chromatic $

=head1 NAME

Parrot - running

=head1 VERSION

$Revision: 22374 $

=head1 OVERVIEW

This document describes parrot's command line options.

=head1 SYNOPSIS

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

=head1 ENVIRONMENT

=over 4

=item PARROT_RUNTIME

If this environment variable is set, parrot will use this path as runtime
prefix instead of the compiled in path.

=item PARROT_GC_DEBUG

Turn on the I<--gc-debug> flag.

=back

=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

These can be listed on the command line by use of the B<--help-debug> switch.

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

Print commandline option summary.

=item --help-debug

Print debugging and tracing flag bits summary.

=item -o outputfile, --output=outputfile

Act like an 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 an assembler, but always output bytecode, even if the output file 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 without 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)
 -Oc turns on the optional/experimental tail call optimizations

See F<docs/imcc/operation.pod> for more information on the optimizer.  NB.
Optimization is currently experimental and these options are likely to 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 -R, --runcore CORE

Select the runcore. The following cores are available:

  slow, bounds  bounds checking core (default)
  fast          fast core (no bounds checking, profiling, or tracing)
  switch        switch core
  cgp           computed goto-predereferenced core
  cgoto         computed goto core
  jit           JIT core
  cgp-jit       computed goto-predereferenced core with JIT
  switch-jit    switch core with JIT
  exec          exec core (uses JIT at compile time to generate native code)
  trace         bounds checking core w/ trace info (see 'parrot --help-debug')
  gcdebug       performs a full GC run before every op dispatch (good for
                debugging GC problems)

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

Select the bounds-checking slow core (default).

=item -C, --CGP-core

Select the CGP (CGoto Predereferenced) core (if available).

=item -f, --fast-core

Select the fast (or function) core.

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

Select the CGoto core (if available).

=item -j, --jit-core

Run with the JIT subsystem (if available).

=item -p, --profile

Run with the slow core and print an execution profile.

=item -S, --switched-core

TODO:  This needs to be documented briefly here and also in glossary.pod.

=item -t, --trace

Run with the slow core and print trace information to B<stderr>. See 'parrot
--help-debug' for available flag bits.

=back

=head2 VM Options

=over 4

=item -w, --warnings

Turn on warnings. See 'parrot --help-debug' for available flag bits.

=item -D, --parrot-debug

Turn on interpreter debug flag. See 'parrot --help-debug' for available flag
bits.

=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 off DOD (Dead Object Detection) and GC. This may be useful to find
GC related bugs. Don't use this option for longer running programs: as memory
is no longer recycled, it may quickly become exhausted.

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

=item --runtime-prefix

Print the runtime prefix path and exit.

=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 number 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. The program is
assumed to know what to do with these.

=head1 Operation table

 Command line		Action		Output
 ---------------------------------------------
 parrot x.pir		run
 parrot x.pasm		run
 parrot x.pbc		run
 -o x.pasm x.pir	ass		x.pasm
 -o x.pasm y.pasm	ass		x.pasm
 -o x.pbc  x.pir	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 C<lt@toetsch.at>

=cut