docs/running.pod

   1 # Copyright (C) 2001-2007, 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 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 B<.pbc>, a PBC file is written. If it ends with B<.pasm>,
  73 a PASM output is generated, even from PASM input. This can be handy to check
  74 various optimizations, including B<-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 B<.pbc>
  80
  81 =item -r, --run-pbc
  82
  83 Only useful after B<-o> or B<--output-pbc>. Run the program from the compiled
  84 in-memory image. If two B<-r> options are given, the B<.pbc> file is read from
  85 disc and run. This is mainly needed for tests.
  86
  87 =item -v, --verbose
  88
  89 One B<-v> shows which files are worked on and prints a summary over register
  90 usage and optimization stats per I<compilation unit>.  With two B<-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/imcc/operation.pod> for more information on the optimizer.  NB.
 114 Optimization is currently experimental and these options are likely to change.
 115
 116 =item -E, --pre-process-only
 117
 118 Preprocess source file (i.e. expand macros) and print result to stdout. E.g.
 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
 128 tuning and debugging.  See L<About runcores> below 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 '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 'parrot --help-debug' for available flag bits.
 191
 192 =item -D, --parrot-debug
 193
 194 Turn on interpreter debug flag. See '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, so that leak checkers can be run.
 211
 212 =item -., --wait
 213
 214 Read a keystroke before starting.
 215
 216 =item --runtime-prefix
 217
 218 Print the runtime prefix path and exit.
 219
 220 =back
 221
 222 =head2 <file>
 223
 224 If the file ends in B<.pbc> it will be interpreted immediately.
 225
 226 If the file ends in B<.pasm>, then it is parsed as PASM code. Otherwise, it is
 227 parsed as PIR code. In both cases, it will then be run, unless the B<-o> flag
 228 was given.
 229
 230 If the B<file> is a single dash, input from B<stdin> is read.
 231
 232 =head2 [arguments ...]
 233
 234 Optional arguments passed to the running program as ARGV. The program is
 235 assumed to know what to do with these.
 236
 237 =head1 Generated files
 238
 239 If JIT debugging is enabled (e.g. via C<--parrot-debug 04>), the
 240 following additional output files are generated:
 241
 242   file.stabs.s ... stabsfile for the program
 243   file.o ... object file with debug information
 244   EVAL_n ... source of B<compile> op number I<n>
 245   EVAL_n.stabs.s ... stabsfile for this block
 246   EVAL_n.o ... object file with debug information
 247
 248 See F<docs/jit.pod> for further information.
 249
 250 =head1 About runcores
 251
 252 The runcore (or runloop) tells Parrot how to find the C code that
 253 implements each instruction.  Parrot provides more than one way to do
 254 this, partly because it is expected that no one runcore will perform
 255 optimally on all architectures (or even for all problems on a given
 256 architecture), and partly because some of the runcores are specialized
 257 for debugging.
 258
 259 In the default "slow" runcore, each opcode is a separate C function.
 260 That's pretty easy in pseudocode:
 261
 262         slow_runcore( op ):
 263                 while ( op ):
 264                         op = op_function( op )
 265                         check_for_events()
 266
 267 The GC debugging runcore is similar:
 268
 269         gcdebug_runcore( op ):
 270                 while ( op ):
 271                         perform_full_gc_run()
 272                         op = op_function( op )
 273                         check_for_events()
 274
 275 Of course, this is much slower, but is extremely helpful for pinning
 276 memory corruption problems that affect GC down to single-instruction
 277 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 a bunch of tiny op functions in favor of
 285 cases in a large 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
 297 function calling.  On older systems, it may fail to compile
 298 altogether.
 299
 300 The computed-goto ("cgoto") runcore avoids the overhead of function
 301 calls by jumping directly to the address where each opcode's function
 302 starts.  The computed-goto-prederef ("CGP") core takes this one step
 303 further by replacing opcode numbers in the bytecode with those opfunc
 304 addresses.  See "Predereferencing" in F<docs/glossary.pod> for a
 305 fuller explanation.
 306
 307 Finally, the JIT runcore uses the "slow" core, but also creates and
 308 jumps to JIT-compiled native code for supported opcodes.  "cgp-jit"
 309 and "switched-jit" are variations that use the CGP or switched core
 310 but run JIT code when possible.
 311
 312 =head1 Operation table
 313
 314  Command line           Action          Output
 315  ---------------------------------------------
 316  parrot x.pir           run
 317  parrot x.pasm          run
 318  parrot x.pbc           run
 319  -o x.pasm x.pir        ass             x.pasm
 320  -o x.pasm y.pasm       ass             x.pasm
 321  -o x.pbc  x.pir        ass             x.pbc
 322  -o x.pbc  x.pasm       ass             x.pbc
 323  -o x.pbc -r x.pasm     ass/run pasm    x.pbc
 324  -o x.pbc -r -r x.pasm  ass/run pbc     x.pbc
 325  -o x.o    x.pbc        obj
 326
 327 Actions above are:
 328
 329   run ... yes, run the program
 330   ass ... assemble sourcefile
 331   obj ..  produce native (ELF) object file for the EXEC subsystem
 332
 333 =head1 BUGS
 334
 335 Yes.
 336
 337 =head1 FILES
 338
 339 F<main.c>
 340
 341 =head1 AUTHOR
 342
 343 Leopold Toetsch C<lt@toetsch.at>
 344
 345 =cut