docs/running.pod

   1 # Copyright (C) 2001-2008, The Perl Foundation.
   2 # $Id$
   3
   4 =head1 NAME
   5
   6 Parrot - running
   7
   8 =head1 VERSION
   9
  10 $Revision$
  11
  12 =head1 OVERVIEW
  13
  14 This document describes Parrot's command line options.
  15
  16 =head1 SYNOPSIS
  17
  18  parrot [-options] <file> [arguments ...]
  19
  20 =head1 ENVIRONMENT
  21
  22 =over 4
  23
  24 =item PARROT_RUNTIME
  25
  26 If this environment variable is set, parrot will use this path as its runtime
  27 prefix instead of the compiled in path.
  28
  29 =item PARROT_GC_DEBUG
  30
  31 Turn on the I<--gc-debug> flag.
  32
  33 =back
  34
  35 =head1 OPTIONS
  36
  37 =head2 Assembler options
  38
  39 =over 4
  40
  41 =item -a, --pasm
  42
  43 Assume PASM input on stdin.
  44
  45 =item -c, --pbc
  46
  47 Assume PBC file on stdin, run it.
  48
  49 =item -d, --imcc-debug [hexbits]
  50
  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.
  53
  54 The individual bits can be listed on the command line by use of the
  55 B<--help-debug> switch.
  56
  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.
  60
  61 =item -h, --help
  62
  63 Print command line option summary.
  64
  65 =item --help-debug
  66
  67 Print debugging and tracing flag bits summary.
  68
  69 =item -o outputfile, --output=outputfile
  70
  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>.
  75
  76 =item --output-pbc
  77
  78 Act like an assembler, but always output bytecode, even if the output file does
  79 not end in F<.pbc>
  80
  81 =item -r, --run-pbc
  82
  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.
  86
  87 =item -v, --verbose
  88
  89 One C<-v> shows which files are worked on and prints a summary over register
  90 usage and optimization stats per I<compilation unit>.  With two C<-v> switches,
  91 C<parrot> prints a line per individual processing step too.
  92
  93 =item -y, --yydebug
  94
  95 Turn on yydebug in F<yacc>/F<bison>.
  96
  97 =item -V, --version
  98
  99 Print version information and exit.
 100
 101 =item -Ox
 102
 103 Optimize
 104
 105  -O0 no optimization (default)
 106  -O1 optimizations without life info (e.g. branches)
 107  -O  same
 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
 112
 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.
 115
 116 =item -E, --pre-process-only
 117
 118 Preprocess source file (expand macros) and print result to stdout:
 119
 120   $ parrot -E t/op/macro_10.pasm
 121   $ parrot -E t/op/macro_10.pasm | parrot -- -
 122
 123 =back
 124
 125 =head2 Runcore Options
 126
 127 These options select the runcore, which is useful for performance tuning and
 128 debugging.  See L<About runcores> for details.
 129
 130 =over 4
 131
 132 =item -R, --runcore CORE
 133
 134 Select the runcore. The following cores are available:
 135
 136   slow, bounds  bounds checking core (default)
 137   fast          fast core (no bounds checking, profiling, or tracing)
 138   switch        switch core
 139   cgp           computed goto-predereferenced core
 140   cgoto         computed goto core
 141   jit           JIT core
 142   cgp-jit       computed goto-predereferenced core with JIT
 143   switch-jit    switch core with JIT
 144   exec          exec core (uses JIT at compile time to generate native code)
 145   trace         bounds checking core w/ trace info (see 'parrot --help-debug')
 146   gcdebug       performs a full GC run before every op dispatch (good for
 147                 debugging GC problems)
 148
 149 =item -b, --bounds-checks, --slow-core
 150
 151 Select the bounds-checking slow core (default).
 152
 153 =item -C, --CGP-core
 154
 155 Select the CGP (CGoto Predereferenced) core (if available).
 156
 157 =item -f, --fast-core
 158
 159 Select the fast (or function) core.
 160
 161 =item -g, --computed-goto-core
 162
 163 Select the CGoto core (if available).
 164
 165 =item -j, --jit-core
 166
 167 Run with the JIT subsystem (if available).
 168
 169 =item -p, --profile
 170
 171 Run with the slow core and print an execution profile.
 172
 173 =item -S, --switched-core
 174
 175 TODO:  This needs to be documented briefly here and also in glossary.pod.
 176
 177 =item -t, --trace
 178
 179 Run with the slow core and print trace information to B<stderr>. See C<parrot
 180 --help-debug> for available flag bits.
 181
 182 =back
 183
 184 =head2 VM Options
 185
 186 =over 4
 187
 188 =item -w, --warnings
 189
 190 Turn on warnings. See C<parrot --help-debug> for available flag bits.
 191
 192 =item -D, --parrot-debug
 193
 194 Turn on interpreter debug flag. See C<parrot --help-debug> for available flag
 195 bits.
 196
 197 =item --gc-debug
 198
 199 Turn on GC (Garbage Collection) debugging. This imposes some stress on the GC
 200 subsystem and can slow down execution considerably.
 201
 202 =item -G, --no-gc
 203
 204 This turns off DOD (Dead Object Detection) and GC. This may be useful to find
 205 GC related bugs. Don't use this option for longer running programs: as memory
 206 is no longer recycled, it may quickly become exhausted.
 207
 208 =item --leak-test, --destroy-at-end
 209
 210 Free all memory of the last interpreter.  This is useful when running leak
 211 checkers.
 212
 213 =item -., --wait
 214
 215 Read a keystroke before starting.  This is useful when you want to attach a
 216 debugger on platforms such as Windows.
 217
 218 =item --runtime-prefix
 219
 220 Print the runtime prefix path and exit.
 221
 222 =back
 223
 224 =head2 <file>
 225
 226 If the file ends in F<.pbc> it will be interpreted immediately.
 227
 228 If the file ends in F<.pasm>, then it is parsed as PASM code. Otherwise, it is
 229 parsed as PIR code. In both cases, it will then be run, unless the C<-o> flag
 230 was given.
 231
 232 If the C<file> is a single dash, input from C<stdin> is read.
 233
 234 =head2 [arguments ...]
 235
 236 Optional arguments passed to the running program as ARGV. The program is
 237 assumed to know what to do with these.
 238
 239 =head1 Generated files
 240
 241 If JIT debugging is enabled (e.g. via C<--parrot-debug 04>), the
 242 following additional output files are generated:
 243
 244   F<file.stabs.s>     stabsfile for the program
 245   F<file.o>           object file with debug information
 246   F<EVAL_n>           source of C<compile> op number I<n>
 247   F<EVAL_n.stabs.s>   stabsfile for this block
 248   F<EVAL_n.o>         object file with debug information
 249
 250 See F<docs/jit.pod> for further information.
 251
 252 =head1 About runcores
 253
 254 The runcore (or runloop) tells Parrot how to find the C code that implements
 255 each instruction.  Parrot provides more than one way to do this, partly because
 256 no single runcore will perform optimally on all architectures (or even for all
 257 problems on a given architecture), and partly because some of the runcores have
 258 specific debugging and tracing capabilities.
 259
 260 In the default "slow" runcore, each opcode is a separate C function.
 261 That's pretty easy in pseudocode:
 262
 263     slow_runcore( op ):
 264         while ( op ):
 265             op = op_function( op )
 266             check_for_events()
 267
 268 The GC debugging runcore is similar:
 269
 270     gcdebug_runcore( op ):
 271         while ( op ):
 272             perform_full_gc_run()
 273             op = op_function( op )
 274             check_for_events()
 275
 276 Of course, this is much slower, but is extremely helpful for pinning memory
 277 corruption problems that affect GC down to single-instruction resolution.  See
 278 L<http://www.oreillynet.com/onlamp/blog/2007/10/debugging_gc_problems_in_parro.html>
 279 for more information.
 280
 281 The trace and profile cores are also based on the "slow" core, doing
 282 full bounds checking, and also printing runtime information to stderr.
 283
 284 The switched core eschews these tiny op functions in favor of cases in a large
 285 switch statement:
 286
 287     switch_runcore( op ):
 288         while ( op ):
 289             switch *op:
 290                 case NOP:
 291                     ...
 292                 case STORE:
 293                     ...
 294                 ...
 295
 296 Depending on the C compiler implementation, this may be faster than function
 297 calling.  On older systems, it may fail to compile altogether.
 298
 299 The computed-goto ("cgoto") runcore avoids the overhead of function
 300 calls by jumping directly to the address where each opcode's function
 301 starts.  The computed-goto-prederef ("CGP") core takes this one step
 302 further by replacing opcode numbers in the bytecode with those opfunc
 303 addresses.  See "Predereferencing" in F<docs/glossary.pod> for a
 304 fuller explanation.
 305
 306 Finally, the JIT runcore uses the "slow" core, but also creates and
 307 jumps to JIT-compiled native code for supported opcodes.  "cgp-jit"
 308 and "switched-jit" are variations that use the CGP or switched core
 309 but run JIT code when possible.
 310
 311 =head1 Operation table
 312
 313  Command Line          Action         Output
 314  ---------------------------------------------
 315  parrot x.pir          run
 316  parrot x.pasm         run
 317  parrot x.pbc          run
 318  -o x.pasm x.pir       ass            x.pasm
 319  -o x.pasm y.pasm      ass            x.pasm
 320  -o x.pbc  x.pir       ass            x.pbc
 321  -o x.pbc  x.pasm      ass            x.pbc
 322  -o x.pbc -r x.pasm    ass/run pasm   x.pbc
 323  -o x.pbc -r -r x.pasm ass/run pbc    x.pbc
 324  -o x.o    x.pbc       obj
 325
 326 ... where the possible actions are:
 327
 328   run ... yes, run the program
 329   ass ... assemble sourcefile
 330   obj ..  produce native (ELF) object file for the EXEC subsystem
 331
 332 =head1 BUGS
 333
 334 Yes.
 335
 336 =head1 FILES
 337
 338 F<main.c>
 339
 340 =head1 AUTHOR
 341
 342 Leopold Toetsch C<lt@toetsch.at>
 343
 344 =cut