docs/running.pod

   1 # Copyright (C) 2001-2009, Parrot 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<subroutine>.  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
 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 in Parrot, but not all
 135 may be available on your system:
 136
 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>
 142
 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
 146 deprecation policy.
 147
 148 =item -p, --profile
 149
 150 Run with the slow core and print an execution profile.
 151
 152 =item -t, --trace
 153
 154 Run with the slow core and print trace information to B<stderr>. See C<parrot
 155 --help-debug> for available flag bits.
 156
 157 =back
 158
 159 =head2 VM Options
 160
 161 =over 4
 162
 163 =item -w, --warnings
 164
 165 Turn on warnings. See C<parrot --help-debug> for available flag bits.
 166
 167 =item -D, --parrot-debug
 168
 169 Turn on interpreter debug flag. See C<parrot --help-debug> for available flag
 170 bits.
 171
 172 =item --hash-seed <hexnum>
 173
 174 Sets the hash seed to the provided value. Only useful for debugging
 175 intermittent failures, and harmful in production.
 176
 177 =item --gc-debug
 178
 179 Turn on GC (Garbage Collection) debugging. This imposes some stress on the GC
 180 subsystem and can slow down execution considerably.
 181
 182 =item -G, --no-gc
 183
 184 This turns off GC. This may be useful to find GC related bugs. Don't use this
 185 option for longer running programs: as memory is no longer recycled, it may
 186 quickly become exhausted.
 187
 188 =item --leak-test, --destroy-at-end
 189
 190 Free all memory of the last interpreter.  This is useful when running leak
 191 checkers.
 192
 193 =item -., --wait
 194
 195 Read a keystroke before starting.  This is useful when you want to attach a
 196 debugger on platforms such as Windows.
 197
 198 =item --runtime-prefix
 199
 200 Print the runtime prefix path and exit.
 201
 202 =back
 203
 204 =head2 <file>
 205
 206 If the file ends in F<.pbc> it will be interpreted immediately.
 207
 208 If the file ends in F<.pasm>, then it is parsed as PASM code. Otherwise, it is
 209 parsed as PIR code. In both cases, it will then be run, unless the C<-o> flag
 210 was given.
 211
 212 If the C<file> is a single dash, input from C<stdin> is read.
 213
 214 =head2 [arguments ...]
 215
 216 Optional arguments passed to the running program as ARGV. The program is
 217 assumed to know what to do with these.
 218
 219 =head1 Generated files
 220
 221 =head1 About runcores
 222
 223 The runcore (or runloop) tells Parrot how to find the C code that implements
 224 each instruction.  Parrot provides more than one way to do this, partly because
 225 no single runcore will perform optimally on all architectures (or even for all
 226 problems on a given architecture), and partly because some of the runcores have
 227 specific debugging and tracing capabilities.
 228
 229 In the default "slow" runcore, each opcode is a separate C function.
 230 That's pretty easy in pseudocode:
 231
 232     slow_runcore( op ):
 233         while ( op ):
 234             op = op_function( op )
 235             check_for_events()
 236
 237 The GC debugging runcore is similar:
 238
 239     gcdebug_runcore( op ):
 240         while ( op ):
 241             perform_full_gc_run()
 242             op = op_function( op )
 243             check_for_events()
 244
 245 Of course, this is much slower, but is extremely helpful for pinning memory
 246 corruption problems that affect GC down to single-instruction resolution.  See
 247 L<http://www.oreillynet.com/onlamp/blog/2007/10/debugging_gc_problems_in_parro.html>
 248 for more information.
 249
 250 The trace and profile cores are also based on the "slow" core, doing
 251 full bounds checking, and also printing runtime information to stderr.
 252
 253 =head1 Operation table
 254
 255  Command Line          Action         Output
 256  ---------------------------------------------
 257  parrot x.pir          run
 258  parrot x.pasm         run
 259  parrot x.pbc          run
 260  -o x.pasm x.pir       ass            x.pasm
 261  -o x.pasm y.pasm      ass            x.pasm
 262  -o x.pbc  x.pir       ass            x.pbc
 263  -o x.pbc  x.pasm      ass            x.pbc
 264  -o x.pbc -r x.pasm    ass/run pasm   x.pbc
 265  -o x.pbc -r -r x.pasm ass/run pbc    x.pbc
 266  -o x.o    x.pbc       obj
 267
 268 ... where the possible actions are:
 269
 270   run ... yes, run the program
 271   ass ... assemble sourcefile
 272   obj ..  produce native (ELF) object file for the EXEC subsystem
 273
 274 =head1 FILES
 275
 276 F<main.c>
 277
 278 =cut