local compiler directives: what changed
Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.
Title: local compiler directives
| Old | New | Line | |
|---|---|---|---|
| 1 | + | Local [[Compiler directive|compiler directives]] may be used more than once in a Pascal [[Source code|source code]] file. | |
| 2 | + | ||
| 3 | + | ## Syntax | |
| 4 | + | ||
| 5 | + | - `{$cOperators}` enables usage of [[Operator|operators]] similar to conventions of in the [[Pascal for C users|C]] language. | |
| 6 | + | - [[sGoto|{$goto}]] enables [[Goto|goto]] and [[Label|label]]. | |
| 7 | + | - `{$inline}` allows the [[Inline|inline]] [[modifier]]. | |
| 8 | + | - [[$H|{$LongStrings} or {$H}]] determines the data type referenced by the reserved word [[String|string]]. | |
| 9 | + | - `{$macro}` enables usage of [[Macros|macros]]. | |
| 10 | + | - [[$scopedEnums|{$scopedEnums}]] whether enumeration type members have to be referred to by the data types name as a scope. (since [[FPC New Features 2.6.0|FPC 2.6.0]]) | |
| 11 | + | - [[$static|{$static}]] enable usage of the reserved word `static` (until [[User Changes 2.6.0|FPC 2.6.0]]). | |
| 12 | + | - [[$typedAddress|{$typedAddress} or {$T}]] determines, if the address operator [[@]] results in a typed or untyped pointer. | |
| 13 | + | - [[$varStringChecks|{$varStringChecks} and {$V}]] enables strict checking of assignment compatibility of string variables. | |
| 14 | + | - [[$writableConst|{$writableConst} or {$J}]] enables assignment of values to typed [[Constant|constants]] during [[runtime|run-time]]. | |
| 15 | + | ||
| 16 | + | ## Data layout | |
| 17 | + | ||
| 18 | + | - [[$A|{$align}]] and [[$A|{$A}]] determine the alignment of data in records | |
| 19 | + | - [[$Bitpacking|{$bitpacking}]] determines, whether `packed` is interpreted as `bitpacked`. | |
| 20 | + | - [[$codeAlign|{$codeAlign}]] determines the code-alignment in memory. | |
| 21 | + | - `{$minEnumSize}` recognized for Delphi-compatibility and has the same effect as the `{$packEnum}` directive. | |
| 22 | + | - [[$minFPConstPrec|{$minFPConstPrec}]] sets the minimum accuracy floating-point constants are stored at. | |
| 23 | + | - [[$packEnum|{$packEnum} or {$Z}]] enables packing of enumeration types. | |
| 24 | + | - [[$packRecords|{$packRecords}]] determines alignment of [[Record|records]] in memory. | |
| 25 | + | - [[$packSet|{$packSet}]] determines packing of [[Set|sets]]. | |
| 26 | + | ||
| 27 | + | ## Code generation | |
| 28 | + | ||
| 29 | + | - [[$boolEval|{$boolEval} and {$B}]] controls short-cut evaluation of Boolean expressions | |
| 30 | + | - [[$Assertions|{$assertions}]] or `{$C}` control, whether [[assert|assert statements]] are compiled into the [[Executable program|executable program]] | |
| 31 | + | - [[$calling|{$calling}]] determines the calling conventions for routines. | |
| 32 | + | - [[$checkPointer|{$checkPointer}]] in conjunction with [[heaptrc|‑gh]] inserts checks ascertain validity of [[Pointer|pointers]]. | |
| 33 | + | - [[$FPUtype|{$FPUType}]] compiles according to FPU type. | |
| 34 | + | - [[$ieeeERRORS|{$ieeeErrors}]] turns on IEEE error checking for floating-point constants. | |
| 35 | + | - [[$implicitExceptions|{$implicitExceptions}]] controls insertion of implicit exceptions which aid prevention of memory leaks. | |
| 36 | + | - [[$interfaces|{$interfaces}]] | |
| 37 | + | - [[$IOChecks|{$IOChecks} or {$I}]] enables checks of input/output. | |
| 38 | + | - [[$objectChecks|{$objectChecks}]] inserts code ensuring [[Self|self]] is non-[[Nil|nil]] | |
| 39 | + | - [[$optimization|{$optimization}]] switches on certain optimizations. | |
| 40 | + | - [[$overflowChecks|{$overflowChecks} or {$Q}]] determines if overflow checks are inserted after arithmetic operations. In `{$mode MacPas}` the directive `{$OV}` is available, too. | |
| 41 | + | - [[$rangeChecks|{$rangeChecks} or {$R}]] determines insertion of code ensuring a value is within the permitted range. | |
| 42 | + | - [[$S|{$S}]] creates code to check for stack overflows | |
| 43 | + | - [[$stackFrames|{$stackFrames} or {$W}]] determines conditions for the creation of stack frames. | |
| 44 | + | ||
| 45 | + | ### \$R versus \$Q | |
| 46 | + | ||
| 47 | + | 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. | |
| 48 | + | ||
| 49 | + | 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. | |
| 50 | + | ||
| 51 | + | ## Platform-specific | |
| 52 | + | ||
| 53 | + | ### For x86 processors only | |
| 54 | + | ||
| 55 | + | - [[$asmMode|{$asmMode}]] determines the syntax the assembler reader expects. Previously, this has been the `{$i386…}` directives. | |
| 56 | + | - [[$MMX|{$MMX}]] enables optimizations for MMX processors. | |
| 57 | + | - [[$safeFPUExceptions|{$safeFPUExceptions}]], whether `fwait` instructions are inserted | |
| 58 | + | - [[$saturation|{$saturation}]] (in conjunction with `{$MMX}`) enables saturation operations. | |
| 59 | + | - [[$maxFPUregisters|{$maxFPUregisters}]] determines the maximum number of floating-points registers to use. | |
| 60 | + | ||
| 61 | + | ### Other | |
| 62 | + | ||
| 63 | + | - [[$linkFramework|{$linkFramework}]] inserts a framework. This directive is only available on Darwin-based operating systems. | |
| 64 | + | ||
| 65 | + | ## Data inclusion | |
| 66 | + | ||
| 67 | + | - [[$link|{$link} or {$L}]] inserts an object file during linking. | |
| 68 | + | - [[$linkLib|{$linkLib}]] inserts a library during linking. | |
| 69 | + | - [[$typeInfo|{$typeInfo} or {$M}]] creates [[Runtime Type Information (RTTI)|run-time type information]]. | |
| 70 | + | - [[$resource|{$resource} or {$R}]] inserts a resource file. | |
| 71 | + | ||
| 72 | + | ## Compile-time context | |
| 73 | + | ||
| 74 | + | - [[$define|{$define}]] defines a symbol. In `{$mode MacPas}` the directive `{$defineC}` is considered, too. | |
| 75 | + | - [[$include|{$include} or {$I}]] reads a file as source or includes certain compile-time/compiler information. | |
| 76 | + | - [[$push and $pop|{$push} and {$pop}]] store and restore the compiler settings. | |
| 77 | + | - `{$setC}` sets a compile-time variable, if the current mode allows it. | |
| 78 | + | - `{$undef}` dismisses the definition of a previously defined symbol. In `{$mode MacPas}` the directive `{$undefC}` is recognized, too. | |
| 79 | + | ||
| 80 | + | ## Conditional compilation | |
| 81 | + | ||
| 82 | + | [[Conditional compilation]] can be achieved via the directives | |
| 83 | + | ||
| 84 | + | - `{$if}` | |
| 85 | + | - `{$else}` | |
| 86 | + | - `{$elseIf}` | |
| 87 | + | - `{$endIf}` | |
| 88 | + | - `{$ifDef}` | |
| 89 | + | - `{$ifNDef}` | |
| 90 | + | - `{$ifOpt}` | |
| 91 | + | ||
| 92 | + | Additionally, in `{$mode MacPas}` the directives | |
| 93 | + | ||
| 94 | + | - `{$ifC}`, | |
| 95 | + | - `{$elseC}`, | |
| 96 | + | - `{$elIfC}`, and | |
| 97 | + | - `{$endC}` | |
| 98 | + | ||
| 99 | + | are allowed, too. | |
| 100 | + | ||
| 101 | + | ## Compile-time behavior | |
| 102 | + | ||
| 103 | + | With `{$wait}`, the compiler waits till the user hits ↵ Enter, and then resumes compilation. | |
| 104 | + | ||
| 105 | + | Self-defined messages can be triggered with the directives: | |
| 106 | + | ||
| 107 | + | - [[$message|{$message}]], and the shortcuts | |
| 108 | + | - `{$stop}`, which also aborts compilation | |
| 109 | + | - `{$fatal}`, which also [[compile-time error|aborts compilation]] | |
| 110 | + | - `{$error}` (in [[Mode MacPas|{$mode MacPas}]] the directive `{$errorC}` is accepted, too) | |
| 111 | + | - `{$warning}` | |
| 112 | + | - `{$hint}` | |
| 113 | + | - `{$note}` | |
| 114 | + | - `{$info}` | |
| 115 | + | ||
| 116 | + | Emission of messages can be controlled via the directives: | |
| 117 | + | ||
| 118 | + | - [[$warn|{$warn}]] for specific warnings, or | |
| 119 | + | - all messages of one kind in one go: | |
| 120 | + | - `{$warnings}` | |
| 121 | + | - `{$hints}` | |
| 122 | + | - `{$notes}` | |
| 123 | + | ||
| 124 | + | ## Ignored | |
| 125 | + | ||
| 126 | + | 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: | |
| 127 | + | ||
| 128 | + | - `{$F}` (far or near functions) | |
| 129 | + | - `{$extendedSym}` | |
| 130 | + | - `{$externalSym}` | |
| 131 | + | - `{$hppEmit}` | |
| 132 | + | - `{$libExport}` | |
| 133 | + | - `{$noDefine}` | |
| 134 | + | - `{$region}` and `{$endRegion}` | |
| 135 | + | - `{$stringChecks}` which in Delphi, this would control the generation of code that checks the sanity of string variables and arguments. | |
| 136 | + | ||
| 137 | + | ## Historical | |
| 138 | + | ||
| 139 | + | Following directives were recognized in earlier versions of FPC and are now illegal: | |
| 140 | + | ||
| 141 | + | - `{$output_format}` determined the output format of an object file. | |
| 142 | + | ||
| 143 | + | ## See also | |
| 144 | + | ||
| 145 | + | - [[Pascal basics]] | |
| 146 | + | - [§ “Local directives” in the *Free Pascal programmer’s guide*](https://www.freepascal.org/docs-html/prog/progse2.html) | |
| 147 | + | ||
| 148 | + | --- | |
| 149 | + | *From the Free Pascal wiki, page "local compiler directives", as it stood on 2021-09-04 after a change by Alextpp, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).* |