Global directives

Global directives affect the whole of the compilation process of a single compilation unit (program, unit, library). They also have a command line counterpart, which is given for each of the directives. They must be specified before the first statement different from the program, unit or library clause in a source file, or they will have no effect.

Note that the configuration file created by the installer can change some of the compiler differences mentioned here.

$APPID : Specify application ID.

Used on the Palm OS only, it can be set to specify the application name, which can be viewed on the Palm only. This directive only makes sense in a program source file, not in a unit.

{$APPID MyApplication}

$APPNAME : Specify application name.

Used on the Palm OS only, it can be set to specify the application name which can be viewed on the Palm only. This directive only makes sense in a program source file, not in a unit.

{$APPNAME My Application, compiled using Free Pascal.}

$APPTYPE : Specify type of application.

This directive is currently only supported on the following targets: Win32, Mac, OS2 and AmigaOS. On other targets, the directive is ignored.

The {$APPTYPE XXX} accepts one argument which specifies what kind of application is compiled. It can have the following values:

CONSOLE

A console application. A terminal will be created and standard input, output and standard error file descriptors will be initialized. In Windows, a terminal window will be created. This is the default.

Note that on macOSsuch applications cannot take command line options, nor return a result code. They will run in a special terminal window, implemented as a SIOW application, see the MPW documentation for details.

On OS/2, these applications can run both full-screen and in a terminal window.

Linuxapplications are always console applications. The application itself can decide to close the standard files, though.

FS

Specifies a full-screen VIO application on OS/2. These applications use a special BIOS-like API to program the screen. OS/2 starts these application always in full screen.

GUI

Specifying the {$APPTYPE GUI} directive will mark the application as a graphical application; no console window will be opened when the application is run. No standard file descriptors will be initialized, using them (with e.g. writeln statements) will produce a run-time error. If run from the command line, the command prompt will be returned immediately after the application was started.

On OS/2and macOS, the GUI application type creates a GUI application, as on Windows. On OS/2, this is a real Presentation Manager application.

TOOL

This is a special directive for the macOS. It tells the compiler to create a tool application: It initializes Input, Output and StdErr files, it can take parameters and return a result code. It is implemented as an MPW tool which can only be run by MPW or ToolServer.

Care should be taken when compiling GUI applications; the Input and Output files are not available in a GUI application, and attempting to read from or write to them will result in a run-time error.

It is possible to determine the application type of a Windowsor application at runtime. The IsConsole constant, declared in the Win32 and Amiga system units as

Const
  IsConsole : Boolean;

contains True if the application is a console application, False if the application is a GUI application.

$CODEPAGE : Set the source codepage

This switch sets the codepage of the rest of the source file. The codepage is only taken into account when interpreting literal strings, the actual code must be in US-ASCII. The argument to this switch is the name of the code page to be used.

{$CODEPAGE UTF8}

The ’UTF-8’ codepage can be specified as ’UTF-8’ or ’UTF8’. The list of supported codepages is the list of codepages supported by the charset unit of the RTL.

$COPYRIGHT specify copyright info

This is intended for the NETWARE version of the compiler: it specifies the copyright information that can be viewed on a module for a Netware OS.

For example:

{$COPYRIGHT GNU copyleft. compiled using Free Pascal}

$D or $DEBUGINFO : Debugging symbols

When this switch is on, the compiler inserts GNU debugging information in the executable. The effect of this switch is the same as the command line switch -g.

By default, insertion of debugging information is off.

$DESCRIPTION : Application description

This switch is recognized for compatibility only, but is ignored completely by the compiler. At a later stage, this switch may be activated.

$E : Emulation of coprocessor

This directive controls the emulation of the coprocessor. There is no command line counterpart for this directive.

Intel 80x86 version

When this switch is enabled, all floating point instructions which are not supported by standard coprocessor emulators will issue a warning.

The compiler itself doesn’t do the emulation of the coprocessor.

