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
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 gcdebug performs a full GC run before every op dispatch (good for
139 debugging GC problems)
140 trace bounds checking core w/ trace info (see 'parrot --help-debug')
141 profiling see F<docs/dev/profilling.pod>
143 The C<jit>, C<switch-jit>, and C<cgp-jit> options are currently aliases for the
144 C<fast>, C<switch>, and C<cgp> options, respectively. We do not recommend
145 their use in new code; they will continue working for existing code per our
150 Run with the slow core and print an execution profile.
154 Run with the slow core and print trace information to B<stderr>. See C<parrot
155 --help-debug> for available flag bits.
165 Turn on warnings. See C<parrot --help-debug> for available flag bits.
167 =item -D, --parrot-debug
169 Turn on interpreter debug flag. See C<parrot --help-debug> for available flag
174 Turn on GC (Garbage Collection) debugging. This imposes some stress on the GC
175 subsystem and can slow down execution considerably.
179 This turns off GC. This may be useful to find GC related bugs. Don't use this
180 option for longer running programs: as memory is no longer recycled, it may
181 quickly become exhausted.
183 =item --leak-test, --destroy-at-end
185 Free all memory of the last interpreter. This is useful when running leak
190 Read a keystroke before starting. This is useful when you want to attach a
191 debugger on platforms such as Windows.
193 =item --runtime-prefix
195 Print the runtime prefix path and exit.
201 If the file ends in F<.pbc> it will be interpreted immediately.
203 If the file ends in F<.pasm>, then it is parsed as PASM code. Otherwise, it is
204 parsed as PIR code. In both cases, it will then be run, unless the C<-o> flag
207 If the C<file> is a single dash, input from C<stdin> is read.
209 =head2 [arguments ...]
211 Optional arguments passed to the running program as ARGV. The program is
212 assumed to know what to do with these.
214 =head1 Generated files
216 =head1 About runcores
218 The runcore (or runloop) tells Parrot how to find the C code that implements
219 each instruction. Parrot provides more than one way to do this, partly because
220 no single runcore will perform optimally on all architectures (or even for all
221 problems on a given architecture), and partly because some of the runcores have
222 specific debugging and tracing capabilities.
224 In the default "slow" runcore, each opcode is a separate C function.
225 That's pretty easy in pseudocode:
229 op = op_function( op )
232 The GC debugging runcore is similar:
234 gcdebug_runcore( op ):
236 perform_full_gc_run()
237 op = op_function( op )
240 Of course, this is much slower, but is extremely helpful for pinning memory
241 corruption problems that affect GC down to single-instruction resolution. See
242 L<http://www.oreillynet.com/onlamp/blog/2007/10/debugging_gc_problems_in_parro.html>
243 for more information.
245 The trace and profile cores are also based on the "slow" core, doing
246 full bounds checking, and also printing runtime information to stderr.
248 =head1 Operation table
250 Command Line Action Output
251 ---------------------------------------------
255 -o x.pasm x.pir ass x.pasm
256 -o x.pasm y.pasm ass x.pasm
257 -o x.pbc x.pir ass x.pbc
258 -o x.pbc x.pasm ass x.pbc
259 -o x.pbc -r x.pasm ass/run pasm x.pbc
260 -o x.pbc -r -r x.pasm ass/run pbc x.pbc
263 ... where the possible actions are:
265 run ... yes, run the program
266 ass ... assemble sourcefile
267 obj .. produce native (ELF) object file for the EXEC subsystem