Difference between revisions of "local compiler directives"

From Free Pascal wiki
Jump to navigationJump to search
m (→‎Syntax: Fixed page link)
 
(10 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{local compiler directives}}
 
{{local compiler directives}}
  
Local compiler directives may be used more than once in a Pascal [[Source code|source code]] file.
+
Local [[Compiler directive|compiler directives]] may be used more than once in a Pascal [[Source code|source code]] file.
  
 
== Syntax ==
 
== Syntax ==
 
 
* <syntaxhighlight lang="pascal" inline>{$cOperators}</syntaxhighlight> enables usage of [[Operator|operators]] similar to conventions of in the [[Pascal for C users|C]] language.
 
* <syntaxhighlight lang="pascal" inline>{$cOperators}</syntaxhighlight> enables usage of [[Operator|operators]] similar to conventions of in the [[Pascal for C users|C]] language.
* <syntaxhighlight lang="pascal" inline>{$goto}</syntaxhighlight> enables [[Goto|<syntaxhighlight lang="pascal" inline>goto</syntaxhighlight>]] and [[Label|<syntaxhighlight lang="pascal" inline>label</syntaxhighlight>]].
+
* [[sGoto|<syntaxhighlight lang="pascal" inline>{$goto}</syntaxhighlight>]] enables [[Goto|<syntaxhighlight lang="pascal" inline>goto</syntaxhighlight>]] and [[Label|<syntaxhighlight lang="pascal" inline>label</syntaxhighlight>]].
* <syntaxhighlight lang="pascal" inline>{$inline}</syntaxhighlight> allows the [[inline|<syntaxhighlight lang="pascal" inline>inline</syntaxhighlight>]] [[Modifiers|modifier]].
+
* <syntaxhighlight lang="pascal" inline>{$inline}</syntaxhighlight> allows the [[Inline|<syntaxhighlight lang="pascal" inline>inline</syntaxhighlight>]] [[modifier]].
 
* [[$H|<syntaxhighlight lang="pascal" inline>{$LongStrings}</syntaxhighlight> or <syntaxhighlight lang="pascal" inline>{$H}</syntaxhighlight>]] determines the data type referenced by the reserved word [[String|<syntaxhighlight lang="pascal" inline>string</syntaxhighlight>]].
 
* [[$H|<syntaxhighlight lang="pascal" inline>{$LongStrings}</syntaxhighlight> or <syntaxhighlight lang="pascal" inline>{$H}</syntaxhighlight>]] determines the data type referenced by the reserved word [[String|<syntaxhighlight lang="pascal" inline>string</syntaxhighlight>]].
 
* <syntaxhighlight lang="pascal" inline>{$macro}</syntaxhighlight> enables usage of [[Macros|macros]].
 
* <syntaxhighlight lang="pascal" inline>{$macro}</syntaxhighlight> enables usage of [[Macros|macros]].
Line 17: Line 16:
  
 
== Data layout ==
 
== Data layout ==
 
 
* [[$A|<syntaxhighlight lang="pascal" inline>{$align}</syntaxhighlight>]] and [[$A|<syntaxhighlight lang="pascal" inline>{$A}</syntaxhighlight>]] determine the alignment of data in records
 
* [[$A|<syntaxhighlight lang="pascal" inline>{$align}</syntaxhighlight>]] and [[$A|<syntaxhighlight lang="pascal" inline>{$A}</syntaxhighlight>]] determine the alignment of data in records
 
* [[$Bitpacking|<syntaxhighlight lang="pascal" inline>{$bitpacking}</syntaxhighlight>]] determines, whether <syntaxhighlight lang="pascal" inline>packed</syntaxhighlight> is interpreted as <syntaxhighlight lang="pascal" inline>bitpacked</syntaxhighlight>.
 
* [[$Bitpacking|<syntaxhighlight lang="pascal" inline>{$bitpacking}</syntaxhighlight>]] determines, whether <syntaxhighlight lang="pascal" inline>packed</syntaxhighlight> is interpreted as <syntaxhighlight lang="pascal" inline>bitpacked</syntaxhighlight>.
Line 28: Line 26:
  
 
== Code generation ==
 
