Conditional compilation

From Free Pascal wiki
Jump to navigationJump to search

Deutsch (de) English (en) suomi (fi) français (fr) русский (ru)

What is conditional compilation?

Conditional compilation is compiling or omitting part of the sourcecode based on if a condition exists or not.
The features that make this possible in most compiled languages are called compile time directives. Compile time directives make it possible to compile a block of code based on the presence or absense of a condition at compile time. They can be used for a variety of purposes like:

  • Platform specific code isolation
  • Natural language selection
  • Licensing opensource and closed source parts
  • Isolating experimental code
  • Compiler version
  • Library version
  • etc, etc.

FreePascal supports four different styles of conditional compilation:

  • TurboPascal and early Delphi style directives
  • Mac Pascal style directives
  • Modern Freepascal and Delphi style directives
  • Compile time Macro's

Note the syntax here is not case sensitive as conforms to all Pascal syntax. We will use both lowercase and uppercase examples. We will show you the difference between the modes and how to efficiently use them.

TurboPascal style directives

The TurboPascal style directives are {$DEFINE}, {$IFDEF}, {$ENDIF}, {$IFNDEF}, {$IFOPT}, {$ELSE}, {$ELSEIF} and {$UNDEF}.
We will describe the directives in the context of the style. Some defines have an extended meaning in another style.
That means later on we may expand the meaning of certain directives like e.g. {$DEFINE} in the context of Macro's.

$define

The {$DEFINE} directive simply declares a symbol that we later can use for conditional compilation:

{$DEFINE name} // This defines a symbol called "name"
 Note you can also define a symbol from the command line or the IDE -dDEBUG for example is the command line equivalent of {$DEFINE DEBUG} in the sourcecode.
$undef

The {$UNDEF} directive undefines a previously defined symbol. Here is an example that the author uses in practice:

// Some older sourcecode is polluted with {$IFDEF FPC}'s that are no 
// longer necessary depending on the Delphi version to which it it should be compatible.
// I always test this by trying this on top of the program or unit:
{$IFDEF FPC}
  {$MODE DELPHI}
  {$UNDEF FPC}
  {$DEFINE VER150} 
  // code will now compile as if it was Delphi 7, provided the original Delphi sourcecode was indeed written for Delphi 7 and up.
{$ENDIF}
$ifdef and $endif

The simplest way to define a block of conditional code is like this:

unit cross;
{$IFDEF FPC}{$MODE DELPHI}{$ENDIF}

The above example is quite common for sourcecode that has to compile in both Delphi and Freepascal
If the compiler is Delphi then nothing is done, but if the compiler is FreePascal it will switch Freepascal to compile and use Delphi syntax mode.
This "FPC" conditional symbol is defined in system - there is a long list of those. The {$IFDEF} and {$ENDIF} block syntax is symmetrical: every {$IFDEF} has its own {$ENDIF}.
To help you recognize the corresponding blocks you can use e.g. indentation, but you can also use the comment feature:

{$IFDEF FPC this part is Freepascal specific}
// some Freepascal specific code
{$ENDIF Freepascal specific code}
warning
This comment feature is often not well understood. Some people - as on an older version of this wiki entry - assumed you could nest {$IFDEF}'s because the compiler seems to accept the syntax. But the former is false and the latter is true: Yes the compiler accepts the syntax below, but it is not a nested {$IFDEF} but a single {$IFDEF} condition and the rest is a comment!" The code below executes the writeln if and only if red is defined.
In this example {$ifdef blue} is a comment! Even if the {$define blue} is valid.
program completelywrong;
{$define blue}  
begin
{$ifdef red or $ifdef blue}// everything after red is a comment
  writeln ('red or blue'); // this code is never reached
{$endif red or blue}       // everything after $endif is a comment.
end.
$ifndef

This is the opposite of {$IFDEF} and code will be included of a certain condition is not defined.

A simple example is:

{$IFNDEF FPC this part not for Freepascal}
// some specific code that Freepascal should not compile
{$ENDIF code for other compilers than Freepascal}
$else and $elseif

{$ELSE} is used to compile code that does not belong to the codeblock that is defined by the corresponding {$IFDEF}. It is also valid in the context {$IFOPT}, {$IF} or {$IFC} that we will discuss later.

