local compiler directives

│ Deutsch (de) │ English (en) │ français (fr) │

Local compiler directives may be used more than once in a Pascal source code file.

Syntax

• {$cOperators} enables usage of operators similar to conventions of in the C language.
• {$goto} enables goto and label.
• {$inline} allows the inline modifier.
• {$LongStrings} or {$H} determines the data type referenced by the reserved word string.
• {$macro} enables usage of macros.
• {$scopedEnums} whether enumeration type members have to be referred to by the data types name as a scope. (since FPC 2.6.0)
• {$static} enable usage of the reserved word static (until FPC 2.6.0).
• {$typedAddress} or {$T} determines, if the address operator @ results in a typed or untyped pointer.
• {$varStringChecks} and {$V} enables strict checking of assignment compatibility of string variables.
• {$writableConst} or {$J} enables assignment of values to typed constants during run-time.

Data layout

• {$align} and {$A} determine the alignment of data in records
• {$bitpacking} determines, whether packed is interpreted as bitpacked.
• {$codeAlign} determines the code-alignment in memory.
• {$minEnumSize} recognized for Delphi-compatibility and has the same effect as the {$packEnum} directive.
• {$minFPConstPrec} sets the minimum accuracy floating-point constants are stored at.
• {$packEnum} or {$Z} enables packing of enumeration types.
• {$packRecords} determines alignment of records in memory.
• {$packSet} determines packing of sets.

Code generation

• {$boolEval} and {$B} controls short-cut evaluation of Boolean expressions
• {$assertions} or {$C} control, whether assert statements are compiled into the executable program
• {$calling} determines the calling conventions for routines.
• {$checkPointer} in conjunction with ‑gh inserts checks ascertain validity of pointers.
• {$FPUType} compiles according to FPU type.
• {$ieeeErrors} turns on IEEE error checking for floating-point constants.
• {$implicitExceptions} controls insertion of implicit exceptions which aid prevention of memory leaks.
• {$interfaces}
• {$IOChecks} or {$I} enables checks of input/output.
• {$objectChecks} inserts code ensuring self is non-nil
• {$optimization} switches on certain optimizations.
• {$overflowChecks} or {$Q} determines if overflow checks are inserted after arithmetic operations. In {$mode MacPas} the directive {$OV} is available, too.
• {$rangeChecks} or {$R} determines insertion of code ensuring a value is within the permitted range.
• {$S} creates code to check for stack overflows
• {$stackFrames} or {$W} determines conditions for the creation of stack frames.

$R versus $Q

There is the completely artificial distinction between the meaning of "overflow" and "range check" errors as defined by Borland. They are basically exactly the same error, except that one is detected by checking the overflow flag of the CPU and the other by explicitly comparing ranges.

On 64 bit CPUs, integer arithmetic is performed using 64 bit integers because of Pascal's convention to evaluate expressions using the native signed integer type. As a result, overflows cannot occur there when performing 32 bit arithmetic and you will get a range error instead when assigning the result to a 32 bit variable. Ideally, there would be only a single switch that governs both range/overflow checking, but because of historical reasons (as explained above) there are two.

Platform-specific

For x86 processors only

• {$asmMode} determines the syntax the assembler reader expects. Previously, this has been the {$i386…} directives.
• {$MMX} enables optimizations for MMX processors.
• {$safeFPUExceptions}, whether fwait instructions are inserted
• {$saturation} (in conjunction with {$MMX}) enables saturation operations.
• {$maxFPUregisters} determines the maximum number of floating-points registers to use.

Other

• {$linkFramework} inserts a framework. This directive is only available on Darwin-based operating systems.

Data inclusion

• {$link} or {$L} inserts an object file during linking.
• {$linkLib} inserts a library during linking.
• {$typeInfo} or {$M} creates run-time type information.
• {$resource} or {$R} inserts a resource file.

Compile-time context

• {$define} defines a symbol. In {$mode MacPas} the directive {$defineC} is considered, too.
• {$include} or {$I} reads a file as source or includes certain compile-time/compiler information.
• {$push} and {$pop} store and restore the compiler settings.
• {$setC} sets a compile-time variable, if the current mode allows it.
• {$undef} dismisses the definition of a previously defined symbol. In {$mode MacPas} the directive {$undefC} is recognized, too.

Conditional compilation

Conditional compilation can be achieved via the directives

• {$if}
• {$else}
• {$elseIf}
• {$endIf}
• {$ifDef}
• {$ifNDef}
• {$ifOpt}

Additionally, in {$mode MacPas} the directives

• {$ifC},
• {$elseC},
• {$elIfC}, and
• {$endC}

are allowed, too.

Compile-time behavior

With {$wait}, the compiler waits till the user hits ↵ Enter, and then resumes compilation.

Self-defined messages can be triggered with the directives:

• {$message}, and the shortcuts
  • {$stop}, which also aborts compilation
  • {$fatal}, which also aborts compilation
  • {$error} (in {$mode MacPas} the directive {$errorC} is accepted, too)
  • {$warning}
  • {$hint}
  • {$note}
• {$info}

Emission of messages can be controlled via the directives:

• {$warn} for specific warnings, or
• all messages of one kind in one go:
  • {$warnings}
  • {$hints}
  • {$notes}

Ignored

Since FPC intends to be sort of compatible to some other compilers, some very common compiler directives stemming from the non-FPC-lands are recognized – not generating an illegal directive error – and ignored. Those are:

• {$F} (far or near functions)
• {$extendedSym}
• {$externalSym}
• {$hppEmit}
• {$libExport}
• {$noDefine}
• {$region} and {$endRegion}
• {$stringChecks} which in Delphi, this would control the generation of code that checks the sanity of string variables and arguments.

Historical

Following directives were recognized in earlier versions of FPC and are now illegal:

• {$output_format} determined the output format of an object file.

See also

• Pascal basics
• § “Local directives” in the Free Pascal programmer’s guide