1 # Copyright (C) 2001-2009, Parrot Foundation.
14 This document describes Parrot's command line options.
18 parrot [-options] <file> [arguments ...]
26 If this environment variable is set, parrot will use this path as its runtime
27 prefix instead of the compiled in path.
31 Turn on the I<--gc-debug> flag.
37 =head2 Assembler options
43 Assume PASM input on stdin.
47 Assume PBC file on stdin, run it.
49 =item -d, --imcc-debug [hexbits]
51 The B<-d> switch takes an optional argument which is considered to hold a hex
52 value of debug bits. Without a value, debug is set to 1.
54 The individual bits can be listed on the command line by use of the
55 B<--help-debug> switch.
57 To produce really huge output on F<stderr> run C<"parrot B<-d 0ffff> ...">.
58 Note: If the argument is separated by whitespace from the B<-d>
59 switch, it has to start with a number.
63 Print command line option summary.
67 Print debugging and tracing flag bits summary.
69 =item -o outputfile, --output=outputfile
71 Act like an assembler. Don't run code, unless B<-r> is given too. If the
72 outputfile ends with F<.pbc>, a PBC file is written. If it ends with F<.pasm>,
73 a PASM output is generated, even from PASM input. This can be handy to check
74 various optimizations, including C<-Op>.
78 Act like an assembler, but always output bytecode, even if the output file does
83 Only useful after C<-o> or C<--output-pbc>. Run the program from the compiled
84 in-memory image. If two C<-r> options are given, the F<.pbc> file is read from
85 disc and run. This is mainly needed for tests.
89 One C<-v> shows which files are worked on and prints a summary over register
90 usage and optimization stats per I<subroutine>. With two C<-v> switches,
91 C<parrot> prints a line per individual processing step too.
95 Turn on yydebug in F<yacc>/F<bison>.
99 Print version information and exit.
105 -O0 no optimization (default)
106 -O1 optimizations without life info (e.g. branches)
108 -O2 optimizations with life info
109 -Op rewrite I and N PASM registers most used first
110 -Ot select fastest runcore (default with -O1 and -O2)
111 -Oc turns on the optional/experimental tail call optimizations
113 See F<docs/dev/optimizer.pod> for more information on the optimizer. Note that
114 optimization is currently experimental and these options are likely to change.
116 =item -E, --pre-process-only
118 Preprocess source file (expand macros) and print result to stdout:
120 $ parrot -E t/op/macro_10.pasm
121 $ parrot -E t/op/macro_10.pasm | parrot -- -
125 =head2 Runcore Options
127 These options select the runcore, which is useful for performance tuning and
128 debugging. See L<About runcores> for details.
132 =item -R, --runcore CORE
134 Select the runcore. The following cores are available in Parrot, but not all
135 may be available on your system:
137 slow, bounds bounds checking core (default)
138 cgoto computed goto core
139 cgp computed goto-predereferenced core
140 fast fast core (no bounds checking, profiling, or tracing)
141 gcdebug performs a full GC run before every op dispatch (good for
142 debugging GC problems)
144 trace bounds checking core w/ trace info (see 'parrot --help-debug')
146 The C<jit>, C<switch-jit>, and C<cgp-jit> options are currently aliases for the
147 C<fast>, C<switch>, and C<cgp> options, respectively. We do not recommend
148 their use in new code; they will continue working for existing code per our
153 Run with the slow core and print an execution profile.
157 Run with the slow core and print trace information to B<stderr>. See C<parrot
158 --help-debug> for available flag bits.
168 Turn on warnings. See C<parrot --help-debug> for available flag bits.
170 =item -D, --parrot-debug
172 Turn on interpreter debug flag. See C<parrot --help-debug> for available flag
177 Turn on GC (Garbage Collection) debugging. This imposes some stress on the GC
178 subsystem and can slow down execution considerably.
182 This turns off GC. This may be useful to find GC related bugs. Don't use this
183 option for longer running programs: as memory is no longer recycled, it may
184 quickly become exhausted.
186 =item --leak-test, --destroy-at-end
188 Free all memory of the last interpreter. This is useful when running leak
193 Read a keystroke before starting. This is useful when you want to attach a
194 debugger on platforms such as Windows.
196 =item --runtime-prefix
198 Print the runtime prefix path and exit.
204 If the file ends in F<.pbc> it will be interpreted immediately.
206 If the file ends in F<.pasm>, then it is parsed as PASM code. Otherwise, it is
207 parsed as PIR code. In both cases, it will then be run, unless the C<-o> flag
210 If the C<file> is a single dash, input from C<stdin> is read.
212 =head2 [arguments ...]
214 Optional arguments passed to the running program as ARGV. The program is
215 assumed to know what to do with these.
217 =head1 Generated files
219 =head1 About runcores
221 The runcore (or runloop) tells Parrot how to find the C code that implements
222 each instruction. Parrot provides more than one way to do this, partly because
223 no single runcore will perform optimally on all architectures (or even for all
224 problems on a given architecture), and partly because some of the runcores have
225 specific debugging and tracing capabilities.
227 In the default "slow" runcore, each opcode is a separate C function.
228 That's pretty easy in pseudocode:
232 op = op_function( op )
235 The GC debugging runcore is similar:
237 gcdebug_runcore( op ):
239 perform_full_gc_run()
240 op = op_function( op )
243 Of course, this is much slower, but is extremely helpful for pinning memory
244 corruption problems that affect GC down to single-instruction resolution. See
245 L<http://www.oreillynet.com/onlamp/blog/2007/10/debugging_gc_problems_in_parro.html>
246 for more information.
248 The trace and profile cores are also based on the "slow" core, doing
249 full bounds checking, and also printing runtime information to stderr.
251 The switched core eschews these tiny op functions in favor of cases in a large
254 switch_runcore( op ):
263 Depending on the C compiler implementation, this may be faster than function
264 calling. On older systems, it may fail to compile altogether.
266 The computed-goto ("cgoto") runcore avoids the overhead of function
267 calls by jumping directly to the address where each opcode's function
268 starts. The computed-goto-prederef ("CGP") core takes this one step
269 further by replacing opcode numbers in the bytecode with those opfunc
270 addresses. See "Predereferencing" in F<docs/glossary.pod> for a
273 =head1 Operation table
275 Command Line Action Output
276 ---------------------------------------------
280 -o x.pasm x.pir ass x.pasm
281 -o x.pasm y.pasm ass x.pasm
282 -o x.pbc x.pir ass x.pbc
283 -o x.pbc x.pasm ass x.pbc
284 -o x.pbc -r x.pasm ass/run pasm x.pbc
285 -o x.pbc -r -r x.pasm ass/run pbc x.pbc
288 ... where the possible actions are:
290 run ... yes, run the program
291 ass ... assemble sourcefile
292 obj .. produce native (ELF) object file for the EXEC subsystem