== Code generation ==
 
 
* [[$boolEval|<syntaxhighlight lang="pascal" inline>{$boolEval}</syntaxhighlight> and <syntaxhighlight lang="pascal" inline>{$B}</syntaxhighlight>]] controls short-cut evaluation of Boolean expressions
 
* [[$boolEval|<syntaxhighlight lang="pascal" inline>{$boolEval}</syntaxhighlight> and <syntaxhighlight lang="pascal" inline>{$B}</syntaxhighlight>]] controls short-cut evaluation of Boolean expressions
* <syntaxhighlight lang="pascal" inline>{$assertions}</syntaxhighlight> or <syntaxhighlight lang="pascal" inline>{$C}</syntaxhighlight> control, whether [[assert|<syntaxhighlight lang="pascal" inline>assert</syntaxhighlight> statements]] are compiled into the [[Executable program|executable program]]
+
* [[$Assertions|<syntaxhighlight lang="pascal" inline>{$assertions}</syntaxhighlight>]] or <syntaxhighlight lang="pascal" inline>{$C}</syntaxhighlight> control, whether [[assert|<syntaxhighlight lang="pascal" inline>assert</syntaxhighlight> statements]] are compiled into the [[Executable program|executable program]]
 
* [[$calling|<syntaxhighlight lang="pascal" inline>{$calling}</syntaxhighlight>]] determines the calling conventions for routines.
 
* [[$calling|<syntaxhighlight lang="pascal" inline>{$calling}</syntaxhighlight>]] determines the calling conventions for routines.
* [[$checkPointer|<syntaxhighlight lang="pascal" inline>{$checkPointer}</syntaxhighlight>]] inserts checks ascertain validity of [[Pointer|pointers]].
+
* [[$checkPointer|<syntaxhighlight lang="pascal" inline>{$checkPointer}</syntaxhighlight>]] in conjunction with [[heaptrc|<syntaxhighlight lang="text" inline>‑gh</syntaxhighlight>]] inserts checks ascertain validity of [[Pointer|pointers]].
 
* [[$FPUtype|<syntaxhighlight lang="pascal" inline>{$FPUType}</syntaxhighlight>]] compiles according to FPU type.
 
* [[$FPUtype|<syntaxhighlight lang="pascal" inline>{$FPUType}</syntaxhighlight>]] compiles according to FPU type.
 
* [[$ieeeERRORS|<syntaxhighlight lang="pascal" inline>{$ieeeErrors}</syntaxhighlight>]] turns on IEEE error checking for floating-point constants.
 
* [[$ieeeERRORS|<syntaxhighlight lang="pascal" inline>{$ieeeErrors}</syntaxhighlight>]] turns on IEEE error checking for floating-point constants.
 
* [[$implicitExceptions|<syntaxhighlight lang="pascal" inline>{$implicitExceptions}</syntaxhighlight>]] controls insertion of implicit exceptions which aid prevention of memory leaks.
 
* [[$implicitExceptions|<syntaxhighlight lang="pascal" inline>{$implicitExceptions}</syntaxhighlight>]] controls insertion of implicit exceptions which aid prevention of memory leaks.
* [[$interfaces|<syntaxhighlight lang="pascal" inline>{$interfacse}</syntaxhighlight>]]
+
* [[$interfaces|<syntaxhighlight lang="pascal" inline>{$interfaces}</syntaxhighlight>]]
 
* [[$IOChecks|<syntaxhighlight lang="pascal" inline>{$IOChecks}</syntaxhighlight> or <syntaxhighlight lang="pascal" inline>{$I}</syntaxhighlight>]] enables checks of input/output.
 
* [[$IOChecks|<syntaxhighlight lang="pascal" inline>{$IOChecks}</syntaxhighlight> or <syntaxhighlight lang="pascal" inline>{$I}</syntaxhighlight>]] enables checks of input/output.
 
* [[$objectChecks|<syntaxhighlight lang="pascal" inline>{$objectChecks}</syntaxhighlight>]] inserts code ensuring [[Self|<syntaxhighlight lang="pascal" inline>self</syntaxhighlight>]] is non-[[Nil|<syntaxhighlight lang="pascal" inline>nil</syntaxhighlight>]]
 
