Difference between revisions of "local compiler directives"

From Free Pascal wiki
m (Syntax: link existing page)
(correct documentation mistake: $output_format is illegal)
Line 2: Line 2:
  
 
Local [[Compiler directive|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 ==
Line 15: Line 16:
 
* [[$varStringChecks|<syntaxhighlight lang="pascal" inline>{$varStringChecks}</syntaxhighlight> and <syntaxhighlight lang="pascal" inline>{$V}</syntaxhighlight>]] enables strict checking of assignment compatibility of string variables.
 
* [[$varStringChecks|<syntaxhighlight lang="pascal" inline>{$varStringChecks}</syntaxhighlight> and <syntaxhighlight lang="pascal" inline>{$V}</syntaxhighlight>]] enables strict checking of assignment compatibility of string variables.
 
* [[$writableConst|<syntaxhighlight lang="pascal" inline>{$writableConst}</syntaxhighlight> or <syntaxhighlight lang="pascal" inline>{$J}</syntaxhighlight>]] enables assignment of values to typed [[Constant|constants]] during [[runtime|run-time]].
 
* [[$writableConst|<syntaxhighlight lang="pascal" inline>{$writableConst}</syntaxhighlight> or <syntaxhighlight lang="pascal" inline>{$J}</syntaxhighlight>]] enables assignment of values to typed [[Constant|constants]] during [[runtime|run-time]].
 +
  
 
== Data layout ==
 
== Data layout ==
Line 26: Line 28:
 
* [[$packRecords|<syntaxhighlight lang="pascal" inline>{$packRecords}</syntaxhighlight>]] determines alignment of [[Record|records]] in memory.
 
* [[$packRecords|<syntaxhighlight lang="pascal" inline>{$packRecords}</syntaxhighlight>]] determines alignment of [[Record|records]] in memory.
 
* [[$packSet|<syntaxhighlight lang="pascal" inline>{$packSet}</syntaxhighlight>]] determines packing of [[Set|sets]].
 
* [[$packSet|<syntaxhighlight lang="pascal" inline>{$packSet}</syntaxhighlight>]] determines packing of [[Set|sets]].
 +
  
 
== Code generation ==
 
== Code generation ==
Line 44: Line 47:
 
* [[$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.
 +
  
 
== Platform-specific ==
 
== Platform-specific ==
 +
  
 
=== For x86 processors only ===
 
=== For x86 processors only ===
Line 54: Line 59:
 
* [[$saturation|<syntaxhighlight lang="pascal" inline>{$saturation}</syntaxhighlight>]] (in conjunction with <syntaxhighlight lang="pascal" inline>{$MMX}</syntaxhighlight>) enables saturation operations.
 
* [[$saturation|<syntaxhighlight lang="pascal" inline>{$saturation}</syntaxhighlight>]] (in conjunction with <syntaxhighlight lang="pascal" inline>{$MMX}</syntaxhighlight>) enables saturation operations.
 
* [[$maxFPUregisters|<syntaxhighlight lang="pascal" inline>{$maxFPUregisters}</syntaxhighlight>]] determines the maximum number of floating-points registers to use.
 
* [[$maxFPUregisters|<syntaxhighlight lang="pascal" inline>{$maxFPUregisters}</syntaxhighlight>]] determines the maximum number of floating-points registers to use.
 +
  
 
=== 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 ==
Line 64: Line 71:
 
* [[$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 ==
Line 74: Line 81:
 
* <syntaxhighlight lang="pascal" inline>{$setC}</syntaxhighlight> sets a compile-time variable, if the current mode allows it.
 
* <syntaxhighlight lang="pascal" inline>{$setC}</syntaxhighlight> sets a compile-time variable, if the current mode allows it.
 
* <syntaxhighlight lang="pascal" inline>{$undef}</syntaxhighlight> dismisses the definition of a previously defined symbol. In <syntaxhighlight lang="pascal" inline>{$mode MacPas}</syntaxhighlight> the directive <syntaxhighlight lang="pascal" inline>{$undefC}</syntaxhighlight> is recognized, too.
 
* <syntaxhighlight lang="pascal" inline>{$undef}</syntaxhighlight> dismisses the definition of a previously defined symbol. In <syntaxhighlight lang="pascal" inline>{$mode MacPas}</syntaxhighlight> the directive <syntaxhighlight lang="pascal" inline>{$undefC}</syntaxhighlight> is recognized, too.
 +
  
 
== Conditional compilation ==
 
== Conditional compilation ==
Line 95: Line 103:
  
 
are allowed, too.
 
are allowed, too.
 +
  
 
== Compile-time behavior ==
 
== Compile-time behavior ==
Line 118: Line 127:
 
** <syntaxhighlight lang="pascal" inline>{$hints}</syntaxhighlight>
 
** <syntaxhighlight lang="pascal" inline>{$hints}</syntaxhighlight>
 
** <syntaxhighlight lang="pascal" inline>{$notes}</syntaxhighlight>
 
** <syntaxhighlight lang="pascal" inline>{$notes}</syntaxhighlight>
 +
  
 
== Ignored ==
 
== Ignored ==
Line 132: Line 142:
 
* <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 ==

Revision as of 14:12, 19 August 2020

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


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