To use coprocessor emulation under DOS(go32v2) you must use the emu387 unit, which contains correct initialization code for the emulator.

Under Linuxand most Unix’es, the kernel takes care of the coprocessor support, so this switch is not necessary on those platforms.

Motorola 680x0 version

When the switch is on, no floating point opcodes are emitted by the code generator. Instead, internal run-time library routines are called to do the necessary calculations. In this case all real types are mapped to the single IEEE floating point type.

$EXTENSION : Extension of generated binary.

This directive can appear in a program or library source file: it sets the extension for the generated binary/library. The initial dot (sometimes associated with the extension) may not be present.

Example:

{$EXTENSION 'cgi'}

will set the extension to ’cgi’.

$FRAMEWORKPATH : Specify framework path.

This option serves to specify the framework search path on Darwin, where the compiler looks for framework files. Used as

{$FRAMEWORKPATH XXX}

it will add XXX to the framework path. The value XXX can contain one or more paths, separated by semicolons or colons.

$G : Generate 80286 code

This option is recognized for Turbo Pascal compatibility, but is ignored, since the compiler works only on 32-bit and 64-bit processors.

$IMAGEBASE : Specify DLL image base location.

This option can be used to set the base location for a DLL on windows-based systems. The directive needs a memory location as an option (use $ to specify a hexadecimal value). It is the equivalent of the -WB command-line option.

The following sets the base location to 0x00400000

{$IMAGEBASE $00400000}

$INCLUDEPATH : Specify include path.

This option serves to specify the include path, where the compiler looks for include files. Used as

{$INCLUDEPATH XXX}

it will add XXX to the include path. The value XXX can contain one or more paths, separated by semicolons or colons.

For example:

{$INCLUDEPATH ../inc;../i386}

{$I strings.inc}

will add the directories ../inc and ../i386 to the include path of the compiler. The compiler will look for the file strings.inc in both these directories, and will include the first found file. This directive is equivalent to the -Fi command line switch.

Caution is in order when using this directive: If you distribute files, the locations of the files may not be the same as on your machine; moreover, the directory structure may be different. In general it would be fair to say that you should avoid using absolute paths. Instead, one should use relative paths only, as in the example above.

$L or $LOCALSYMBOLS : Local symbol information

This switch (not to be confused with the local {$L file} file linking directive) is recognized for Turbo Pascal compatibility, but is ignored. Generation of symbol information is controlled by the $D switch.

$LIBPREFIX : Specify library filename prefix.

The LIBPREFIX directive has a similar function as the {$EXTENSION } and {$LIBSUFFIX } compiler directives: It sets the prefix of the library. This is by default ’lib’ on unices, and empty on windows. The name is simply prepended to the filename.

Example:

library tl;
{$LIBPREFIX 'library'}

begin
end.

will result in a filename librarytl.so on linux, or librarytl.dll on windows.

$LIBRARYPATH : Specify library path.

This option serves to specify the library path, where the linker looks for static or dynamic libraries. {$LIBRARYPATH XXX} will add XXX to the library path. XXX can contain one or more paths, separated by semicolons or colons.

For example:

{$LIBRARYPATH /usr/X11/lib;/usr/local/lib}

{$LINKLIB X11}

will add the directories /usr/X11/lib and /usr/local/lib to the linker library path. The linker will look for the library libX11.so in both these directories, and use the first found file. This directive is equivalent to the -Fl command line switch.

Caution is in order when using this directive: If you distribute files, the locations of the libraries may not be the same as on your machine; moreover, the directory structure may be different. In general it would be fair to say that you should avoid using this directive. If you are not sure, it is better practice to use makefiles and makefile variables.

$LIBSUFFIX : Set the library suffix

Similar to the {$EXTENSION } and {$LIBPREFIX } directives, the $LIBSUFFIX directive sets the suffix of the library. This is usually used for version numbers, which are simply added to the output filename, followed by the extension.

Example:

library tl;
{$LIBSUFFIX '-1.2.3'}

begin
end.

