Running programs on the virtual machine.

Synopsis

Files ending in .pbc are interpreted as bytecode. Files ending in .pasm are parsed as PASM; other supported source files are parsed as PIR. Unless an output option is supplied, the resulting program is run.

Environment

PARROT_RUNTIME

When set, the runtime uses this path as its runtime prefix instead of the compiled-in path.

PARROT_GC_DEBUG

Enables the --gc-debug behavior for garbage-collection diagnostics.

Command options

Input and assembly

-a, --pasm

Assume PASM input on standard input.

-c, --pbc

Assume a bytecode file on standard input and run it.

-E, --pre-process-only

Expand macros in a source file and print the result to standard output.

-o outputfile, --output=outputfile

Assemble without running unless -r is also supplied. A .pbc suffix produces bytecode; a .pasm suffix produces PASM output.

--output-pbc

Assemble and always write bytecode, regardless of the output filename suffix.

-r, --run-pbc

Run the compiled in-memory image after assembly. Repeating the option reads the bytecode file from disk before running it.

Help, diagnostics, and optimization

-h, --help

Print a summary of command-line options.

--help-debug

Print the available debugging and tracing flag bits.

-d, --imcc-debug [hexbits]

Enable compiler debugging. Without a value, the debug level is set to one; a hexadecimal value selects individual diagnostic bits.

-v, --verbose

Show processed files and compilation statistics. Repeating the switch adds detail for individual processing steps.

-V, --version

Print version information and exit.

-Ox

Choose optimization behavior. -O0 disables optimization, while higher levels enable progressively broader optimization passes. -Op rewrites register order and -Ot selects the fastest available run core.

Runtime controls

-w, --warnings

Enable warnings.

-D, --parrot-debug

Enable interpreter debugging according to the selected debug bits.

--gc-debug

Run additional garbage-collection checks. This can substantially slow execution.

-G, --no-gc

Disable dead-object detection and garbage collection. This is intended for diagnostics, not long-running programs.

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

Free the final interpreter state for use with leak-checking tools.

-., --wait

Wait for a keystroke before starting, allowing a debugger to attach on suitable platforms.

--runtime-prefix

Print the runtime prefix and exit.

Runcore options

A runcore determines how the virtual machine dispatches each instruction. Different cores trade speed for bounds checking, tracing, profiling, or JIT support.

-R, --runcore CORE

Select a named core, such as slow, fast, switch, cgoto, cgp, jit, trace, or gcdebug.

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

Select the bounds-checking core, which is the conservative default.

-C, --CGP-core

Select the computed-goto predereferenced core when available.

-f, --fast-core

Select the fast or function core.

-g, --computed-goto-core

Select the computed-goto core when available.

-j, --jit-core

Use the JIT subsystem when available.

-p, --profile

Run with the slow core and print execution profiling information.

-S, --switched-core

Select the switched core.

-t, --trace

Run with the slow core and print trace information to standard error.

Input, arguments, and generated files

If the file argument is a single dash, the program reads from standard input. Additional arguments are passed to the running program as its argument vector.

JIT debugging may generate intermediate assembly, object, and evaluation files. Their names identify the original input or the evaluated compilation block.

Operation table

How runcores differ

The slow core dispatches through individual operation functions and performs bounds checks. The switched core places operations in a large switch statement. Computed-goto variants jump directly to operation addresses, reducing dispatch overhead on compilers that support the technique. JIT variants add native compilation for supported operations.

Troubleshooting

When a program behaves unexpectedly, first run it with conservative bounds checking, then add targeted tracing or profiling. Keep diagnostic output separate from program output and compare behavior across cores only after confirming that the same input and options are being used.