{$IFDEF red}  
   writeln('Red is defined');  
{$ELSE  no red}  
  {$IFDEF blue}  
   writeln('Blue is defined, but red is not defined');  
  {$ELSE no blue}  
  writeln('Neither red nor blue is defined'); 
  {$ENDIF blue}  
{$ENDIF red}

Such nested conditional written in the above syntax can get very messy and unreadable. Luckily we can simplify it a lot by using {$ELSEIF}. The code below is an expanded equivalent of the first example:

{$IFDEF red}  
  writeln('Red is defined');  
{$ELSEIF blue}  
  writeln('Blue is defined');  
{$ELSEIF green}  
  writeln('Green is defined');   
{$ELSE}
  writeln('Neither red, blue or green. Must be black...or something else...');
{$ENDIF}

As you can see this is a lot more readable.

$ifopt

With {$IFOPT} we can check if a certain compile option is defined. From the programmers manual:

The {$IFOPT switch} will compile the text that follows it if the switch switch is currently in the specified state. If it isn’t in the specified state, then compilation continues after the corresponding {$ELSE} 
or {$ENDIF} directive.
As an example:
 {$IFOPT M+}  
   Writeln(’Compiled with type information’);  
 {$ENDIF}
Will compile the Writeln statement only if generation of type information is on.
Remark:The {$IFOPT} directive accepts only short options, i.e. {$IFOPT TYPEINFO} will not be accepted.

A common use is this example to test if DEBUG mode is defined:

{$IFOPT D+}{$NOTE debug mode is active}{$ENDIF}

Such defines can also reside in configuration files like fpc.cfg which also contains a full explanation on how to use:

# ----------------------
# Defines (preprocessor)
# ----------------------
#
# nested #IFNDEF, #IFDEF, #ENDIF, #ELSE, #DEFINE, #UNDEF are allowed
#
# -d is the same as #DEFINE
# -u is the same as #UNDEF
#
#
# Some examples (for switches see below, and the -? helppages)
#
# Try compiling with the -dRELEASE or -dDEBUG on the commandline
#
# For a release compile with optimizes and strip debuginfo
#IFDEF RELEASE
  -O2
  -Xs
  #WRITE Compiling Release Version
#ENDIF

CODE AFTER THIS IS SUBJECT TO CHANGE OR REMOVAL PENDING EDITS

Mac Pascal style directives

Modern Delphi style directives

=== {$IF}{$IFEND}

LEGACY entries subject to edits and rewrites

If you have an application that needs several variations - say for two customers, or for two operating systems then compile-time defines are just what you need. A practical example is when coding across several platforms. 32 bit Windows only allows 4Gb files because of the maximum size of an integer and other operating systems do not have this limitation. So a filesize definition may be as follows:

var
  MyFilesize:
  {$ifdef Win32} 
    Cardinal 
  {$else}
    int64
  {$endif}

None of the above is case sensitive. {$ifdef}, {$else}, etc are known as symbols. When they are put together to perform logic the resultant code is known as a macro. For another practical example see: Code_Conversion_Guide#Useful_compiler_variables_.2F_defines_.2F_macros.

Another way of doing the same thing is to use IDE macros. IDE_Macros_in_paths_and_filenames.

All that remains is to know where the {$DEFINE WIN32} is placed in the code or the IDE.

There are three possible ways to do this.

Unit based {$DEFINE} and {$IFDEF} statements.

  //Insert $DEFINE symbol at an earlier point in the unit
  {$DEFINE Win32}
  var
  MyFilesize:
  {$ifdef Win32} 
    Cardinal 
  {$else}
    int64
  {$endif} 
  //Insert $UNDEF symbol
  {UNDEF $Win32}

Use the IDE

In the IDE go to Project | Project Options | Compiler Options | Other | Custom options and enter -dWin32 or Win32, depending on the version. In Lazarus 1.2.4 the -d is entered automatically.

In Custom options

-d is the same as #DEFINE
-u is the same as #UNDEF

These entries apply to the whole project.

Use an 'include' file

See the more detailed example below.

Symbols

Nested $IFNDEF, $IFDEF, $ENDIF, $ELSE, $DEFINE, $UNDEF are allowed. See http://wiki.lazarus.freepascal.org/local_compiler_directives#Conditional_compilation for a complete list.

Complex Examples

Unit based defines and Include (.inc) files must be done individually for each unit. A Custom Option entry applies to every unit.