will result in a filename libtl-1.2.3.so on linux, or libtl-1.2.3.dll on windows.

$MAXSTACKSIZE : Set maximum stack size

The {$MAXSTACKSIZE} sets the maximum stack size for an executable on Windows-based systems. It needs an argument, the size (in bytes) of the stack. The maximum value is $7FFFFFFF, the minimum value is 2048 or the value of $MINSTACKSIZE if it was specified.

The following example sets the maximum stack size to$FFFFFF bytes:

{$MAXSTACKSIZE $FFFFFF}

$M or $MEMORY : Memory sizes

This switch can be used to set the heap and stacksize. Its format is as follows:

{$M StackSize,HeapSize}

where StackSize and HeapSize should be two integer values, greater than 1024. The first number sets the size of the stack, and the second the size of the heap. The stack size setting is ignored on Unix platforms unless stack checking is enabled: in that case the stack checking code will use the size set here as maximum stack size.

On those systems, in addition to the stack size set here, the operating system or the run-time environment may have set other (possibly more strict) limits on stack size using the OS’es ulimit system calls.

The two numbers can be set on the command line using the -Ch and -Cs switches.

Note that the abbreviation of this directive is the same as the local directive $M for enabling Run-time Type information (section Compiler directives).

$MINSTACKSIZE : Set minimum stack size

The {$MINSTACKSIZE} sets the minimum stack size for an executable on Windows-based systems. It needs an argument, the size (in bytes) of the stack. This must be a number larger than 1024.

The following example sets the minimum stack size to 2048 bytes:

{$MINSTACKSIZE 2048}

$MODE : Set compiler compatibility mode

The {$MODE} sets the compatibility mode of the compiler. This is equivalent to setting one of the command line options -So, -Sd, -Sp or -S2. it has the following arguments:

Default

Default mode. This reverts back to the mode that was set on the command line.

Delphi

Delphi compatibility mode. All object-pascal extensions are enabled. This is the same as the command line option -Sd. Note that this also implies {$H ON} (i.e., in Delphi mode, ansistrings are the default).

DelphiUnicode

Delphi compatibility mode. All object-pascal extensions are enabled, and additionally the String keyword refers to a unicode string.

ExtendedPascal

Extended pascal mode. Only available in 3.2 and higher.

TP

Turbo pascal compatibility mode. Object pascal extensions are disabled, except ansistrings, which remain valid. This is the same as the command line option -So.

FPC

FPC mode. This is the default, if no command line switch is supplied.

OBJFPC

Object pascal mode. This is the same as the -S2 command line option.

MACPAS

MACPAS mode. In this mode, the compiler tries to be more compatible to commonly used pascal dialects on the macOS, such as Think Pascal, Metrowerks Pascal, MPW Pascal.

ISO

Standard Pascal, ISO 7185 mode. In this mode, the compiler complies with the requirements of level 0 of ISO/IEC 7185.

For an exact description of each of these modes, see appendix Compiler modes, on page .

$MODESWITCH : Select mode features

As of FPC 2.3.1, the {$MODESWITCH} directive can be used to select some of the features that a {$MODE } directive would select.

It can be used to enable language features that would otherwise not be available in the current mode. For example, you might be programming in TP mode, but want to use the Out parameters, which are only available in Delphi mode.

The {$MODESWITCH } directive enables or disables individual mode features without changing the current compiler mode.

This switch is a global switch, and can be used wherever the {$MODE} switch can be used.

The syntax is as follows:

{$MODESWITCH XXX}
{$MODESWITCH XXX+}
{$MODESWITCH XXX-}

The first two will switch on feature XXX, the last one will switch it off.

The feature XXX can be one of the following:

ADVANCEDRECORDS

Allow the use of advanced records (i.e. records with methods).

ARRAYOPERATORS

Use Delphi compatible array operators instead of custom ones ("+").

ALLOWINLINE

Allow inline procedures.

ANSISTRINGS

Allow use of ansistrings.

