Command line

The installed wrapper is normally called as:

pxx [options] source [output]

From a checkout, use:

./pxx [options] source [output]

The wrapper created by install.sh calls the pinned compiler and adds bundled library roots. The underlying compiler executable is still named compiler/pascal26.

Source and output

The frontend is selected by the source file's extension: .pas/.pp for Pascal, .c for C, .npy or .py for Nil Python, and .asm for the assembly-source frontend.

With an output path, PXX writes the executable there and emits a matching map file. Without an output path, it derives one from the source name and refuses to overwrite the source.

An output path ending in .o also selects object-output mode, the same as passing --emit-obj. An output path ending in .so selects shared-library mode, the same as passing --shared.

Information flags

These answer a question about the toolchain itself and need no source file. Each exits 0.

--version names the compiler generation — the same number a {$IF PXX_VERSION >= n} directive tests:

pxx (pascal26) — self-hosting Pascal-dialect compiler
  generation:  26   (the value {$IF PXX_VERSION >= n} tests)
  frontends:   pascal c nilpy rust zig ada basic fortran algol erlang lolcode whitespace
  host arch:   x86-64 linux

That frontend list is every frontend compiled into the binary, and they sit at very different stages. The ones these docs cover in depth are Pascal, C and Nil Python; the rest are a real BASIC frontend, two experimental ones, and six skeleton probes, and their presence in the list is not a support claim. See Other frontends for which is which.

--where — the one to reach for first

When a build cannot find a unit or a header, --where is the answer, because it prints the paths from the code that resolves them rather than from a rule written down separately. It marks each root that does not exist [MISSING], and ends with the tier order in force:

Library roots (as ParseUsesUnit resolves them):
  /opt/pxx/lib/rtl/   [RTL]
  /opt/pxx/lib/pcl/   [PCL]
  ...

Pascal unit search roots, in order (-Fu goes in FRONT of these):
  /opt/pxx/../lib/rtl/platform/posix/   [MISSING]
  /opt/pxx/lib/rtl/platform/posix/

Tier order: -Fu/-I  >  PXX_HOME/PXX_LIBPATH  >  pxx.cfg  >  exe-dir defaults.

--config is an exact alias — same output, same exit — for when the question is phrased as "which pxx.cfg is in effect?" rather than "where is the RTL?". (Deliberately not called "byte-identical": in these docs that phrase is reserved for two specific technical claims, and reusing it for two flags that print the same thing would blur a distinction worth keeping. The two claims are not the same claim — in the self-host fixedpoint it is the binary that is identical, to our own previous output; in the gcc-oracle corpora it is a compiled program's output that is identical, to the output of the same program built with gcc. PXX does not emit gcc's machine code. See Status.)

One subtlety worth knowing: -Fu and -I given before --where on the command line appear in its output, and ones given after it do not — --where answers where it is read.

--doctor — capability, not correctness

--doctor reports what this box can do with this binary: native compilation, whether the RTL, builtin units and C headers were found, which cross targets can actually be run here through qemu, whether an ESP-IDF and Espressif toolchain are present, and whether an FPC seed, gdb and gcc are around for compiler development. Every no row names what to install.

Nothing in it is fatal. Compiling and running a native program needs none of the optional rows; each no costs exactly the one capability its row names.

Options

Strictness and dialect

PXX is lax by default and turns FPC-parity checks on individually. See the compiler modes page for the whole lax → --strict → granular → --mimic-fpc model; each flag below is documented there in context. The directive column names the in-source directive with the same effect where one exists.

Runtime and codegen

--experimental-ir-codegen is accepted as a deprecated no-op (IR is the only backend).

Float errors are quiet by default

The default is the part a Pascal reader will not expect, and it is a decision rather than an omission: PXX leaves the float exceptions masked, so 1.0/0.0 evaluates to +Inf, 0.0/0.0 to NaN, and the program keeps running. FPC unmasks at startup and aborts; PXX does not. The reasoning is that measurement and streaming data with out-of-bounds inputs is better served by Inf/NaN propagating through a computation than by an abort partway into it.

--fpc-float-errors is how a program asks for FPC's behaviour instead. The same program compiled with and without it:

$ pxx --fpc-float-errors trap.pas trap && ./trap div
Runtime error 208 (division by zero)          # exit status 208

$ pxx trap.pas trap && ./trap div
no trap, r= Inf                               # exit status 0

Overflow (1e308 * 10) reports 205 and invalid (0.0/0.0) reports 207 under the flag. Underflow and inexact stay masked, exactly as they do under FPC, so runtime error 206 is decoded but never armed by the flag alone.

The flag is program-wide and set at compile time. To change the mask for one region at runtime, use GetExceptionMask / SetExceptionMask from the math unit, which take and return an FPC-compatible TFPUExceptionMask.

Diagnostics and internal flags

The --warn-* flags are opt-in diagnostics you can run against ordinary source; each is off by default and none changes what is compiled. The dump and measure flags below them serve compiler development and self-inspection — use those only when directed.

Search paths

The wrapper created by install.sh already passes the bundled lib/ roots. Use -Fu for project-local units:

./pxx -Fusrc -Fulib/more app.pas app

Search roots are checked in flag order before the default library roots. That lets a project override or add units deliberately without changing the checkout.

The full order — flags, then environment, then pxx.cfg, then the defaults guessed from the binary's location — is printed by pxx --where (see Information flags above), which reads it from the resolver itself. Prefer running it over trusting a copy of the rule.

Use -I for C headers. It also feeds the Pascal unit search path, which is useful for generated bindings that sit next to the imported header:

./pxx -Iinclude main.pas main

Environment and pxx.cfg

Three environment variables and one optional config file sit between the command-line flags and the defaults the compiler guesses from its own location. Run pxx --where to see which of them are actually in effect — it prints all of them, set or unset.

PXX_HOME is what makes an unpacked tarball work from any directory, and it is honoured all-or-nothing: the exe-dir guesses are not kept underneath it as a fallback. Point it at the wrong root and the RTL is simply not found —

error: uses: unit source not found: platform_backend

— which is --where territory, and every root will be marked [MISSING].

The config file

If PXX_CONFIG is unset, the compiler takes the first of these that exists: ./pxx.cfg, ~/.config/pxx/pxx.cfg, <exe dir>/pxx.cfg. Three directives are understood today:

home      /opt/pxx
unitpath  /opt/units
incpath   /opt/inc

--where echoes the file it chose and the directives it read from it, so a config that is not taking effect is one command away from explaining itself. Per-library define and mode manifests are not implemented.

Examples

./pxx --where
./pxx --doctor
./pxx hello.pas hello
./pxx -g hello.pas hello
./pxx --target=aarch64 hello.pas hello.a64
./pxx -dDEBUG hello.pas hello
./pxx -Fusrc -Iinclude app.pas app
./pxx --target=riscv32 --esp-profile=bare main.pas main.o

Next

• Compiler modes and strictness
• Compiler directives
• Install
• Targets