1 # Copyright (C) 2001-2005, The Perl 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 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, --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 are:
67 These can be listed on the command line by use of the B<--help-debug> switch.
69 To produce really huge output on F<stderr> run "imcc B<-d 0ffff> ...". Note:
70 if the argument is separated by whitespace from the B<-d> switch, it has to
75 Print commandline option summary.
79 Print debugging and tracing flag bits summary.
81 =item -o outputfile, --output=outputfile
83 Act like an assembler. Don't run code, unless B<-r> is given too. If the
84 outputfile ends with B<.pbc>, a PBC file is written. If it ends with B<.pasm>,
85 a PASM output is generated, even from PASM input. This can be handy to check
86 various optimizations, including B<-Op>.
90 Act like an assembler, but always output bytecode, even if the output file does
95 Only useful after B<-o> or B<--output-pbc>. Run the program from the compiled
96 in-memory image. If two B<-r> options are given, the B<.pbc> file is read from
97 disc and run. This is mainly needed for tests.
101 One B<-v> shows which files are worked on and prints a summary over register
102 usage and optimization stats per I<compilation unit>. With two B<-v> switches,
103 IMCC prints a line per individual processing step too.
107 Turn on yydebug in F<yacc>/F<bison>.
115 -O0 no optimization (default)
116 -O1 optimizations without life info (e.g. branches)
118 -O2 optimizations with life info
119 -Op rewrite I and N PASM registers most used first
120 -Ot select fastest run core (default with -O1 and -O2)
122 See F<imcc/docs/operation.pod> for more information on the optimizer. NB.
123 Optimization is currently experimental and these options are likely to change.
125 =item -E, --pre-process-only
127 Preprocess source file (i.e. expand macros) and print result to stdout. E.g.
129 $ parrot -E t/op/macro_10.pasm
130 $ parrot -E t/op/macro_10.pasm | parrot -- -
134 =head2 Run Core Options
136 TODO: The default run core should be indicated.
140 =item -b, --bounds-checks, --slow-core
142 Select the bounds-checking slow core.
146 Select the CGP (CGoto Predereferenced) core (if available).
148 =item -f, --fast-core
150 Select the fast (or function) core.
152 =item -g, --computed-goto-core
154 Select the CGoto core (if available).
158 Run with the JIT subsystem (if available).
162 Run with the slow core and print an execution profile.
164 =item -S, --switched-core
166 TODO: This needs to be documented briefly here and also in glossary.pod.
170 Run with the slow core and print trace information to B<stderr>. See 'parrot
171 --help-debug' for available flag bits.
181 Turn on warnings. See 'parrot --help-debug' for available flag bits.
183 =item -D, --parrot-debug
185 Turn on interpreter debug flag. See 'parrot --help-debug' for available flag
190 Turn on GC (Garbage Collection) debugging. This imposes some stress on the GC
191 subsystem and can slow down execution considerably.
195 This turns off DOD (Dead Object Detection) and GC. This may be useful to find
196 GC related bugs. Don't use this option for longer running programs: as memory
197 is no longer recycled, it may quickly become exhausted.
199 =item --leak-test, --destroy-at-end
201 Free all memory of the last interpreter, so that leak checkers can be run.
205 Read a keystroke before starting.
207 =item --runtime-prefix
209 Print the runtime prefix path and exit.
215 If the file ends in B<.pbc> it will be interpreted immediately.
217 If the file ends in B<.pasm>, then it is parsed as PASM code. Otherwise, it is
218 parsed as PIR code. In both cases, it will then be run, unless the B<-o> flag
221 If the B<file> is a single dash, input from B<stdin> is read.
223 =head2 Generated files
225 If debugging is enabled these files are generated:
227 file.stabs.s ... stabsfile for the program
228 file.o ... object file with debug information
229 EVAL_n ... source of B<compile> op number I<n>
230 EVAL_n.stabs.s ... stabsfile for this block
231 EVAL_n.o ... object file with debug information
233 =head1 [arguments ...]
235 Optional arguments passed to the running program as ARGV. The program is
236 assumed to know what to do with these.
238 =head1 Operation table
240 Command line Action Output
241 ---------------------------------------------
245 -o x.pasm x.pir ass x.pasm
246 -o x.pasm y.pasm ass x.pasm
247 -o x.pbc x.pir ass x.pbc
248 -o x.pbc x.pasm ass x.pbc
249 -o x.pbc -r x.pasm ass/run pasm x.pbc
250 -o x.pbc -r -r x.pasm ass/run pbc x.pbc
255 run ... yes, run the program
256 ass ... assemble sourcefile
257 obj .. produce native (ELF) object file for the EXEC subsystem
269 Leopold Toetsch C<lt@toetsch.at>