Node:Compiler Directives, Next:Library Routines, Previous:OOP, Up:Programming

### Compiler Directives And The Preprocessor

GPC, like UCSD Pascal and BP, treats comments beginning with a `$` immediately following the opening `{` or `(*` as a compiler directive. As in Borland Pascal, `{$...}` and `(*$...*)` are equivalent. When a single character plus a `+` or `-` follows, this is also called a compiler switch. All of these directives are case-insensitive (but some of them have case-sensitive arguments). Directives are local and can be changed during one compilation (except include files etc. where this makes no sense).

In general, compiler directives are compiler-dependent. (E.g., only the include directive `{$I FileName}` is common to UCSD and BP.) Because of BP's popularity, GPC supports all of BP's compiler directives (and ignores those that are unnecessary on its platforms - these are those not listed below), but it knows a lot more directives.

Some BP directives are - of course not by chance - just an alternative notation for C preprocessor directives. But there are differences: BP's conditional definitions (`{$define Foo}`) go into another name space than the program's definitions. Therefore you can define conditionals and check them via `{$ifdef Foo}`, but the program will not see them as an identifier `Foo`, so macros do not exist in Borland Pascal.

GPC does support macros, but disables this feature when the `--no-macros` option or the dialect option `--borland-pascal` or `--delphi` is given, to mimic BP's behaviour. Therefore, the following program will react differently when compiled with GPC either without special options or with, e.g., the `--borland-pascal` option (and in the latter case, it behaves the same as when compiled with BP).

    program MacroDemo;

    const Foo = 'Borland Pascal';

    {$define Foo 'Default'}

    begin
      WriteLn (Foo)
    end.

Of course, you should not rely on such constructs in your programs. To test if the program is compiled with GPC, you can test the `__GPC__` conditional, and to test the dialect used in GPC, you can test the dialect, e.g., with `{$ifopt borland-pascal}`.

In general, almost every GPC specific command line option (see GPC Command Line Options) can be turned into a compiler directive (exceptions are those options that contain directory names, such as `--unit-path`, because they refer to the installation on a particular system, and therefore should be set system-wide, rather than in a source file):

    --foo       {$foo}
    --no-foo    {$no-foo}
    -Wbar       {$W bar}     { note the space after the W }
    -Wno-bar    {$W no-bar}

The following table lists some such examples as well as all those directives that do not correspond to command-line options or have syntactical alternatives (for convenience and/or BP compatibility).

    --[no-]short-circuit   $B+ $B- like in Borland Pascal:
                                   $B- means short-circuit Boolean
                                   operators; $B+ complete evaluation

    --[no-]io-checking     $I+ $I- like in Borland Pascal:
                                   enable/disable I/O checking

    --[no-]stack-checking  $S+ $S- like in Borland Pascal:
                                   enable/disable stack checking

    --[no-]typed-address   $T+ $T- like in Borland Pascal:
                                   make the result of the address
                                   operator and the Addr function a
                                   typed or untyped pointer

    -W[no-]warnings        $W+ $W- enable/disable warnings. Note: in
                                   --borland-pascal mode, the
                                   short version is disabled because
                                   $W+/$W- has a different meaning in
                                   Borland Pascal (which can safely be
                                   ignored in GPC), but the long version
                                   is still available.

    --[no-]extended-syntax $X+ $X- mostly like in Borland Pascal:
                                   enable/disable extended syntax
                                   (ignore function resuls, operator
                                   definitions, PChar, pointer
                                   arithmetic, ...)

    --borland-pascal               disable or warn about GPC features
    --extended-pascal              not supported by the standard or
    --pascal-sc                    dialect given, do not warn about its
    etc.                           ``dangerous'' features (especially BP).
                                   The dialect can be changed during one
                                   compilation via directives like,
                                   e.g., {$borland-pascal}.

    {$M Hello!}                    write message Hello! to
                                   standard error during compilation. In
                                   --borland-pascal mode, it is
                                   ignored it if only numbers follow
                                   (for compatibility to Borland
                                   Pascal's memory directive)

    {$define FOO}                  like in Borland Pascal:
    or                             define FOO (for conditional compilation)
    {$CIDefine FOO}                (case-insensitively)

    --cidefine=FOO                 the same on the command line

    {$CSDefine FOO}                define FOO case-sensitively

    -D FOO                         the same on the command line
    or                             Note: --define on the command
    --csdefine=FOO                 line is case-sensitive like in GCC,
    or                             but {$define} in the source code
    --define=FOO                   is case-insensitive like in BP

    {$define loop while True do}   define loop to be while True do
    or                             as a macro like in C. The name of the
    {$CIDefine loop ...}           macro is case-insensitive. Note:
                                   Macros are disabled in
                                   --borland-pascal mode because BP
                                   doesn't support macros.

    --cidefine="loop=..."          the same on the command line

    {$CSDefine loop ...}           define a case-sensitive macro

    --csdefine="loop=..."          the same on the command line
    or
    --define="loop=..."

    {$I FileName}                  like in Borland Pascal:
                                   include filename.pas
                                   (the name is converted to lower case)

    {$undef FOO}                   like in Borland Pascal: undefine FOO

    {$ifdef FOO}                   conditional compilation
      ...                          (like in Borland Pascal).
    {$else}                        Note: GPC predefines the symbol
      ...                          __GPC__ (with two leading
    {$endif}                       and trailing underscores).

    {$include "filename.pas"}      include (case-sensitive)

    {$include <filename.pas>}      the same, but don't search in the
                                   current directory

...and all the other C preprocessor directives.

You also can use the preprocessor directives in C style, e.g. `#include`, but this is deprecated because of possible confusion with Borland Pascal style `#42` character constants. Besides, in the Pascal style, e.g. `{$include "foo.bar"}`, there may be more than one directive in the same line.