Local directives have no command-line counterpart. They influence the compiler's behaviour from the moment they're encountered until the moment another switch annihilates their behaviour, or the end of the unit or program is reached.
This switch is recognized for Turbo Pascal Compatibility, but is not yet implemented. The alignment of data will be different in any case, since Free Pascal is a 32-bit compiler.
The {$ASMMODE XXX directive informs the compiler what kind of assembler it can expect in an asm block. The XXX should be replaced by one of the following:
This switch is understood by the Free Pascal compiler, but is ignored. The compiler always uses shortcut evaluation, i.e. the evaluation of a boolean expression is stopped once the result of the total exression is known with certainty.
So, in the following example, the function Bofu, which has a boolean result, will never get called.
If False and Bofu then ...
This switch is recognised for Delphi compatibility only. Assertions are not yet supported by the compiler, but will be implemented in the future.
The directive
{$DEFINE name}
defines the symbol name. This symbol remains defined until the end of
the current module, or until a $UNDEF name directive is encountered.
If name is already defined, this has no effect. Name is case insensitive.
The {$ELSE } switches between compiling and ignoting the source text delimited by the preceding {$IFxxx} and following {$ENDIF}. Any text after the ELSE keyword but before the brace is ignored:
{$ELSE some ignored text}
is the same as
{$ELSE}
This is useful for indication what switch is meant.
The {$ENDIF} directive ends the conditional compilation initiated by the last {$IFxxx} directive. Any text after the ENDIF keyword but before the closing brace is ignored:
{$ENDIF some ignored text}
is the same as
{$ENDIF}
This is useful for indication what switch is meant to be ended.
The following code
{$ERROR This code is erroneous !}
will display an error message when the compiler encounters it,
and increase the error count of the compiler.
The compiler will continue to compile, but no code will be emitted.
This directive is recognized for compatibility with Turbo Pascal. Under the 32-bit programming model, the concept of near and far calls have no meaning, hence the directive is ignored. A warning is printed to the screen, telling you so.
As an example, : the following piece of code :
{$F+}
Procedure TestProc;
begin
Writeln ('Hello From TestProc');
end;
begin
testProc
end.
Generates the following compiler output:
malpertuus: >pp -vw testf Compiler: ppc386 Units are searched in: /home/michael;/usr/bin/;/usr/lib/ppc/0.9.1/linuxunits Target OS: Linux Compiling testf.pp testf.pp(1) Warning: illegal compiler switch 7739 kB free Calling assembler... Assembled... Calling linker... 12 lines compiled, 1.00000000000000E+0000You can see that the verbosity level was set to display warnings.
If you declare a function as Far (this has the same effect as setting it between {$F+}...{$F-} directives), the compiler also generates a warning :
testf.pp(3) Warning: FAR ignored
The same story is true for procedures declared as Near. The warning displayed in that case is:
testf.pp(3) Warning: NEAR ignored
The following code
{$FATAL This code is erroneous !}
will display an error message when the compiler encounters it, and trigger
and increase the error count of the compiler.
The compiler will immediatly stop the compilation process.
If {$LONGSTRINGS ON} is specified, the keyword String (no length specifier) will be treated as AnsiString, and the compiler will treat the corresponding varible as an ansistring, and will generate corresponding code.
By default, the use of ansistrings is off, corresponding to {$H-}.
This feature is still experimental, and should be used with caution for the time being.
If the generation of hints is turned on, through the -vh command-line option or the {$HINTS ON} directive, then
{$Hint This code should be optimized }
will display a hint message when the compiler encounters it.
{$HINTS ON} switches the generation of hints on. {$HINTS OFF} switches the generation of hints off. Contrary to the command-line option -vh this is a local switch, this is useful for checking parts of your code.
The directive {$IF expr} will continue the compilation if the boolean expression expr evaluates to true. If the compilation evaluates to false, then the source are skipped to the first {$ELSE} or {$ENDIF} directive.
The compiler must be able to evaluate the expression at compile time. This means that you cannot use variables or constants that are defined in the source. Macros and symbols may be used, however.
More information on this can be found in the section about conditionals.
The {$IFDEF name} will skip the compilation of the text that follows it if the symbol name is not defined. If it is defined, then compilation continues as if the directive wasn't there.
The {$IFNDEF name} will skip the compilation of the text that follows it if the symbol name is defined. If it is not defined, then compilation continues as if the directive wasn't there.
The {$IFOPT switch} will skip the compilation of the text that follows it if the switch switch is currently not in the specified state. If it is in the specified state, then compilation continues as if the directive wasn't there.
As an example:
{$IFOPT M+}
Writeln ('Compiled with type information');
{$ENDIF}
Will compile the writeln statement if generation of type information is on.
If the generation of info is turned on, through the -vi command-line option, then
{$INFO This was coded on a rainy day by Bugs Bunny }
will display an info message when the compiler encounters it.
The {$I-} or {$IOCHECK OFF} directive tells the compiler not to generate input/output checking code in your program. By default, the compiler does not generate this code, you must switch it on using the -Ci command-lne switch.
If you compile using the -Ci compiler switch, the Free Pascal compiler inserts input/output checking code after every input/output call in your program. If an error occurred during input or output, then a run-time error will be generated. Use this switch if you wish to avoid this behavior. If you still want to check if something went wrong, you can use the IOResult function to see if everything went without problems.
Conversely, {$I+} will turn error-checking back on, until another directive is encountered which turns it off again.
The most common use for this switch is to check if the opening of a file went without problems, as in the following piece of code:
...
assign (f,'file.txt');
{$I-}
rewrite (f);
{$I+}
if IOResult<>0 then
begin
Writeln ('Error opening file : "file.txt"');
exit
end;
...
The {$I filename} or {$INCLUDE filename} directive tells the compiler to read further statements from the file filename. The statements read there will be inserted as if they occurred in the current file.
The compiler will append the .pp extension to the file if you don't specify an extension yourself. Do not put the filename between quotes, as they will be regarded as part of the file's name.
You can nest included files, but not infinitely deep. The number of files is restricted to the number of file descriptors available to the Free Pascal compiler.
Contrary to Turbo Pascal, include files can cross blocks. I.e. you can start a block in one file (with a Begin keyword) and end it in another (with a End keyword). The smallest entity in an include file must be a token, i.e. an identifier, keyword or operator.
The compiler will look for the file to include in the following places:
In this form:
{$INCLUDE %xxx%}
where xxx is one of TIME, DATE, FPCVERSION or
FPCTARGET, will generate a macro with the value of these things.
If xxx is none of the above, then it is assumed to be the value of
an environment variable. It's value will be fetched, and inserted in the coe
as if it were a srtring.
For example, the following program
Program InfoDemo;
Const User = {$I %USER%};
begin
Write ('This program was comilped at ',{$I %TIME%});
Writeln (' on ',{$I %DATE%});
Writeln ('By ',User);
Writeln ('Compiler version : ',{$I %FPCVERSION%});
Writeln ('Target CPU : ',{$I %FPCTARGET%});
end.
Creates the following output :
This program was comilped at 17:40:18 on 1998/09/09 By michael Compiler version : 0.99.7 Target CPU : i386
This switch selects the assembler reader. {$I386_XXX} has the same effect as {$ASMMODE XXX}, section (1.1)
The {$L filename} or {$LINK filename} directive tells the compiler that the file filename should be linked to your program.
the compiler will look for this file in the following way:
On LINUX systems, the name is case sensitive, and must be typed exactly as it appears on your system.
Remark : Take care that the object file you're linking is in a format the linker understands. Which format this is, depends on the platform you're on. Typing ld on the command line gives a list of formats ld knows about.
You can pass other files and options to the linker using the -k command-line option. You can specify more than one of these options, and they will be passed to the linker, in the order that you specified them on the command line, just before the names of the object files that must be linked.
The {$LINKLIB name} will link to a library name. This has the effect of passing -lname to the linker.
As an example, consider the following unit:
unit getlen;
interface
{$LINKLIB c}
function strlen (P : pchar) : longint;cdecl;
implementation
function strlen (P : pchar) : longint;cdecl;external;
end.
If one would issue the command the command
ppc386 foo.ppwhere foo.pp has the above unit in its uses clause, then the compiler would link your program to the c library, by passing the linker the -lc option.
The same effect could be obtained by removing the linklib directive in the above unit, and specify -k-lc on the command-line:
ppc386 -k-lc foo.pp
This switch is recognized for Delphi compatibility only since the generation of type information isn't fully implemented yet.
If the generation of info is turned on, through the -vi command-line option, then
{$MESSAGE This was coded on a rainy day by Bugs Bunny }
will display an info message when the compiler encounters it. The effect is
the same as the {$INFO} directive.
As of version 0.9.8, Free Pascal supports optimization for the MMX Intel processor (see also 7). This optimizes certain code parts for the MMX Intel processor, thus greatly improving speed. The speed is noticed mostly when moving large amounts of data. Things that change are
When MMX support is on, you aren't allowed to do floating point arithmetic. You are allowed to move floating point data, but no arithmetic can be done. If you wish to do floating point math anyway, you must first switch of MMX support and clear the FPU using the emms function of the cpu unit.
The following example will make this more clear:
Program MMXDemo;
uses cpu;
var
d1 : double;
a : array[0..10000] of double;
i : longint;
begin
d1:=1.0;
{$mmx+}
{ floating point data is used, but we do _no_ arithmetic }
for i:=0 to 10000 do
a[i]:=d2; { this is done with 64 bit moves }
{$mmx-}
emms; { clear fpu }
{ now we can do floating point arithmetic }
....
end.
See, however, the chapter on MMX (7) for more information
on this topic.
If the generation of notes is turned on, through the -vn command-line option or the {$NOTES ON} directive, then
{$NOTE Ask Santa Claus to look at this code }
will display a note message when the compiler encounters it.
{$NOTES ON} switches the generation of notes on. {$NOTES OFF} switches the generation of notes off. Contrary to the command-line option -vn this is a local switch, this is useful for checking parts of your code.
{$OUTPUT_FORMAT format} has the same functionality as the -A command-line option : It tells the compiler what kind of object file must be generated. You can specify this switch only befor the Program or Unit clause in your source file. The different kinds of formats are shown in table (1.1).
| Switch value | Generated format |
| att | AT&T assembler file. |
| o | Unix object file. |
| obj | OMF file. |
| wasm | assembler for the Watcom assembler. |
This switch is provided for compatibility only, as open strings aren't implemented yet.
This directive tells the compiler the minimum number of bytes it should use when storing enumerated types. It is of the following form:
{$PACKENUM xxx}
{$MINENUMSIZE xxx}
Where the form with $MINENUMSIZE is for Delphi compatibility.
varxxx can be one of 1,2 or 4, or NORMAL or
DEFAULT, corresponding to the default value of 4.
As an alternative form one can use {$Z1}, {$Z2} {$Z4}. Contrary to Delphi, the default size is 4 bytes ({$Z4}).
So the follwoing code
{$PACKENUM 1}
Type
Days = (monday, tuesday, wednesday, thursday, friday,
saturday, sunday);
will use 1 byte to store a variable of type Days, wheras it nomally
would use 4 bytes. The above code is equivalent to
{$Z1}
Type
Days = (monday, tuesday, wednesday, thursday, friday,
saturday, sunday);
Remark: Sets are always put in 32 bit or 32 bytes, this cannot be changed
This directive controls the byte alignment of the elements in a record, object or class type definition.
It is of the following form:
{$PACKRECORDS xx}
Where xxx is one of 1,2,4,16 or NORMAL or DEFAULT. This means that the elements of a record will be aligned on 1,2, 4 or 16 byte boundaries. Thus, the size of a record will always be a multiple of the alignment size. The default alignment (which can be selected with DEFAULT) is 2, contrary to Turbo Pascal, where it is 1.
More information of this can be found in the reference guide, in the section about record types.
Remark: Sets are always put in 32 bit or 32 bytes, this cannot be changed
The {$Q+} or {$OVERFLOWCHECKS ON} directive turns on integer overflow checking. This means that the compiler inserts code to check for overflow when doing computations with integers. When an overflow occurs, the run-time library will print a message Overflow at xxx, and exit the program with exit code 215.
Remark: Overflow checking behaviour is not the same as in Turbo Pascal since all arithmetic operations are done via 32-bit values. Furthermore, the Inc() and Dec() standard system procedures are checked for overflow in Free Pascal, while in Turbo Pascal they are not.
Using the {$Q-} switch switches off the overflow checking code generation.
The generation of overflow checking code can also be controlled using the -Co command line compiler option (see Users' guide\).
By default, the computer doesn't generate code to check the ranges of array indices, enumeration types, subrange types, etc. Specifying the {$R+} switch tells the computer to generate code to check these indices. If, at run-time, an index or enumeration type is specified that is out of the declared range of the compiler, then a run-time error is generated, and the program exits with exit code 201.
The {$RANGECHECKS OFF} switch tells the compiler not to generate range checking code. This may result in faulty program behaviour, but no run-time errors will be generated.
Remark: Range checking for sets and enumerations are not yet fully implemented.
This works only on the intel compiler, and MMX support must be on ({$MMX +}) for this to have any effect. See the section on saturation support (section (7.2)) for more information on the effect of this directive.
The following code
{$STOP This code is erroneous !}
will display an error message when the compiler encounters it.
The compiler will immediatly stop the compilation process.
It has the same effect as the {$FATAL} directive.
In the {$T+} or {$TYPEDADDRESS ON} state the @ operator, when applied to a variable, returns a result of type ^T, if the type of the variable is T. In the {$T-} state, the result is always an untyped pointer, which is assignment compatible with all other pointer types.
The directive
{$UNDEF name}
un-defines the symbol name if it was previously defined.
Name is case insensitive.
When in the + or ON state, the compiler checks that strings passed as parameters are of the same, identical, string type as the declared parameters of the procedure.
If the compiler encaounters a
{$WAIT }
directive, it will resume compiling only after the user has pressed the
enter key. If the generation of info messages is turned on, then the compiler
will display the follwing message:
Press <return> to continuebefore waiting for a keypress. Careful ! this may interfere with automatic compilation processes. It should be used for debuggig purposes only.
If the generation of warnings is turned on, through the -vw command-line option or the {$WARNINGS ON} directive, then
{$WARNING This is dubious code }
will display a warning message when the compiler encounters it.
{$WARNINGS ON} switches the generation of warnings on. {$WARNINGS OFF} switches the generation of warnings off. Contrary to the command-line option -vw this is a local switch, this is useful for checking parts of your code.
Extended syntax allows you to drop the result of a function. This means that you can use a function call as if it were a procedure. Standard 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.
The command-line compiler switch -Sa1 has the same effect as the {$X+} directive.