RUNNING(1)						      Debian GNU/Linux manual							RUNNING(1)

NAME

       docs/running.pod - Running

VERSION

       $Revision$

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)
	     gcdebug	   performs a full GC run before every op dispatch (good for
			   debugging GC problems)
	     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.

       --hash-seed <hexnum>
	   Sets the hash seed to the provided value. Only useful for debugging intermittent failures, and harmful in production.

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

       -L path
	   Add "path" to the library search path

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

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

Debian Project							    2011-09-11								RUNNING(1)