NAME
Parrot - Running
VERSION
$Revision: 45073 $
OVERVIEW
This document describes Parrot’s command line options.
SYNOPSIS
parrot [-options] <file> [arguments ...]
ENVIRONMENT
PARROT_RUNTIME
If this environment variable is set, parrot will use this path as
its runtime prefix instead of the compiled in path.
PARROT_GC_DEBUG
Turn on the --gc-debug flag.
OPTIONS
Assembler options
-a, --pasm
Assume PASM input on stdin.
-c, --pbc
Assume PBC file on stdin, run it.
-d, --imcc-debug [hexbits]
The -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 can be listed on the command line by use of the
--help-debug switch.
To produce really huge output on stderr run "parrot -d 0ffff ...".
Note: If the argument is separated by whitespace from the -d
switch, it has to start with a number.
-h, --help
Print command line option summary.
--help-debug
Print debugging and tracing flag bits summary.
-o outputfile, --output=outputfile
Act like an assembler. Don’t run code, unless -r is given too. If
the outputfile ends with .pbc, a PBC file is written. If it ends
with .pasm, a PASM output is generated, even from PASM input. This
can be handy to check various optimizations, including "-Op".
--output-pbc
Act like an assembler, but always output bytecode, even if the
output file does not end in .pbc
-r, --run-pbc
Only useful after "-o" or "--output-pbc". Run the program from the
compiled in-memory image. If two "-r" options are given, the .pbc
file is read from disc and run. This is mainly needed for tests.
-v, --verbose
One "-v" shows which files are worked on and prints a summary over
register usage and optimization stats per subroutine. With two
"-v" switches, "parrot" prints a line per individual processing
step too.
-y, --yydebug
Turn on yydebug in yacc/bison.
-V, --version
Print version information and exit.
-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 runcore
-Oc turns on the optional/experimental tail call optimizations
See docs/dev/optimizer.pod for more information on the optimizer.
Note that optimization is currently experimental and these options
are likely to change.
-E, --pre-process-only
Preprocess source file (expand macros) and print result to stdout:
$ parrot -E t/op/macro_10.pasm
$ parrot -E t/op/macro_10.pasm | parrot -- -
Runcore Options
These options select the runcore, which is useful for performance
tuning and debugging. See "About runcores" for details.
-R, --runcore CORE
Select the runcore. The following cores are available in Parrot,
but not all may be available on your system:
slow, bounds bounds checking core (default)
cgoto computed goto core
cgp computed goto-predereferenced core
fast fast core (no bounds checking, profiling, or tracing)
gcdebug performs a full GC run before every op dispatch (good for
debugging GC problems)
switch switch core
trace bounds checking core w/ trace info (see 'parrot --help-debug')
profiling see F<docs/dev/profilling.pod>
The "jit", "switch-jit", and "cgp-jit" options are currently
aliases for the "fast", "switch", and "cgp" options, respectively.
We do not recommend their use in new code; they will continue
working for existing code per our deprecation policy.
-p, --profile
Run with the slow core and print an execution profile.
-t, --trace
Run with the slow core and print trace information to stderr. See
"parrot --help-debug" for available flag bits.
VM Options
-w, --warnings
Turn on warnings. See "parrot --help-debug" for available flag
bits.
-D, --parrot-debug
Turn on interpreter debug flag. See "parrot --help-debug" for
available flag bits.
--gc-debug
Turn on GC (Garbage Collection) debugging. This imposes some stress
on the GC subsystem and can slow down execution considerably.
-G, --no-gc
This turns off 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.
--leak-test, --destroy-at-end
Free all memory of the last interpreter. This is useful when
running leak checkers.
-., --wait
Read a keystroke before starting. This is useful when you want to
attach a debugger on platforms such as Windows.
--runtime-prefix
Print the runtime prefix path and exit.
<file>
If the file ends in .pbc it will be interpreted immediately.
If the file ends in .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 "-o" flag was given.
If the "file" is a single dash, input from "stdin" is read.
[arguments ...]
Optional arguments passed to the running program as ARGV. The program
is assumed to know what to do with these.
Generated files
About runcores
The runcore (or runloop) tells Parrot how to find the C code that
implements each instruction. Parrot provides more than one way to do
this, partly because no single runcore will perform optimally on all
architectures (or even for all problems on a given architecture), and
partly because some of the runcores have specific debugging and tracing
capabilities.
In the default "slow" runcore, each opcode is a separate C function.
That’s pretty easy in pseudocode:
slow_runcore( op ):
while ( op ):
op = op_function( op )
check_for_events()
The GC debugging runcore is similar:
gcdebug_runcore( op ):
while ( op ):
perform_full_gc_run()
op = op_function( op )
check_for_events()
Of course, this is much slower, but is extremely helpful for pinning
memory corruption problems that affect GC down to single-instruction
resolution. See
<http://www.oreillynet.com/onlamp/blog/2007/10/debugging_gc_problems_in_parro.html>
for more information.
The trace and profile cores are also based on the "slow" core, doing
full bounds checking, and also printing runtime information to stderr.
The switched core eschews these tiny op functions in favor of cases in
a large switch statement:
switch_runcore( op ):
while ( op ):
switch *op:
case NOP:
...
case STORE:
...
...
Depending on the C compiler implementation, this may be faster than
function calling. On older systems, it may fail to compile altogether.
The computed-goto ("cgoto") runcore avoids the overhead of function
calls by jumping directly to the address where each opcode’s function
starts. The computed-goto-prederef ("CGP") core takes this one step
further by replacing opcode numbers in the bytecode with those opfunc
addresses. See "Predereferencing" in docs/glossary.pod for a fuller
explanation.
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
... where the possible actions are:
run ... yes, run the program
ass ... assemble sourcefile
obj .. produce native (ELF) object file for the EXEC subsystem
FILES
main.c