ConditionalDefines

Michalis Kamburelis edited this page Jan 7, 2017 · 5 revisions
Clone this wiki locally

Overview

As you may know, Pascal allows for directives in the source code. These are comments that contain commands for the compiler introduced by the dollar sign.

To distinguish different compilers, libraries or development stages, conditional directives make it possible to make the compiler ignore part of the file.

An example:

unit SampleUnit;

{$ifdef WIN32}

uses Windows, WinProcs;
procedure WindowMove(H: TWindowHandle; DX, DY: Integer);

{$else}

procedure ClearConsole;
procedure PrintText(S: String);

{$endif}

{$define DEBUG}
{$undef OPTIMIZE}

The $ifdef part checks if a conditional directive called WIN32 is currently defined (that would be the case for Delphi or FPC/Win32). If this is true, all code until $else is compiled, and everything between $else and $endif is ignored. The contrary would apply if the directive is not defined, e.g. under FPC/Linux or Borland Pascal. These statements can also be nested. Using $define and $undef, a programmer can add and delete directives, in the above example DEBUG and OPTIMIZE.

As pasdoc loads Pascal files in a similar way a compiler does, it must be able to regard conditional directives. All $define and $undef parts are evaluated by pasdoc, modifying an internal list of directives as source code is parsed.

Different from a real compiler, pasdoc starts with an empty list of conditional directives. To get back to the above example, if you want to generate documentation for the WIN32 code part, you must explicitly tell pasdoc that you want WIN32 directive defined.

You can do so using the --define and --conditionals CommandLine options described below. It’s perfectly valid to specify multiple --define or --condtional options.

--define option

--define DIRECTIVES option (short form is -D DIRECTIVES) adds DIRECTIVES to the list of conditional directives that are present whenever parsing a unit is started. Each define should be separated from the others by a comma, as shown in the following example:

pasdoc --define DEBUG,FPC,WIN32

This defines three conditionals: DEBUG, FPC and WIN32.

--conditionals option

--conditionals CONDITIONALS-FILE option (short form is -d CONDITIONALS-FILE) adds the defines specified in a file CONDITIONALS-FILE to the list of conditional directives that are present whenever parsing a unit is started. The file must contain one conditional per line, without any comments.

Examples:

pasdoc --conditionals c:\sources\myconditionals.txt
pasdoc --conditionals /home/me/pascal/myconditionals.txt

where the myconditionals.txt file may contain, for example:

DEBUG
FPC
WIN32