.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "RUNNING 1" .TH RUNNING 1 "2011-09-11" "Debian Project" "Debian GNU/Linux manual" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" docs/running.pod \- Running .SH "VERSION" .IX Header "VERSION" \&\f(CW$Revision\fR$ .SH "OVERVIEW" .IX Header "OVERVIEW" This document describes Parrot's command line options. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& parrot [\-options] [arguments ...] .Ve .SH "ENVIRONMENT" .IX Header "ENVIRONMENT" .IP "\s-1PARROT_RUNTIME\s0" 4 .IX Item "PARROT_RUNTIME" If this environment variable is set, parrot will use this path as its runtime prefix instead of the compiled in path. .IP "\s-1PARROT_GC_DEBUG\s0" 4 .IX Item "PARROT_GC_DEBUG" Turn on the \fI\-\-gc\-debug\fR flag. .SH "OPTIONS" .IX Header "OPTIONS" .SS "Assembler options" .IX Subsection "Assembler options" .IP "\-a, \-\-pasm" 4 .IX Item "-a, --pasm" Assume \s-1PASM\s0 input on stdin. .IP "\-c, \-\-pbc" 4 .IX Item "-c, --pbc" Assume \s-1PBC\s0 file on stdin, run it. .IP "\-d, \-\-imcc\-debug [hexbits]" 4 .IX Item "-d, --imcc-debug [hexbits]" The \fB\-d\fR switch takes an optional argument which is considered to hold a hex value of debug bits. Without a value, debug is set to 1. .Sp The individual bits can be listed on the command line by use of the \&\fB\-\-help\-debug\fR switch. .Sp To produce really huge output on \fIstderr\fR run \f(CW"parrot \f(CB\-d 0ffff\f(CW ..."\fR. Note: If the argument is separated by whitespace from the \fB\-d\fR switch, it has to start with a number. .IP "\-h, \-\-help" 4 .IX Item "-h, --help" Print command line option summary. .IP "\-\-help\-debug" 4 .IX Item "--help-debug" Print debugging and tracing flag bits summary. .IP "\-o outputfile, \-\-output=outputfile" 4 .IX Item "-o outputfile, --output=outputfile" Act like an assembler. Don't run code, unless \fB\-r\fR is given too. If the outputfile ends with \fI.pbc\fR, a \s-1PBC\s0 file is written. If it ends with \fI.pasm\fR, a \s-1PASM\s0 output is generated, even from \s-1PASM\s0 input. This can be handy to check various optimizations, including \f(CW\*(C`\-Op\*(C'\fR. .IP "\-\-output\-pbc" 4 .IX Item "--output-pbc" Act like an assembler, but always output bytecode, even if the output file does not end in \fI.pbc\fR .IP "\-r, \-\-run\-pbc" 4 .IX Item "-r, --run-pbc" Only useful after \f(CW\*(C`\-o\*(C'\fR or \f(CW\*(C`\-\-output\-pbc\*(C'\fR. Run the program from the compiled in-memory image. If two \f(CW\*(C`\-r\*(C'\fR options are given, the \fI.pbc\fR file is read from disc and run. This is mainly needed for tests. .IP "\-v, \-\-verbose" 4 .IX Item "-v, --verbose" One \f(CW\*(C`\-v\*(C'\fR shows which files are worked on and prints a summary over register usage and optimization stats per \fIsubroutine\fR. With two \f(CW\*(C`\-v\*(C'\fR switches, \&\f(CW\*(C`parrot\*(C'\fR prints a line per individual processing step too. .IP "\-y, \-\-yydebug" 4 .IX Item "-y, --yydebug" Turn on yydebug in \fIyacc\fR/\fIbison\fR. .IP "\-V, \-\-version" 4 .IX Item "-V, --version" Print version information and exit. .IP "\-Ox" 4 .IX Item "-Ox" Optimize .Sp .Vb 7 \& \-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 .Ve .Sp See \fIdocs/dev/optimizer.pod\fR for more information on the optimizer. Note that optimization is currently experimental and these options are likely to change. .IP "\-E, \-\-pre\-process\-only" 4 .IX Item "-E, --pre-process-only" Preprocess source file (expand macros) and print result to stdout: .Sp .Vb 2 \& $ parrot \-E t/op/macro_10.pasm \& $ parrot \-E t/op/macro_10.pasm | parrot \-\- \- .Ve .SS "Runcore Options" .IX Subsection "Runcore Options" These options select the runcore, which is useful for performance tuning and debugging. See \*(L"About runcores\*(R" for details. .IP "\-R, \-\-runcore \s-1CORE\s0" 4 .IX Item "-R, --runcore CORE" Select the runcore. The following cores are available in Parrot, but not all may be available on your system: .Sp .Vb 5 \& 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 \*(Aqparrot \-\-help\-debug\*(Aq) \& profiling see F .Ve .Sp The \f(CW\*(C`jit\*(C'\fR, \f(CW\*(C`switch\-jit\*(C'\fR, and \f(CW\*(C`cgp\-jit\*(C'\fR options are currently aliases for the \&\f(CW\*(C`fast\*(C'\fR, \f(CW\*(C`switch\*(C'\fR, and \f(CW\*(C`cgp\*(C'\fR options, respectively. We do not recommend their use in new code; they will continue working for existing code per our deprecation policy. .IP "\-p, \-\-profile" 4 .IX Item "-p, --profile" Run with the slow core and print an execution profile. .IP "\-t, \-\-trace" 4 .IX Item "-t, --trace" Run with the slow core and print trace information to \fBstderr\fR. See \f(CW\*(C`parrot \&\-\-help\-debug\*(C'\fR for available flag bits. .SS "\s-1VM\s0 Options" .IX Subsection "VM Options" .IP "\-w, \-\-warnings" 4 .IX Item "-w, --warnings" Turn on warnings. See \f(CW\*(C`parrot \-\-help\-debug\*(C'\fR for available flag bits. .IP "\-D, \-\-parrot\-debug" 4 .IX Item "-D, --parrot-debug" Turn on interpreter debug flag. See \f(CW\*(C`parrot \-\-help\-debug\*(C'\fR for available flag bits. .IP "\-\-hash\-seed " 4 .IX Item "--hash-seed " Sets the hash seed to the provided value. Only useful for debugging intermittent failures, and harmful in production. .IP "\-\-gc\-debug" 4 .IX Item "--gc-debug" Turn on \s-1GC\s0 (Garbage Collection) debugging. This imposes some stress on the \s-1GC\s0 subsystem and can slow down execution considerably. .IP "\-G, \-\-no\-gc" 4 .IX Item "-G, --no-gc" This turns off \s-1GC\s0. This may be useful to find \s-1GC\s0 related bugs. Don't use this option for longer running programs: as memory is no longer recycled, it may quickly become exhausted. .IP "\-\-leak\-test, \-\-destroy\-at\-end" 4 .IX Item "--leak-test, --destroy-at-end" Free all memory of the last interpreter. This is useful when running leak checkers. .IP "\-., \-\-wait" 4 .IX Item "-., --wait" Read a keystroke before starting. This is useful when you want to attach a debugger on platforms such as Windows. .IP "\-\-runtime\-prefix" 4 .IX Item "--runtime-prefix" Print the runtime prefix path and exit. .IP "\-L path" 4 .IX Item "-L path" Add \f(CW\*(C`path\*(C'\fR to the library search path .SS "" .IX Subsection "" If the file ends in \fI.pbc\fR it will be interpreted immediately. .PP If the file ends in \fI.pasm\fR, then it is parsed as \s-1PASM\s0 code. Otherwise, it is parsed as \s-1PIR\s0 code. In both cases, it will then be run, unless the \f(CW\*(C`\-o\*(C'\fR flag was given. .PP If the \f(CW\*(C`file\*(C'\fR is a single dash, input from \f(CW\*(C`stdin\*(C'\fR is read. .SS "[arguments ...]" .IX Subsection "[arguments ...]" Optional arguments passed to the running program as \s-1ARGV\s0. The program is assumed to know what to do with these. .SH "Generated files" .IX Header "Generated files" .SH "About runcores" .IX Header "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. .PP In the default \*(L"slow\*(R" runcore, each opcode is a separate C function. That's pretty easy in pseudocode: .PP .Vb 4 \& slow_runcore( op ): \& while ( op ): \& op = op_function( op ) \& check_for_events() .Ve .PP The \s-1GC\s0 debugging runcore is similar: .PP .Vb 5 \& gcdebug_runcore( op ): \& while ( op ): \& perform_full_gc_run() \& op = op_function( op ) \& check_for_events() .Ve .PP Of course, this is much slower, but is extremely helpful for pinning memory corruption problems that affect \s-1GC\s0 down to single-instruction resolution. See for more information. .PP The trace and profile cores are also based on the \*(L"slow\*(R" core, doing full bounds checking, and also printing runtime information to stderr. .SH "Operation table" .IX Header "Operation table" .Vb 12 \& 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 .Ve .PP \&... where the possible actions are: .PP .Vb 3 \& run ... yes, run the program \& ass ... assemble sourcefile \& obj .. produce native (ELF) object file for the EXEC subsystem .Ve .SH "FILES" .IX Header "FILES" \&\fImain.c\fR