docs/running.pod

   1 # Copyright (C) 2001-2005, 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, --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 are:
  55
  56  DEBUG_PARROT         0001
  57  DEBUG_LEXER          0002
  58  DEBUG_PARSER         0004
  59  DEBUG_IMC            0008
  60  DEBUG_CFG            0010
  61  DEBUG_OPT1           0020
  62  DEBUG_OPT2           0040
  63  DEBUG_PBC            1000
  64  DEBUG_PBC_CONST      2000
  65  DEBUG_PBC_FIXUP      4000
  66
  67 These can be listed on the command line by use of the B<--help-debug> switch.
  68
  69 To produce really huge output on F<stderr> run "imcc B<-d 0ffff> ...".  Note:
  70 if the argument is separated by whitespace from the B<-d> switch, it has to
  71 start with a number.
  72
  73 =item -h, --help
  74
  75 Print commandline option summary.
  76
  77 =item --help-debug
  78
  79 Print debugging and tracing flag bits summary.
  80
  81 =item -o outputfile, --output=outputfile
  82
  83 Act like an assembler. Don't run code, unless B<-r> is given too. If the
  84 outputfile ends with B<.pbc>, a PBC file is written. If it ends with B<.pasm>,
  85 a PASM output is generated, even from PASM input. This can be handy to check
  86 various optimizations, including B<-Op>.
  87
  88 =item --output-pbc
  89
  90 Act like an assembler, but always output bytecode, even if the output file does
  91 not end in B<.pbc>
  92
  93 =item -r, --run-pbc
  94
  95 Only useful after B<-o> or B<--output-pbc>. Run the program from the compiled
  96 in-memory image. If two B<-r> options are given, the B<.pbc> file is read from
  97 disc and run. This is mainly needed for tests.
  98
  99 =item -v, --verbose
 100
 101 One B<-v> shows which files are worked on and prints a summary over register
 102 usage and optimization stats per I<compilation unit>.  With two B<-v> switches,
 103 IMCC prints a line per individual processing step too.
 104
 105 =item -y, --yydebug
 106
 107 Turn on yydebug in F<yacc>/F<bison>.
 108
 109 =item -V, --version
 110
 111 =item -Ox
 112
 113 Optimize
 114
 115  -O0 no optimization (default)
 116  -O1 optimizations without life info (e.g. branches)
 117  -O  same
 118  -O2 optimizations with life info
 119  -Op rewrite I and N PASM registers most used first
 120  -Ot select fastest run core (default with -O1 and -O2)
 121  -Oc turns on the optional/experimental tail call optimizations
 122
 123 See F<docs/imcc/operation.pod> for more information on the optimizer.  NB.
 124 Optimization is currently experimental and these options are likely to change.
 125
 126 =item -E, --pre-process-only
 127
 128 Preprocess source file (i.e. expand macros) and print result to stdout. E.g.
 129
 130   $ parrot -E t/op/macro_10.pasm
 131   $ parrot -E t/op/macro_10.pasm | parrot -- -
 132
 133 =back
 134
 135 =head2 Run Core Options
 136
 137 TODO:  The default run core should be indicated.
 138
 139 =over 4
 140
 141 =item -b, --bounds-checks, --slow-core
 142
 143 Select the bounds-checking slow core.
 144
 145 =item -C, --CGP-core
 146
 147 Select the CGP (CGoto Predereferenced) core (if available).
 148
 149 =item -f, --fast-core
 150
 151 Select the fast (or function) core.
 152
 153 =item -g, --computed-goto-core
 154
 155 Select the CGoto core (if available).
 156
 157 =item -j, --jit-core
 158
 159 Run with the JIT subsystem (if available).
 160
 161 =item -p, --profile
 162
 163 Run with the slow core and print an execution profile.
 164
 165 =item -S, --switched-core
 166
 167 TODO:  This needs to be documented briefly here and also in glossary.pod.
 168
 169 =item -t, --trace
 170
 171 Run with the slow core and print trace information to B<stderr>. See 'parrot
 172 --help-debug' for available flag bits.
 173
 174 =back
 175
 176 =head2 VM Options
 177
 178 =over 4
 179
 180 =item -w, --warnings
 181
 182 Turn on warnings. See 'parrot --help-debug' for available flag bits.
 183
 184 =item -D, --parrot-debug
 185
 186 Turn on interpreter debug flag. See 'parrot --help-debug' for available flag
 187 bits.
 188
 189 =item --gc-debug
 190
 191 Turn on GC (Garbage Collection) debugging. This imposes some stress on the GC
 192 subsystem and can slow down execution considerably.
 193
 194 =item -G, --no-gc
 195
 196 This turns off DOD (Dead Object Detection) and GC. This may be useful to find
 197 GC related bugs. Don't use this option for longer running programs: as memory
 198 is no longer recycled, it may quickly become exhausted.
 199
 200 =item --leak-test, --destroy-at-end
 201
 202 Free all memory of the last interpreter, so that leak checkers can be run.
 203
 204 =item -., --wait
 205
 206 Read a keystroke before starting.
 207
 208 =item --runtime-prefix
 209
 210 Print the runtime prefix path and exit.
 211
 212 =back
 213
 214 =head1 <file>
 215
 216 If the file ends in B<.pbc> it will be interpreted immediately.
 217
 218 If the file ends in B<.pasm>, then it is parsed as PASM code. Otherwise, it is
 219 parsed as PIR code. In both cases, it will then be run, unless the B<-o> flag
 220 was given.
 221
 222 If the B<file> is a single dash, input from B<stdin> is read.
 223
 224 =head2 Generated files
 225
 226 If debugging is enabled these files are generated:
 227
 228   file.stabs.s ... stabsfile for the program
 229   file.o ... object file with debug information
 230   EVAL_n ... source of B<compile> op number I<n>
 231   EVAL_n.stabs.s ... stabsfile for this block
 232   EVAL_n.o ... object file with debug information
 233
 234 =head1 [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 Operation table
 240
 241  Command line           Action          Output
 242  ---------------------------------------------
 243  parrot x.pir           run
 244  parrot x.pasm          run
 245  parrot x.pbc           run
 246  -o x.pasm x.pir        ass             x.pasm
 247  -o x.pasm y.pasm       ass             x.pasm
 248  -o x.pbc  x.pir        ass             x.pbc
 249  -o x.pbc  x.pasm       ass             x.pbc
 250  -o x.pbc -r x.pasm     ass/run pasm    x.pbc
 251  -o x.pbc -r -r x.pasm  ass/run pbc     x.pbc
 252  -o x.o    x.pbc        obj
 253
 254 Actions above are:
 255
 256   run ... yes, run the program
 257   ass ... assemble sourcefile
 258   obj ..  produce native (ELF) object file for the EXEC subsystem
 259
 260 =head1 BUGS
 261
 262 Yes.
 263
 264 =head1 FILES
 265
 266 F<main.c>
 267
 268 =head1 AUTHOR
 269
 270 Leopold Toetsch C<lt@toetsch.at>
 271
 272 =cut