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