# 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] [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 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. With two B<-v> switches, IMCC prints a line per individual processing step too. =item -y, --yydebug Turn on yydebug in F/F. =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 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. 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 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 is a single dash, input from B 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 op number I 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 =head1 AUTHOR Leopold Toetsch C =cut