NAME ^

Parrot - running

VERSION ^

$Revision$

OVERVIEW ^

This document describes parrot's command line options.

SYNOPSIS ^

 parrot [-options] <file> [arguments ...]

ENVIRONMENT ^

PARROT_RUNTIME

If this environment variable is set, parrot will use this path as runtime prefix instead of the compiled in path.

PARROT_GC_DEBUG

Turn on the --gc-debug flag.

OPTIONS ^

Assembler options ^

-a, --pasm

Assume PASM input on stdin.

-c, --pbc

Assume PBC file on stdin, run it.

-d, --debug [hexbits]

The -d switch takes an optional argument which is considered to hold a hex value of debug bits. Without a value, debug is set to 1.

The individual bits are:

 DEBUG_PARROT         0001
 DEBUG_LEXER          0002
 DEBUG_PARSER         0004
 DEBUG_IMC            0008
 DEBUG_CFG            0010
 DEBUG_OPT1           0020
 DEBUG_OPT2           0040
 DEBUG_PBC            1000
 DEBUG_PBC_CONST      2000
 DEBUG_PBC_FIXUP      4000
These can be listed on the command line by use of the --help-debug switch.

To produce really huge output on stderr run "imcc -d 0ffff ...". Note: if the argument is separated by whitespace from the -d switch, it has to start with a number.

-h, --help

Print commandline option summary.

--help-debug

Print debugging and tracing flag bits summary.

-o outputfile, --output=outputfile

Act like an assembler. Don't run code, unless -r is given too. If the outputfile ends with .pbc, a PBC file is written. If it ends with .pasm, a PASM output is generated, even from PASM input. This can be handy to check various optimizations, including -Op.

--output-pbc

Act like an assembler, but always output bytecode, even if the output file does not end in .pbc

-r, --run-pbc

Only useful after -o or --output-pbc. Run the program from the compiled in-memory image. If two -r options are given, the .pbc file is read from disc and run. This is mainly needed for tests.

-v, --verbose

One -v shows which files are worked on and prints a summary over register usage and optimization stats per compilation unit. With two -v switches, IMCC prints a line per individual processing step too.

-y, --yydebug

Turn on yydebug in yacc/bison.

-V, --version

-Ox

Optimize

 -O0 no optimization (default)
 -O1 optimizations without life info (e.g. branches)
 -O  same
 -O2 optimizations with life info
 -Op rewrite I and N PASM registers most used first
 -Ot select fastest run core (default with -O1 and -O2)
 -Oc turns on the optional/experimental tail call optimizations
See docs/imcc/operation.pod for more information on the optimizer. NB. Optimization is currently experimental and these options are likely to change.

-E, --pre-process-only

Preprocess source file (i.e. expand macros) and print result to stdout. E.g.

  $ parrot -E t/op/macro_10.pasm
  $ parrot -E t/op/macro_10.pasm | parrot -- -

Run Core Options ^

TODO: The default run core should be indicated.

-b, --bounds-checks, --slow-core

Select the bounds-checking slow core.

-C, --CGP-core

Select the CGP (CGoto Predereferenced) core (if available).

-f, --fast-core

Select the fast (or function) core.

-g, --computed-goto-core

Select the CGoto core (if available).

-j, --jit-core

Run with the JIT subsystem (if available).

-p, --profile

Run with the slow core and print an execution profile.

-S, --switched-core

TODO: This needs to be documented briefly here and also in glossary.pod.

-t, --trace

Run with the slow core and print trace information to stderr. See 'parrot --help-debug' for available flag bits.

VM Options ^

-w, --warnings

Turn on warnings. See 'parrot --help-debug' for available flag bits.

-D, --parrot-debug

Turn on interpreter debug flag. See 'parrot --help-debug' for available flag bits.

--gc-debug

Turn on GC (Garbage Collection) debugging. This imposes some stress on the GC subsystem and can slow down execution considerably.

-G, --no-gc

This turns off DOD (Dead Object Detection) and GC. This may be useful to find GC related bugs. Don't use this option for longer running programs: as memory is no longer recycled, it may quickly become exhausted.

--leak-test, --destroy-at-end

Free all memory of the last interpreter, so that leak checkers can be run.

-., --wait

Read a keystroke before starting.

--runtime-prefix

Print the runtime prefix path and exit.

<file> ^

If the file ends in .pbc it will be interpreted immediately.

If the file ends in .pasm, then it is parsed as PASM code. Otherwise, it is parsed as PIR code. In both cases, it will then be run, unless the -o flag was given.

If the file is a single dash, input from stdin is read.

Generated files ^

If debugging is enabled these files are generated:

  file.stabs.s ... stabsfile for the program
  file.o ... object file with debug information
  EVAL_n ... source of B<compile> op number I<n>
  EVAL_n.stabs.s ... stabsfile for this block
  EVAL_n.o ... object file with debug information

[arguments ...] ^

Optional arguments passed to the running program as ARGV. The program is assumed to know what to do with these.

Operation table ^

 Command line           Action          Output
 ---------------------------------------------
 parrot x.pir           run
 parrot x.pasm          run
 parrot x.pbc           run
 -o x.pasm x.pir        ass             x.pasm
 -o x.pasm y.pasm       ass             x.pasm
 -o x.pbc  x.pir        ass             x.pbc
 -o x.pbc  x.pasm       ass             x.pbc
 -o x.pbc -r x.pasm     ass/run pasm    x.pbc
 -o x.pbc -r -r x.pasm  ass/run pbc     x.pbc
 -o x.o    x.pbc        obj

Actions above are:

  run ... yes, run the program
  ass ... assemble sourcefile
  obj ..  produce native (ELF) object file for the EXEC subsystem

BUGS ^

Yes.

FILES ^

main.c

AUTHOR ^

Leopold Toetsch lt@toetsch.at


 parrot