AUTODEREF

Automatic (silent) dereferencing of typed pointers.

CBLOCKS

C style blocks.

CLASSICPROCVARS

Use classical procedural variables.

CLASS

Use object pascal classes.

CVAR

Allow the use of the CVAR keyword.

DEFAULTPARAMETERS

Allow use of default parameter values.

DUPLICATELOCALS

Allow local variables in class methods to have the same names as properties of the class.

EXCEPTIONS

Allow the use of exceptions.

FINALFIELDS

Allows declaring fields as "final", which means they must be initialised in the (class) constructor and are constant from then on (same as final fields in Java).

HINTDIRECTIVE

Support the hint directives (deprecated, platform etc.)

INITFINAL

Allow use of Initialization and Finalization

ISOIO

Input/output as required by ISO pascal.

ISOMOD

Mod operation as required by ISO pascal.

ISOPROGRAMPARAS

Program parameters as required by ISO pascal.

ISOUNARYMINUS

Unary minus as required by ISO pascal.

MACPROCVARS

Use mac-style procedural variables.

NESTEDCOMMENTS

Allow use of nested comments.

NESTEDPROCVARS

Allow assigning local procedures to procedural variables.

NONLOCALGOTO

Allow jumping to a location outside the current scope.

OBJECTIVEC1

Allow interfacing with Objective C version 1.

OBJECTIVEC2

Allow interfacing with Objective C version 21.

OBJPAS

Automatically include the ObjPas unit.

OUT

Allow use of the out parameter type.

PCHARTOSTRING

Allow automatic conversion of null-terminated strings to strings,

POINTERTOPROCVAR

Allow silent conversion of pointers to procedural variables.

PROPERTIES

Allow use of properties.

REPEATFORWARD

Implementation and Forward declaration must match completely.

RESULT

Enable the Result identifier for function results.

SYSTEMCODEPAGE

Set the codepage to the code page of the platform on which the compiler is running. This is automatically enabled if you selected delphiunicode mode: {$mode delphiunicode}.

TYPEHELPERS

Allow the use of type helpers.

UNICODESTRINGS

String is by default unicode string.

Hence, the following:

{$MODE TP}
{$MODESWITCH OUT}

Will switch on the support for the out parameter type in TP mode. It is equivalent to

{$MODE TP}
{$MODESWITCH OUT+}

$N : Numeric processing

This switch is recognized for Turbo Pascal compatibility, but is otherwise ignored, since the compiler always uses the coprocessor for floating point mathematics.

$O : Level 2 Optimizations

In earlier versions of FPC, this switch was recognized for Turbo Pascal compatibility, but was otherwise ignored: The concept of overlay code is not needed in 32-bit or 64-bit programs.

In newer versions of FPC (certainly as of 2.0.0), this switch became a Delphi compatible switch: it has the same meaning as the {$OPTIMIZATION ON/OFF} switch, switching on or off level 2 optimizations.

See section Compiler directives on page for more explanations and more detailed optimization settings.

$OBJECTPATH : Specify object path.

This option serves to specify the object path, where the compiler looks for object files. {$OBJECTPATH XXX} will add XXX to the object path. XXX can contain one or more paths, separated by semicolons or colons.

For example:

{$OBJECTPATH ../inc;../i386}

{$L strings.o}

will add the directories ../inc and ../i386 to the object path of the compiler. The compiler will look for the file strings.o in both these directories, and will link the first found file in the program. This directive is equivalent to the -Fo command line switch.

Caution is in order when using this directive: If you distribute files, the locations of the files may not be the same as on your machine; moreover, the directory structure may be different. In general it would be fair to say that you should avoid using absolute paths, instead use relative paths, as in the example above. Only use this directive if you are certain of the locations where the files reside. If you are not sure, it is better practice to use makefiles and makefile variables.

$P or $OPENSTRINGS : Use open strings

If this switch is on, all function or procedure parameters of type string are considered to be open string parameters; this parameter only has effect for short strings, not for ansistrings.

