Compiler directives

Directives are {$...} comments the compiler reads while lexing. This page lists the directives PXX recognizes. Anything not listed here is accepted as an inert comment (so FPC sources with unsupported directives still compile), which means a misspelled directive is silently ignored rather than flagged.

Where a directive has an equivalent command-line flag, it is named in the table. The strictness switches are explained in context on the compiler modes page.

Conditional compilation

{$DEFINE} is scoped to the unit that writes it, as in FPC — a unit's define never reaches the program or any other unit. {$CLAIM} is the deliberate exception, for the claim-and-skip pattern: two units can supply the same capability, and whichever is compiled first claims the name so the second compiles itself out.

{$IFNDEF PXX_HAS_THE_THING}
  {$CLAIM PXX_HAS_THE_THING}
  { …this unit provides it… }
{$ENDIF}

A claim is order-dependent by construction, and that is the point — it is #ifndef GUARD / #define GUARD from C, at a spelling that says so. It is not retroactive: only sources scanned after the claim see it. pxx reads a source file whole before parsing it, so every conditional in the main program is resolved before its uses clause compiles anything — a program that wants the name must claim it itself, above its own uses.

{$IF} / {$ELSEIF} expressions support defined(NAME), declared(NAME), integer literals and defined integer symbols, the comparison operators, ! (not), and parentheses. A bare non-zero integer is true ({$IF 1} / {$IF 0}). Float literals are rejected.

Includes and resources

Check switches

Short toggles use a trailing + (on) or - (off); the long forms take ON / OFF.

{$NILCHECKS} is tri-state

The Default column cannot hold one answer, because there is not one. The compiler distinguishes on, off, and the author said nothing — and the two kinds of site resolve that third state in opposite directions:

So {$NILCHECKS ON} adds the deref checks and {$NILCHECKS OFF} removes the call checks; each is a no-op for the other class. --no-nil-check is the master off for both, and it outranks the directive — a source that says {$NILCHECKS ON} still gets no checks under that flag.

The split follows the cost. A call check is about 2% and replaces a fault that lands frames away from the call, or on a target with no signal runtime does not land at all. A deref check is a test inside whatever loop the deref sits in — measured at +6% on a loop doing nothing else — and on PC targets the MMU already reports it at exactly the right instruction.

What a checked site does when it fires

It calls PXXNilRef, which prints Runtime error 216 (nil reference) and halts. With SysUtils in the program it instead raises a catchable EAccessViolation, and that is the point of the feature — a raw memory fault can never offer it, because try..except does not run for one.

The same program shows both halves. Unchecked, the except never runs:

program uncatchnil;
uses sysutils;
var p: ^Integer;
begin
  p := nil;
  try
    WriteLn(p^);
  except
    on E: Exception do WriteLn('caught: ', E.ClassName);
  end;
  WriteLn('still running');
end.

Segmentation fault (core dumped)

Add {$NILCHECKS ON} after the uses clause and the identical program prints:

caught: EAccessViolation
still running

A call on a nil instance is already checked without the directive, and carries the reason in its message — EAccessViolation: Access violation (nil reference).

Strictness and dialect switches

Each takes ON / OFF and has a matching command-line flag — see compiler modes.

Layout, comments, and dialect

Runtime knobs and messages

The per-thread variable area

threadvar storage comes out of a fixed area carved into every thread's block, 3072 bytes by default. It costs that much of BSS and of each thread's stack whether or not the program declares a single threadvar, so it is settable per compile — as a define, because a define needs no new option:

Measured on an x86-64 hello, BSS at each rung: 35,324 / 36,348 / 37,372 / 38,396 / 39,420 / 43,516 / 51,708 — exactly the area's own difference each time. -dPXX_TLS_USER_0 is the right setting for a program with no threadvar, which is most of them.

It is a cap, not a budget. A program whose threadvars do not fit is refused at compile time, with a diagnostic naming the rung to raise to; it is never quietly given storage the reserved block does not contain. That is what makes the setting safe in both directions, and it is why the size must be fixed on the command line rather than grown as declarations are parsed: the block is reserved, and __pxxTlsBlockSize folds to a literal, before the first line of the program is read.

The RTL follows the setting without being rebuilt — lib/rtl/palthread.pas reads the real block size through __pxxTlsBlockSize rather than restating it.

Next

• Command line
• Compiler modes and strictness
• FPC compatibility