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   cgoto         computed goto core
 139   cgp           computed goto-predereferenced core
 140   fast          fast core (no bounds checking, profiling, or tracing)
 141   gcdebug       performs a full GC run before every op dispatch (good for
 142                 debugging GC problems)
 143   switch        switch core
 144   trace         bounds checking core w/ trace info (see 'parrot --help-debug')
 145
 146 The C<jit>, C<switch-jit>, and C<cgp-jit> options are currently aliases for the
 147 C<fast>, C<switch>, and C<cgp> options, respectively.  We do not recommend
 148 their use in new code; they will continue working for existing code per our
 149 deprecation policy.
 150
 151 =item -p, --profile
 152
 153 Run with the slow core and print an execution profile.
 154
 155 =item -t, --trace
 156
 157 Run with the slow core and print trace information to B<stderr>. See C<parrot
 158 --help-debug> for available flag bits.
 159
 160 =back
 161
 162 =head2 VM Options
 163
 164 =over 4
 165
 166 =item -w, --warnings
 167
 168 Turn on warnings. See C<parrot --help-debug> for available flag bits.
 169
 170 =item -D, --parrot-debug
 171
 172 Turn on interpreter debug flag. See C<parrot --help-debug> for available flag
 173 bits.
 174
 175 =item --gc-debug
 176
 177 Turn on GC (Garbage Collection) debugging. This imposes some stress on the GC
 178 subsystem and can slow down execution considerably.
 179
 180 =item -G, --no-gc
 181
 182 This turns off GC. This may be useful to find GC related bugs. Don't use this
 183 option for longer running programs: as memory is no longer recycled, it may
 184 quickly become exhausted.
 185
 186 =item --leak-test, --destroy-at-end
 187
 188 Free all memory of the last interpreter.  This is useful when running leak
 189 checkers.
 190
 191 =item -., --wait
 192
 193 Read a keystroke before starting.  This is useful when you want to attach a
 194 debugger on platforms such as Windows.
 195
 196 =item --runtime-prefix
 197
 198 Print the runtime prefix path and exit.
 199
 200 =back
 201
 202 =head2 <file>
 203
 204 If the file ends in F<.pbc> it will be interpreted immediately.
 205
 206 If the file ends in F<.pasm>, then it is parsed as PASM code. Otherwise, it is
 207 parsed as PIR code. In both cases, it will then be run, unless the C<-o> flag
 208 was given.
 209
 210 If the C<file> is a single dash, input from C<stdin> is read.
 211
 212 =head2 [arguments ...]
 213
 214 Optional arguments passed to the running program as ARGV. The program is
 215 assumed to know what to do with these.
 216
 217 =head1 Generated files
 218
 219 =head1 About runcores
 220
 221 The runcore (or runloop) tells Parrot how to find the C code that implements
 222 each instruction.  Parrot provides more than one way to do this, partly because
 223 no single runcore will perform optimally on all architectures (or even for all
 224 problems on a given architecture), and partly because some of the runcores have
 225 specific debugging and tracing capabilities.
 226
 227 In the default "slow" runcore, each opcode is a separate C function.
 228 That's pretty easy in pseudocode:
 229
 230     slow_runcore( op ):
 231         while ( op ):
 232             op = op_function( op )
 233             check_for_events()
 234
 235 The GC debugging runcore is similar:
 236
 237     gcdebug_runcore( op ):
 238         while ( op ):
 239             perform_full_gc_run()
 240             op = op_function( op )
 241             check_for_events()
 242
 243 Of course, this is much slower, but is extremely helpful for pinning memory
 244 corruption problems that affect GC down to single-instruction resolution.  See
 245 L<http://www.oreillynet.com/onlamp/blog/2007/10/debugging_gc_problems_in_parro.html>
 246 for more information.
 247
 248 The trace and profile cores are also based on the "slow" core, doing
 249 full bounds checking, and also printing runtime information to stderr.
 250
 251 The switched core eschews these tiny op functions in favor of cases in a large
 252 switch statement:
 253
 254     switch_runcore( op ):
 255         while ( op ):
 256             switch *op:
 257                 case NOP:
 258                     ...
 259                 case STORE:
 260                     ...
 261                 ...
 262
 263 Depending on the C compiler implementation, this may be faster than function
 264 calling.  On older systems, it may fail to compile altogether.
 265
 266 The computed-goto ("cgoto") runcore avoids the overhead of function
 267 calls by jumping directly to the address where each opcode's function
 268 starts.  The computed-goto-prederef ("CGP") core takes this one step
 269 further by replacing opcode numbers in the bytecode with those opfunc
 270 addresses.  See "Predereferencing" in F<docs/glossary.pod> for a
 271 fuller explanation.
 272
 273 =head1 Operation table
 274
 275  Command Line          Action         Output
 276  ---------------------------------------------
 277  parrot x.pir          run
 278  parrot x.pasm         run
 279  parrot x.pbc          run
 280  -o x.pasm x.pir       ass            x.pasm
 281  -o x.pasm y.pasm      ass            x.pasm
 282  -o x.pbc  x.pir       ass            x.pbc
 283  -o x.pbc  x.pasm      ass            x.pbc
 284  -o x.pbc -r x.pasm    ass/run pasm   x.pbc
 285  -o x.pbc -r -r x.pasm ass/run pbc    x.pbc
 286  -o x.o    x.pbc       obj
 287
 288 ... where the possible actions are:
 289
 290   run ... yes, run the program
 291   ass ... assemble sourcefile
 292   obj ..  produce native (ELF) object file for the EXEC subsystem
 293
 294 =head1 FILES
 295
 296 F<main.c>
 297
 298 =cut