When using openstrings, the declared type of the string can be different from the type of string that is actually passed, even for strings that are passed by reference. The declared size of the string passed can be examined with the High(P) call.

By default, the use of openstrings is off.

$PASCALMAINNAME : Set entry point name

The {$PASCALMAINNAME NNN} directive sets the assembler symbol name of the program or library entry point to NNN. This directive is the equivalent of the -XM command line switch.

Under normal circumstances, it should not be necessary to use this switch.

$PIC : Generate PIC code or not

The {$PIC } directive takes a boolean argument and tells the compiler whether it should generate PIC (Position Independent Code) or not. This directive is the equivalent of the -Cg command line switch.

This directive is only useful on Unix platforms: Units should be compiled using PIC code if they are supposed to be in a library. For programs, using PIC code is not needed, but it doesn’t hurt either (although PIC code is slower).

The following

{$PIC ON}
unit MyUnit;

tells the compiler to compile myunit using PIC code.

$POINTERMATH : Allow use of pointer math

By default, pointer arithmetic is enabled in FPC/OBJFPC modes and disabled in DELPHI mode. The directive $POINTERMATH ON/OFF can be used to toggle pointer arithmetic support. Types declared while $POINTERMATH ON is in effect also support pointer arithmetic.

This boolean directive enables or disables the use of pointer arithmetic in expressions involving pointers. When enabled, the difference of 2 pointers is a valid integer expression, and an integer value can be added to a pointer value.

The following

{$POINTERMATH OFF}
unit MyUnit;

tells the compiler to give an error whenever pointer math appears in an expression.

$PROFILE : Profiling

This directive turns the generation of profiling code on or off. It is equivalent to the -gp command line option. Default is OFF. This directive only makes sense in a program source file, not in a unit.

$SCREENNAME : Specify screen name

This directive can be used for the Novell netware targets to specify the screen name. The argument is the screen name to be used.

{$SCREENNAME My Nice Screen}

Will set the screenname of the current application to ’My Nice Screen’.

$SETPEFLAGS : Specify PE Executable flags

The $SETPEFLAGS executable sets the PE flags on Windows. These flags are written to the binary PE header file. It expects a numerical constant as an argument, this constant will be written to the header block.

Under normal circumstances, the compiler itself will determine the values of the PE flags to write to the binary file, but this directive can be used to override the compiler’s behavior.

$SMARTLINK : Use smartlinking

A unit that is compiled in the {$SMARTLINK ON} state will be compiled in such a way that it can be used for smartlinking. This means that the unit is chopped in logical pieces: each procedure is put in its own object file, and all object files are put together in a big archive. When using such a unit, only the pieces of code that you really need or call will be linked in your program, thus reducing the size of your executable substantially.

Beware: using smartlinked units slows down the compilation process, because a separate object file must be created for each procedure. If you have units with many functions and procedures, this can be a time consuming process, even more so if you use an external assembler (the assembler is called to assemble each procedure or function code block separately).

The smartlinking directive should be specified before the unit declaration part:

{$SMARTLINK ON}

Unit MyUnit;

Interface
 ...

This directive is equivalent to the -CX command line switch.

To have a smartlinked binary, 2 command-line options are needed:

-CX

create object files that can be smartlinked (or use the directive above)

-XX

: perform smartlinking during the linking phase. This requires that the units were compiled with -CX

It should be noted that on some targets, -CX is a no-op and -XX works even when -CX was not specified (e.g. Linux), or both -CX and -XX are no-ops and smart linking is always enabled (as on Windows).

$SYSCALL : Select system calling convention on Amiga/MorphOS

This directive sets the system calling convention to use on a MorphOS or Amiga system. The directive needs an argument, which should be one of the following:

LEGACY

SYSV

SYSVBASE

BASESYSV

R12BASE

The directive will generate a warning if used on another system.

$THREADNAME : Set thread name in Netware

This directive can be set to specify the thread name when compiling for Netware.