* [[$objectChecks|<syntaxhighlight lang="pascal" inline>{$objectChecks}</syntaxhighlight>]] inserts code ensuring [[Self|<syntaxhighlight lang="pascal" inline>self</syntaxhighlight>]] is non-[[Nil|<syntaxhighlight lang="pascal" inline>nil</syntaxhighlight>]]
Line 44: Line 41:
 
* [[$S|<syntaxhighlight lang="pascal" inline>{$S}</syntaxhighlight>]] creates code to check for stack overflows
 
* [[$S|<syntaxhighlight lang="pascal" inline>{$S}</syntaxhighlight>]] creates code to check for stack overflows
 
* [[$stackFrames|<syntaxhighlight lang="pascal" inline>{$stackFrames}</syntaxhighlight> or <syntaxhighlight lang="pascal" inline>{$W}</syntaxhighlight>]] determines conditions for the creation of stack frames.
 
* [[$stackFrames|<syntaxhighlight lang="pascal" inline>{$stackFrames}</syntaxhighlight> or <syntaxhighlight lang="pascal" inline>{$W}</syntaxhighlight>]] 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 ==
 
== Platform-specific ==
 
 
=== For x86 processors only ===
 
=== For x86 processors only ===
 
 
* [[$asmMode|<syntaxhighlight lang="pascal" inline>{$asmMode}</syntaxhighlight>]] determines the syntax the assembler reader expects. Previously, this has been the <syntaxhighlight lang="pascal" inline>{$i386…}</syntaxhighlight> directives.
 
* [[$asmMode|<syntaxhighlight lang="pascal" inline>{$asmMode}</syntaxhighlight>]] determines the syntax the assembler reader expects. Previously, this has been the <syntaxhighlight lang="pascal" inline>{$i386…}</syntaxhighlight> directives.
 
* [[$MMX|<syntaxhighlight lang="pascal" inline>{$MMX}</syntaxhighlight>]] enables optimizations for MMX processors.
 
* [[$MMX|<syntaxhighlight lang="pascal" inline>{$MMX}</syntaxhighlight>]] enables optimizations for MMX processors.
Line 56: Line 57:
  
 
=== Other ===
 
=== Other ===
 
 
* [[$linkFramework|<syntaxhighlight lang="pascal" inline>{$linkFramework}</syntaxhighlight>]] inserts a framework. This directive is only available on Darwin-based operating systems.
 
* [[$linkFramework|<syntaxhighlight lang="pascal" inline>{$linkFramework}</syntaxhighlight>]] inserts a framework. This directive is only available on Darwin-based operating systems.
  
 
== Data inclusion ==
 
== Data inclusion ==
 
 
* [[$link|<syntaxhighlight lang="pascal" inline>{$link}</syntaxhighlight> or <syntaxhighlight lang="pascal" inline>{$L}</syntaxhighlight>]] inserts an object file during linking.
 
* [[$link|<syntaxhighlight lang="pascal" inline>{$link}</syntaxhighlight> or <syntaxhighlight lang="pascal" inline>{$L}</syntaxhighlight>]] inserts an object file during linking.
 
* [[$linkLib|<syntaxhighlight lang="pascal" inline>{$linkLib}</syntaxhighlight>]] inserts a library during linking.
 
* [[$linkLib|<syntaxhighlight lang="pascal" inline>{$linkLib}</syntaxhighlight>]] inserts a library during linking.
 
* [[$typeInfo|<syntaxhighlight lang="pascal" inline>{$typeInfo}</syntaxhighlight> or <syntaxhighlight lang="pascal" inline>{$M}</syntaxhighlight>]] creates [[Runtime Type Information (RTTI)|run-time type information]].
 
* [[$typeInfo|<syntaxhighlight lang="pascal" inline>{$typeInfo}</syntaxhighlight> or <syntaxhighlight lang="pascal" inline>{$M}</syntaxhighlight>]] creates [[Runtime Type Information (RTTI)|run-time type information]].
* [[$output_format|<syntaxhighlight lang="pascal" inline>{$output_format}</syntaxhighlight>]] determines output format of an object file.
 
 
* [[$resource|<syntaxhighlight lang="pascal" inline>{$resource}</syntaxhighlight> or <syntaxhighlight lang="pascal" inline>{$R}</syntaxhighlight>]] inserts a resource file.
 