Unit based {$DEFINE} and {$IFDEF} statements

Create a single form project as below. Comment and uncomment the two {$DEFINE) statements in turn and see what happens. If you add a second form (Form2) which opens when the first form (Form1) is clicked, similar statements will work independently of the {$DEFINE} statements in Form1.

var
  Form1: TForm1;

implementation

{$R *.lfm}
{$DEFINE RED}
//{$DEFINE BLUE}
{ TForm1 }

procedure TForm1.FormClick(Sender: TObject);
begin
  {$IFDEF RED} Form1.Color := clRed; {$ENDIF}
  {$IFDEF BLUE} Form1.Color := clBlue; {$ENDIF}
  // the following code, however does not do what you think
  {$IFDEF BLUE AND $IFDEF RED} Form1.Color := clYellow; {$ENDIF}
  {$IFNDEF RED AND $IFNDEF BLUE} Form1.Color := clAqua; {$ENDIF}
end;

Note that {$IFDEF} expects a single statement. The rest is comments, so in the above example on line 4/5 only {$IFDEF BLUE resp. {$IFNDEF RED is evaluated and the rest of those lines are comments. A better way to show that is:

program untitled;
begin
{$ifdef CPUARM this code is for arm only} // everything after CPUARM is a comment
  writeln ('arm');
{$endif arm specific code} // everything after endif is a comment.
end.

Be careful not to mis-interpret this feature.
The correct way to handle the above code is with the {$IF defined()} syntax, like so:

{$DEFINE RED}
//{$DEFINE BLUE}
{ TForm1 }

procedure TForm1.FormClick(Sender: TObject);
begin
  // the following code does do what you think it does
  {$IF Defined(BLUE) AND $Defined(RED)} Form1.Color := clYellow; {$IFEND}
  {$IF not (Defined(RED) AND Defined(BLUE))} Form1.Color := clAqua; {$IFEND}
end;

Include files

Include files add code into any .pas unit.

Create a file called unit1.inc (It could be called anything.inc.) that contains:

{$DEFINE RED}
//{$DEFINE BLUE}

Create another called unit1a.inc that contains:

  {$IFDEF RED} Form1.Color := clRed; {$ENDIF}
  {$IFDEF BLUE} Form1.Color := clBlue; {$ENDIF}
  {$IF Defined(BLUE) AND Defined(RED)} Form1.Color := clYellow; {$IFEND}
  {$IF NOT (Defined(RED) AND Defined(BLUE))} Form1.Color := clAqua; {$IFEND}

Add them to the project folder. When compiled, these lines will replace the $INCLUDE statements below. Both methods present the same code to the compiler. However, using the include file method makes it easier to handle more complex requirements.


var
  Form1: TForm1;

implementation

{$R *.lfm}
  {$INCLUDE unit1.inc}
{ TForm1 }

procedure TForm1.FormClick(Sender: TObject);
begin
  {$INCLUDE unit1a.inc}
end;

Now, we can extend to this:

var
  Form1: TForm1;

implementation

{$R *.lfm}
{$IFDEF ABC}  
  {$INCLUDE abc.inc}
{$ELSE}
  {$INCLUDE xyz.inc}
{$ENDIF}

{ TForm1 }

procedure TForm1.FormClick(Sender: TObject);
begin
 ... some code ...
{$IFDEF ABC}  
  {$INCLUDE abcCode.inc}
{$ELSE}
  {$INCLUDE xyzCode.inc}
{$ENDIF} 
... some more code ... 
end;

Project | Project Options | Compiler Options | Other | Custom options

Comment out, or remove, the {$DEFINE} symbols in your code and add the directives as below. In this case the directives will apply to all units. This defines FPC Symbols. For example, -dDEBUG -dVerbose will define the FPC symbols DEBUG and Verbose, so you can use {$IFDEF Debug}. See http://wiki.freepascal.org/IDE_Macros_in_paths_and_filenames.

Note the -d prefix.

-dRED
-dBLUE

A similar approach can be used when compiling with FPC instead of Lazarus: specify the -d... argument on the command line calling FPC (e.g. in a batch file).

From Lazarus 1.2, the new Options GUI offers a choice: either enter the directive with -d as before, or use the GUI. The GUI internally stores all entered directives and activates the ones you select. These are then displayed as in pre version 1.2 with the -d prefix.

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

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