$UNITPATH : Specify unit path.

This option serves to specify the unit path, where the compiler looks for unit files. {$UNITPATH XXX} will add XXX to the unit path. XXX can contain one or more paths, separated by semicolons or colons. No quotation marks must be present, even if there are spaces in the paths.

For example:

{$UNITPATH ../units;../i386/units}

Uses strings;

will add the directories ../units and ../i386/units to the unit path of the compiler: these directories are relative to the unit file in which the directive appears. The compiler will look for the file strings.ppu in both these directories, and will link the first found file in the program.

Note that this switch does not propagate to other units, i.e. its scope is limited to the current unit (this is in line with the fact that the paths are relative to the current unit). To add search paths for "all units", need to use the command line switch -Fu.

The uses clause construct uses a in 'sub/a.pp' is relative to the current working directory of the compiler. By adding a directive to your program:

{$UNITPATH sub}

uses a in 'sub/a.pp';

you will make sure the compiler will always find the sources.

Caution is in order when using this directive: If you distribute files, the locations of the files may not be the same as on your machine; moreover, the directory structure may be different. In general it would be fair to say that you should avoid using absolute paths, instead use relative paths, as in the example above. Only use this directive if you are certain of the locations where the files reside. If you are not sure, it is better practice to use makefiles and makefile variables.

$VARPROPSETTER : Enable use of var/out/constref parameters for property setters.

This boolean directive is meant to import COM interfaces. Sometimes COM interfaces have property setters which accept arguments that are not by value, but by reference. These setters are normally forbidden. This flag enables the use of property setters with var, constref, out arguments. By default it is OFF. Note that it affects all properties that write to a setter procedure, including those of objects and extended records.

The following example only compiles in the ON state:

{$VARPROPSETTER ON}
Type
  TMyInterface = Interface
    Procedure SetP(Var AValue : Integer);
    Function GetP : Integer;
    Property MyP : Integer Read GetP Write SetP;
  end;

In the OFF state, the following error will be generated:

testvp.pp(7,48) Error: Illegal symbol for property access

$VERSION : Specify DLL version.

On Windows, this can be used to specify a version number for a library. This version number will be used when the library is installed, and can be viewed in the Windows Explorer by opening the property sheet of the DLL and looking on the tab ’Version’. The version number contains 1, 2 or 3 integers, separated by a dot:

{$VERSION 1}

Or:

{$VERSION 1.1}

And even:

{$VERSION 1.1.1}

This cannot yet be used for executables on Windows, but may be activated in the future.

$WEAKPACKAGEUNIT : ignored

This switch is parsed for Delphi compatibility but is otherwise ignored. The compiler will issue a warning when it is encountered.

$X or $EXTENDEDSYNTAX : Extended syntax

Extended syntax allows you to drop the result of a function and perform pointer arithmetic. This means that you can use a function call as if it were a procedure. By default this feature is on. You can switch it off using the {$X-} or {$EXTENDEDSYNTAX OFF}directive.

The following, for instance, will not compile:

function Func (var Arg : sometype) : longint;
begin
...          { declaration of Func }
end;

...

{$X-}
Func (A);

The reason this construct is supported is that you may wish to call a function for certain side-effects it has, but you don’t need the function result. In this case you don’t need to assign the function result, saving you an extra variable.

Similarly, the pointer math wil be disabled:

{$x-}
var
  x,p : pointer;

begin
  p:=pbyte(x)+1;
  p:=pdouble(x)+4;
end;

will result in an error for both lines:

ex.pp(13,14) Error: Operation "+" not supported for types "PByte" and "ShortInt"                                                            
ex.pp(15,16) Error: Operation "+" not supported for types "PDouble" and "ShortInt"

By default, extended syntax is assumed.

$Y or $REFERENCEINFO : Insert Browser information

This switch controls the generation of browser information. It is recognized for compatibility with Turbo Pascal and Delphi only, as Browser information generation is not yet fully supported.