* [[$resource|<syntaxhighlight lang="pascal" inline>{$resource}</syntaxhighlight> or <syntaxhighlight lang="pascal" inline>{$R}</syntaxhighlight>]] inserts a resource file.
  
 
== Compile-time context ==
 
== Compile-time context ==
 
 
* [[$define|<syntaxhighlight lang="pascal" inline>{$define}</syntaxhighlight>]] defines a symbol. In <syntaxhighlight lang="pascal" inline>{$mode MacPas}</syntaxhighlight> the directive <syntaxhighlight lang="pascal" inline>{$defineC}</syntaxhighlight> is considered, too.
 
* [[$define|<syntaxhighlight lang="pascal" inline>{$define}</syntaxhighlight>]] defines a symbol. In <syntaxhighlight lang="pascal" inline>{$mode MacPas}</syntaxhighlight> the directive <syntaxhighlight lang="pascal" inline>{$defineC}</syntaxhighlight> is considered, too.
 
* [[$include|<syntaxhighlight lang="pascal" inline>{$include}</syntaxhighlight> or <syntaxhighlight lang="pascal" inline>{$I}</syntaxhighlight>]] reads a file as source or includes certain compile-time/compiler information.
 
* [[$include|<syntaxhighlight lang="pascal" inline>{$include}</syntaxhighlight> or <syntaxhighlight lang="pascal" inline>{$I}</syntaxhighlight>]] reads a file as source or includes certain compile-time/compiler information.
Line 76: Line 73:
  
 
== Conditional compilation ==
 
== Conditional compilation ==
 
 
[[Conditional compilation]] can be achieved via the directives
 
[[Conditional compilation]] can be achieved via the directives
 
 
* <syntaxhighlight lang="pascal" inline>{$if}</syntaxhighlight>
 
* <syntaxhighlight lang="pascal" inline>{$if}</syntaxhighlight>
 
* <syntaxhighlight lang="pascal" inline>{$else}</syntaxhighlight>
 
* <syntaxhighlight lang="pascal" inline>{$else}</syntaxhighlight>
Line 88: Line 83:
  
 
Additionally, in <syntaxhighlight lang="pascal" inline>{$mode MacPas}</syntaxhighlight> the directives
 
Additionally, in <syntaxhighlight lang="pascal" inline>{$mode MacPas}</syntaxhighlight> the directives
 
 
* <syntaxhighlight lang="pascal" inline>{$ifC}</syntaxhighlight>,
 
* <syntaxhighlight lang="pascal" inline>{$ifC}</syntaxhighlight>,
 
* <syntaxhighlight lang="pascal" inline>{$elseC}</syntaxhighlight>,
 
* <syntaxhighlight lang="pascal" inline>{$elseC}</syntaxhighlight>,
 
* <syntaxhighlight lang="pascal" inline>{$elIfC}</syntaxhighlight>, and
 
* <syntaxhighlight lang="pascal" inline>{$elIfC}</syntaxhighlight>, and
 
* <syntaxhighlight lang="pascal" inline>{$endC}</syntaxhighlight>
 
* <syntaxhighlight lang="pascal" inline>{$endC}</syntaxhighlight>
 
 
are allowed, too.
 
are allowed, too.
  
 
== Compile-time behavior ==
 
== Compile-time behavior ==
 
 
With <syntaxhighlight lang="pascal" inline>{$wait}</syntaxhighlight>, the compiler waits till the user hits ↵ Enter, and then resumes compilation.
 
With <syntaxhighlight lang="pascal" inline>{$wait}</syntaxhighlight>, the compiler waits till the user hits ↵ Enter, and then resumes compilation.
  
 
Self-defined messages can be triggered with the directives:
 
Self-defined messages can be triggered with the directives:
 
 
* [[$message|<syntaxhighlight lang="pascal" inline>{$message}</syntaxhighlight>]], and the shortcuts
 
* [[$message|<syntaxhighlight lang="pascal" inline>{$message}</syntaxhighlight>]], and the shortcuts
 
** <syntaxhighlight lang="pascal" inline>{$stop}</syntaxhighlight>, which also aborts compilation
 
** <syntaxhighlight lang="pascal" inline>{$stop}</syntaxhighlight>, which also aborts compilation
** <syntaxhighlight lang="pascal" inline>{$fatal}</syntaxhighlight>, which also aborts compilation
+
** <syntaxhighlight lang="pascal" inline>{$fatal}</syntaxhighlight>, which also [[compile-time error|aborts compilation]]
 
** <syntaxhighlight lang="pascal" inline>{$error}</syntaxhighlight> (in [[Mode MacPas|<syntaxhighlight lang="pascal" inline>{$mode MacPas}</syntaxhighlight>]] the directive <syntaxhighlight lang="pascal" inline>{$errorC}</syntaxhighlight> is accepted, too)
 
** <syntaxhighlight lang="pascal" inline>{$error}</syntaxhighlight> (in [[Mode MacPas|<syntaxhighlight lang="pascal" inline>{$mode MacPas}</syntaxhighlight>]] the directive <syntaxhighlight lang="pascal" inline>{$errorC}</syntaxhighlight> is accepted, too)
 
** <syntaxhighlight lang="pascal" inline>{$warning}</syntaxhighlight>
 
** <syntaxhighlight lang="pascal" inline>{$warning}</syntaxhighlight>
Line 112: Line 103:
  
 
Emission of messages can be controlled via the directives:
 
Emission of messages can be controlled via the directives:
 
 
* [[$warn|<syntaxhighlight lang="pascal" inline>{$warn}</syntaxhighlight>]] for specific warnings, or
 
* [[$warn|<syntaxhighlight lang="pascal" inline>{$warn}</syntaxhighlight>]] for specific warnings, or
 
* all messages of one kind in one go:
 
* all messages of one kind in one go:
Line 120: Line 110:
  
 
== Ignored ==
 
== 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.
 
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:
 
Those are:
 
 
* <syntaxhighlight lang="pascal" inline>{$F}</syntaxhighlight> (far or near functions)
 
* <syntaxhighlight lang="pascal" inline>{$F}</syntaxhighlight> (far or near functions)
 
* <syntaxhighlight lang="pascal" inline>{$extendedSym}</syntaxhighlight>
 
* <syntaxhighlight lang="pascal" inline>{$extendedSym}</syntaxhighlight>
Line 132: Line 120:
 
* <syntaxhighlight lang="pascal" inline>{$region}</syntaxhighlight> and <syntaxhighlight lang="pascal" inline>{$endRegion}</syntaxhighlight>
 
* <syntaxhighlight lang="pascal" inline>{$region}</syntaxhighlight> and <syntaxhighlight lang="pascal" inline>{$endRegion}</syntaxhighlight>
 
* <syntaxhighlight lang="pascal" inline>{$stringChecks}</syntaxhighlight> which in Delphi, this would control the generation of code that checks the sanity of string variables and arguments.
 
* <syntaxhighlight lang="pascal" inline>{$stringChecks}</syntaxhighlight> 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:
 +
* <syntaxhighlight lang="pascal" inline>{$output_format}</syntaxhighlight> determined the output format of an object file.
  
 
== See also ==
 
== See also ==
 
 
* [[Pascal basics]]
 
* [[Pascal basics]]
 
* [https://www.freepascal.org/docs-html/prog/progse2.html § “Local directives” in the ''Free Pascal programmer’s guide'']
 
* [https://www.freepascal.org/docs-html/prog/progse2.html § “Local directives” in the ''Free Pascal programmer’s guide'']
  
 
{{Directives, Defines and Conditionals}}
 
{{Directives, Defines and Conditionals}}

Latest revision as of 15:14, 4 September 2021

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

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

Syntax

Data layout

Code generation

$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

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

Directives, definitions and conditionals definitions
global compiler directives • local compiler directives

Conditional Compiler Options • Conditional compilation • Macros and Conditionals • Platform defines
$IF