
Free  Pascal  :

Users'  manual

==============================================================================================================================

                                                      Users' manual for Free Pascal, version 2.0.4

                                                                                         Document version 2.0

                                                                                                        August 2006


Micha"el Van Canneyt
Florian Klmpfl
______________________________________________________________________________________________________________________________



Contents
1    Introduction                                                                                                           7

     1.1    About this document            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .     7

     1.2    About the compiler          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .     7

     1.3    Getting more information.             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .     8


2    Installing the compiler                                                                                                9

     2.1    Before Installation :  Requirements               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.     9

            2.1.1     Hardware requirements              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .     9

            2.1.2     Software requirements            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .     9

     2.2    Installing the compiler.         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    10

            2.2.1     Installing under DOS, Windows or OS/2                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 10

            2.2.2     Installing under Linux           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    12

     2.3    Optional configuration steps             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    13

     2.4    Before compiling          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .    14

     2.5    Testing the compiler           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    14


3    Compiler usage                                                                                                       15

     3.1    File searching       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .    15

            3.1.1     Command line files          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    15

            3.1.2     Unit files      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .    15

            3.1.3     Include files     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    18

            3.1.4     Object files      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    18

            3.1.5     Configuration file        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    18

            3.1.6     About long filenames           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    19

     3.2    Compiling a program            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    19

     3.3    Compiling a unit          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .    19

     3.4    Units, libraries and smartlinking               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    20

     3.5    Reducing the size of your program                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    20


4    Compiling problems                                                                                                   21

     4.1    General problems          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .    21

     4.2    Problems you may encounter under DOS                        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   21



                                                              1

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
5    Compiler configuration                                                                                               22

    5.1    Using the command-line options                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    22

           5.1.1     General options        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    22

           5.1.2     Options for getting feedback               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    23

           5.1.3     Options concerning files and directories                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 23

           5.1.4     Options controlling the kind of output.                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 24

           5.1.5     Options concerning the sources (language options)                       .  .  .  .  .  .  .  .  .  .  .    28

    5.2    Using the configuration file             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    29

           5.2.1     #IFDEF          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    30

           5.2.2     #IFNDEF            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    30

           5.2.3     #ELSE         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .    31

           5.2.4     #ENDIF          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    31

           5.2.5     #DEFINE            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    31

           5.2.6     #UNDEF          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    31

           5.2.7     #WRITE          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    31

           5.2.8     #INCLUDE             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    32

           5.2.9     #SECTION           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    32

    5.3    Variable substitution in paths             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    33


6    The IDE                                                                                                              34

    6.1    First steps with the IDE            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    34

           6.1.1     Starting the IDE          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    34

           6.1.2     IDE Command line options                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    34

           6.1.3     The IDE screen         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    35

    6.2    Navigating in the IDE            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    36

           6.2.1     Using the keyboard          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    36

           6.2.2     Using the mouse           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    36

           6.2.3     Navigating in dialogs          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    37

    6.3    Windows         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .    37

           6.3.1     Window basics          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    37

           6.3.2     Sizing and moving windows                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    38

           6.3.3     Working with multiple windows                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   38

           6.3.4     Dialog windows         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    39

    6.4    The Menu        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .    40

           6.4.1     Accessing the menu             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    40

           6.4.2     The File menu          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    40

           6.4.3     The Edit menu          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    41

           6.4.4     The Search menu           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    41

           6.4.5     The Run menu           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    42

           6.4.6     The Compile menu            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    42
                                                                  2

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           6.4.7     The Debug menu            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    43

           6.4.8     The Tools menu            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    43

           6.4.9     The Options menu            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    44

           6.4.10    The Window menu             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    45

           6.4.11    The Help menu          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    45

    6.5    Editing text       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .    46

           6.5.1     Insert modes         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    46

           6.5.2     Blocks     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .    46

           6.5.3     Setting bookmarks           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    47

           6.5.4     Jumping to a source line            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    47

           6.5.5     Syntax highlighting            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    47

           6.5.6     Code Completion           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    48

           6.5.7     Code Templates            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    49

    6.6    Searching and replacing             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    50

    6.7    The symbol browser             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    52

    6.8    Running programs             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    53

    6.9    Debugging programs             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    54

           6.9.1     Using breakpoints           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    54

           6.9.2     Using watches        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    56

           6.9.3     The call stack       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    57

           6.9.4     The GDB window              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    57

    6.10   Using Tools        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .    58

           6.10.1    The messages window              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    58

           6.10.2    Grep     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .    59

           6.10.3    The ASCII table           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    59

           6.10.4    The calculator         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    60

           6.10.5    Adding new tools          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    61

           6.10.6    Meta parameters           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    62

           6.10.7    Building a command line dialog box                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  64

    6.11   Project management and compiler options                     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  66

           6.11.1    The primary file          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    67

           6.11.2    The directory dialog           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    67

           6.11.3    The target operating system                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    67

           6.11.4    Compiler options          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    68

           6.11.5    Linker options         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    73

           6.11.6    Memory sizes         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    74

           6.11.7    Debug options          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    74

           6.11.8    The switches mode           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    75

    6.12   Customizing the IDE            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    76

           6.12.1    Preferences        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    76



                                                                  3

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           6.12.2    The desktop        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    77

           6.12.3    The Editor         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    78

           6.12.4    Mouse      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .    80

           6.12.5    Colors     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .    81

    6.13   The help system           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    82

           6.13.1    Navigating in the help system              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    82

           6.13.2    Working with help files             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    82

           6.13.3    The about dialog          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    83

    6.14   Keyboard shortcuts           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    84


7    Porting and Portable code                                                                                            88

    7.1    Turbo Pascal         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .    88

           7.1.1     Things that will not work             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    88

           7.1.2     Things which are extra              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    89

           7.1.3     Turbo Pascal compatibility mode                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   91

           7.1.4     A note on long file names under dos                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  93

    7.2    Porting Delphi Code            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    93

           7.2.1     Missing language constructs              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    93

           7.2.2     Missing calls/API incompatibilities               .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  94

           7.2.3     Best practices for porting            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    95

    7.3    Writing portable code            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    95


8    Utilities that come with Free Pascal                                                                                 97

    8.1    Demo programs and examples                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    97

    8.2    fpcmake       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  .    97

    8.3    fpdoc - Pascal Unit documenter                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    97

    8.4    h2pas - C header to Pascal Unit converter                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  98

           8.4.1     Options       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .    98

           8.4.2     Constructs         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    98

    8.5    h2paspp - preprocessor for h2pas                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  100

           8.5.1     Usage      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  100

           8.5.2     Options       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  100

    8.6    ppudump program              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  101

    8.7    ppumove program              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  101

    8.8    ptop - Pascal source beautifier            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  102

           8.8.1     ptop program         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  102

           8.8.2     The ptop configuration file              .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  103

           8.8.3     ptopu unit         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  104

    8.9    rstconv program           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  106

    8.10   unitdiff program          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  106

           8.10.1    Synopsis      .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  106



                                                                  4

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
           8.10.2    Description and usage            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  106

           8.10.3    Options       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  107


9    Units that come with Free Pascal                                                                                   108

    9.1    Standard units          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  108

    9.2    Under DOS          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  109

    9.3    Under Windows           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  110

    9.4    Under Linux and BSD-like platforms                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  110

    9.5    Under OS/2         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  110

    9.6    Unit availability       .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  111


10   Debugging your Programs                                                                                            112

    10.1   Compiling your program with debugger support                        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *12

    10.2   Using gdb to debug your program                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  113

    10.3   Caveats when debugging with gdb                    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  114

    10.4   Support for gprof, the gnu profiler                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  115

    10.5   Detecting heap memory leaks                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  115

    10.6   Line numbers in run-time error backtraces                   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *116

    10.7   Combining heaptrc and lineinfo                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  116


11   Alphabetical listing of command-line options                                                                       118


12   Alphabetical list of reserved words                                                                                122


13   Compiler messages                                                                                                  123

    13.1   General compiler messages             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  123

    13.2   Scanner messages.            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  124

    13.3   Parser messages         .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  128

    13.4   Type checking errors           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  142

    13.5   Symbol handling           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  147

    13.6   Code generator messages             .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  149

    13.7   Errors of assembling/linking stage                 .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  152

    13.8   Executable information messages.                .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  153

    13.9   Unit loading messages.           .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  154

    13.10  Command-line handling errors                  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  157

    13.11  Assembler reader errors.            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  158

           13.11.1   General assembler errors            .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  159

           13.11.2   I386 specific errors        .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  161

           13.11.3   m68k specific errors.          .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  163


14   Run-time errors                                                                                                    164



                                                                  5

____________________________________________________________________________________________________________________CONTENTS_______*
 *___
15   A sample gdb.ini file                                                                                              167


16   Options and settings                                                                                               168
                                                                  6


Chapter   1


Introduction
1.1         About  this  document


This is the user's manual for Free Pascal.  It describes the installation and use of the Free
Pascal compiler on the different supported platforms.  It does not attempt to give an exhaus-
tive  list  of  all  supported  commands,  nor  a  definition  of  the  Pascal  language.  Look  at  the
Reference guide        for these things.  For a description of the possibilities and the inner workings
of  the  compiler,  see  the  Programmers guide          .  In  the  appendices  of  this  document  you  will
find lists of reserved words and compiler error messages (with descriptions).

This document describes the compiler as it is/functions at the time of writing.  First consult
the README and FAQ files, distributed with the compiler.  The README and FAQ files are,
in case of conflict with this manual, authoritative.
1.2         About  the  compiler


Free Pascal is a 32-bit compiler for the i386 and m68k processors.  Currently, it supports the
following operating systems:


     o  dos

     o  linux

     o  Amiga (version 0.99.5 only)

     o  Windows

     o  os/2 (optionally using the EMX package, so it also works on DOS/Windows)

     o  FreeBSD

     o  BeOS (under development)

     o  Solaris (under development)

     o  PalmOS (under development)

     o  NetBSD

     o  Netware

     o  OpenBSD (under development)



                                                              7

______________________________________________________________________________________CHAPTER_1.___INTRODUCTION____________________*
 *___
Free Pascal is designed to be, as much as possible, source compatible with Turbo Pascal 7.0
and Delphi 7 (although this goal is not yet attained), but it also enhances these languages
with elements like operator overloading.  And,  unlike these ancestors,  it supports multiple
platforms.

It also differs from them in the sense that you cannot use compiled units from one system
for the other, i.e.  you cannot use TP compiled units.

Also, at the time of writing, there is a beta version of an Integrated Development Environ-
ment (IDE) available for Free Pascal.

Free Pascal consists of several parts :


    1.  The compiler program itself.

    2.  The Run-Time Library (RTL).

    3.  The packages.  This is a collection of many utility units, ranging from the whole Win-
        dows 32 API, through native ZIP/BZIP file handling to the whole GTK-2 interface.

    4.  The Free Class Library.  This is a set of class-based utility units which give a database
        framework, image support, web support, XML support and many many more.

    5.  Utility programs and units.


Of these you only need the first two, in order to be able to use the compiler.  In this document,
we describe the use of the compiler.  The RTL is described in the Reference guide       .
1.3         Getting  more  information.


If the documentation doesn't give an answer to your questions, you can obtain more infor-
mation on the Internet, on the following addresses:


     o  http://www.freepascal.org/             is the main site.  It contains also useful mail addresses and
        links to other places.  It also contains the instructions for inscribing to the mailing-list.

     o  http://community.freepascal.org:10000/                  is a forum site where questions can be posted.


Other than that, some mirrors exist.

Finally, if you think something should be added to this manual (entirely possible), please do
not hesitate and contact me at michael@freepascal.org          .  .

Let's get on with something useful.



                                                                  8


Chapter   2


Installing   the   compiler
2.1         Before  Installation  :   Requirements



2.1.1        Hardware  requirements

The compiler needs at least one of the following processors:


    1.  An  Intel  80386  or  higher  processor.   A  coprocessor  is  not  required,  although  it  will
        slow down your program's performance if you do floating point calculations without a
        coprocessor, since emulation will be used.

    2.  An AMD64 or EMT64 processor.

    3.  A PowerPC processor.

    4.  A SPARC processor

    5.  A Intel ARM processor.

    6.  Older  FPC  versions  exist  for  the  motorola  68000  processor,  but  these  are  no  longer
        maintained.


Memory and disk requirements:


    1.  8 Megabytes of free memory.  This is for compiling small programs.

    2.  Large programs such as the compiler will require at least 64 Mb.  of memory, but 128Mb
        is recommended.  (note that the programs themselves do not need so much memory)

    3.  At  least  80  Megabytes  free  disk  space.  When  the  sources  are  installed,  another  270
        Megabytes are needed.
2.1.2        Software  requirements

Under DOS


The dos distribution contains all the files you need to run the compiler and compile pascal
programs.
                                                              9

__________________________________________________________________CHAPTER_2.___INSTALLING_THE_COMPILER_____________________________*
 *___
Under UNIX


Under unix systems (such as linux) you need to have the following programs installed :


    1.  gnu as, the gnu assembler.

    2.  gnu ld, the gnu linker.

    3.  Optionally (but highly recommended) :  gnu make.  For easy recompiling of the com-
        piler and Run-Time Library, this is needed.



Under Windows


The Windows distribution contains all the files you need to run the compiler and compile
pascal programs.  However, it may be a good idea to install the mingw32 tools or the cygwin
development tools.  Links to both of these tools can be found on http://www.freepascal.org



Under OS/2


While the Free Pascal distribution comes with all necessary tools, it is a good idea to install
the EMX extender in order to compile and run programs with the Free Pascal compiler.  The
EMX extender can be found on:
http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/index.html



Under Mac OS X


Mac OS X 10.1 or higher is required, and the developer tools or XCode should be installed.
2.2         Installing  the  compiler.


The installation of Free Pascal is easy,  but is platform-dependent.  We discuss the process
for each platform separately.
2.2.1        Installing  under  DOS,  Windows  or  OS/2

Mandatory installation steps.


First, you must get the latest distribution files of Free Pascal.  They come as zip files, which
you must unzip first, or you can download the compiler as a series of separate files.  This is
especially useful if you have a slow connection, but it is also nice if you want to install only
some parts of the compiler distribution.  The distribution zip files for DOS or OS/2 contain
an installation program INSTALL.EXE. You must run this program to install the compiler.

For Windows, there is a Windows installer, setup.exe, this is a normal windows installation
program, which offers the usual options.

The screen of the DOS or OS/2 installation program looks like figure 2.1 .

The program allows you to select:


     o  What components you wish to install.  e.g do you want the sources or not, do you want
        docs or not.  Items that you didn't download when downloading as separate files, will
        not be enabled, i.e.  you can't select them.
                                                                 10

__________________________________________________________________CHAPTER_2.___INSTALLING_THE_COMPILER_____________________________*
 *___

                                 Figure 2.1:  The dos install program screen


     o Where you want to install (the default location is C:\PP).


In order to run Free Pascal from any directory on your system, you must extend your path
variable to contain the C:\PP\BIN directory.  Usually this is done in the AUTOEXEC.BAT
file.  It should look something like this :


   SET  PATH=%PATH%;C:\PP\BIN\GO32V2


for dos or


   SET  PATH=%PATH%;C:\PP\BIN\WIN32


for Windows and finally


   SET  PATH=%PATH%;C:\PP\BIN\OS2


for os/2.  (Again, assuming that you installed in the default location).

On  os/2,  Free  Pascal  installs  some  libraries  from  the  EMX  package  if  they  were  not  yet
installed (the installer will notify you if they should be installed).  They are located in the


C:\PP\DLL


directory.   The  name  of  this  directory  should  be  added  to  the  LIBPATH  directive  in  the
config.sys file:


LIBPATH=XXX;C:\PP\DLL


Obviously, any existing directories in the LIBPATH directive (indicated by XXX in the above
example) should be preserved.

                                                                 11

__________________________________________________________________CHAPTER_2.___INSTALLING_THE_COMPILER_____________________________*
 *___

                                                       Figure 2.2:

Optional Installation:  The coprocessor emulation


For  people  who  have  an  older  CPU  type,  without  math  coprocessor  (i387)  it  is  necessary
to install a coprocessor emulation, since Free Pascal uses the coprocessor to do all floating
point operations.

The installation of the coprocessor emulation is handled by the installation program (INSTALL.EXE)
under dos and Windows.
2.2.2        Installing  under  Linux

Mandatory installation steps.


The linux distribution of Free Pascal comes in three forms:


     o  a tar.gz version, also available as seperate files.

     o  a .rpm (Red Hat Package Manager) version, and

     o  a .deb (Debian) version.


If you use the .rpm format, installation is limited to


rpm  -i  fpc-X.Y.Z-N.ARCH.rpm


Where  X.Y.Z  is  the  version  number  of  the  .rpm  file,  and  ARCH  is  one  of  the  supported
architectures (i586, x86_64 etc.).

If you use Debian, installation is limited to


dpkg  -i  fpc-XXX.deb


Here again, XXX is the version number of the .deb file.



                                                                 12

__________________________________________________________________CHAPTER_2.___INSTALLING_THE_COMPILER_____________________________*
 *___
You need root access to install these packages.  The .tar file allows you to do an installation
if you don't have root permissions.

When downloading the .tar file, or the separate files, installation is more interactive.

In case you downloaded the .tar file, you should first untar the file, in some directory where
you have write permission, using the following command:


tar  -xvf  fpc.tar


We supposed here that you downloaded the file fpc.tar somewhere from the Internet.  (The
real filename will have some version number in it, which we omit here for clarity.)

When the file is untarred, you will be left with more archive files, and an install program:
an installation shell script.

If you downloaded the files as separate files, you should at least download the install.sh script,
and the libraries (in libs.tar.gz).

To install Free Pascal, all that you need to do now is give the following command:


./install.sh


And then you must answer some questions.  They're very simple, they're mainly concerned
with 2 things :


    1.  Places where you can install different things.

    2.  Deciding  if  you  want  to  install  certain  components  (such  as  sources  and  demo  pro-
        grams).


The script will automatically detect which components are present and can be installed.  It
will only offer to install what has been found.  because of this feature,  you must keep the
original names when downloading, since the script expects this.

If you run the installation script as the root user, you can just accept all installation defaults.
If you don't run as root, you must take care to supply the installation program with directory
names  where  you  have  write  permission,  as  it  will  attempt  to  create  the  directories  you
specify.  In principle, you can install it wherever you want, though.

At the end of installation, the installation program will generate a configuration file (fpc.cfg)
for the Free Pascal compiler which reflects the settings that you chose.  It will install this file
in the /etc directory or in your home directory (with name .fpc.cfg) if you do not have write
permission in the /etc directory.  It will make a copy in the directory where you installed the
libraries.

The compiler will first look for a file .fpc.cfg  in your home directory before looking in the
/etc directory.
2.3         Optional  configuration  steps


On any platform, after installing the compiler you may wish to set some environment vari-
ables.  The Free Pascal compiler recognizes the following variables :


     o  PPC_EXEC_PATH  contains  the  directory  where  support  files  for  the  compiler  can  be
        found.

     o  PPC_CONFIG_PATH specifies an alternate path to find the fpc.cfg.



                                                                 13

__________________________________________________________________CHAPTER_2.___INSTALLING_THE_COMPILER_____________________________*
 *___
     o PPC_ERROR_FILE specifies the path and name of the error-definition file.

     o FPCDIR specifies the root directory of the Free Pascal installation.  (e.g :  C:\PP\BIN)


These locations are, however, set in the sample configuration file which is built at the end
of the installation process, except for the PPC_CONFIG_PATH variable, which you must set if
you didn't install things in the default places.
2.4         Before  compiling


Also  distributed  in  Free  Pascal  is  a  README  file.  It  contains  the  latest  instructions  for
installing Free Pascal, and should always be read first.

Furthermore, platform-specific information and common questions are addressed in the FAQ.
It should be read before reporting any bug.
2.5         Testing  the  compiler


After the installation is completed and the optional environment variables are set as described
above, your first program can be compiled.

Included  in  the  Free  Pascal  distribution  are  some  demonstration  programs,  showing  what
the compiler can do.  You can test if the compiler functions correctly by trying to compile
these programs.

The compiler is called


     o  fpc.exe under Windows, os/2 and dos.

     o  fpc under most other operating systems.


To compile a program (e.g demo\hello.pp) simply type :


    fpc  hello


at the command prompt.  If you don't have a configuration file, then you may need to tell
the compiler where it can find the units, for instance as follows:


fpc  -Fuc:\pp\units\go32v2\rtl  hello


under dos, and under linux you could type


fpc  -Fu/usr/lib/fpc/NNN/units/linux/rtl  hello


(replace NNN with the version number of Free Pascal that you are using).  This is, of course,
assuming that you installed under C:\PP or /usr/lib/fpc/NNN, respectively.

If you got no error messages, the compiler has generated an executable called hello.exe under
dos,  os/2  or  Windows,  or  hello  (no  extension)  under  unix  and  most  other  operating
systems.

To execute the program, simply type :


    hello


If all went well, you should see the following friendly greeting:


Hello  world
                                                                 14


               Chapter   3


               Compiler   usage



               Here we describe the essentials to compile a program and a unit.  For more advanced uses of
               the compiler, see the section on configuring the compiler, and the Programmers guide          .

               The examples in this section suppose that you have a fpc.cfg which is set up correctly, and
               which contains at least the path setting for the RTL units.  In principle this file is generated
               by the installation program.  You may have to check that it is in the correct place (see section
               5.2  for more information on this).
               3.1         File  searching


               Before  you  start  compiling  a  program  or  a  series  of  units,  it  is  important  to  know  where
               the compiler looks for its source files and other files.  In this section we discuss this, and we
               indicate how to influence this.

Remark:         The use of slashes (/) and backslashes (\) as directory separators is irrelevant, the compiler
               will convert to whatever character is used on the current operating system.  Examples will
               be given using slashes, since this avoids problems on unix systems (such as linux).
               3.1.1        Command  line  files

               The file that you specify on the command line, such as in


               fpc  foo.pp


               will be looked for ONLY in the current directory.  If you specify a directory in the filename,
               then the compiler will look in that directory:


               fpc  subdir/foo.pp


               will look for foo.pp in the subdirectory subdir of the current directory.

               Under  case  sensitive  file  systems  (such  as  linux  and  unix),  the  name  of  this  file  is  case
               sensitive, under other operating systems (such as dos, Windows NT, os/2) this is not the
               case.
               3.1.2        Unit  files

               When  you  compile  a  unit  or  program  that  needs  other  units,  the  compiler  will  look  for
               compiled versions of these units in the following way:



                                                                             15

___________________________________________________________________________________CHAPTER_3.___COMPILER_USAGE_____________________*
 *___
    1.  It will look in the current directory.

    2.  It will look in the directory where the source file is being compiled.

    3.  It will look in the directory where the compiler binary is.

    4.  It will look in all the directories specified in the unit search path.


You can add a directory to the unit search path with the (-Fu (see page 5.1.3  )) option.  Every
occurrence of one of this options will insert a directory to the unit search path.  i.e.  the last
path on the command line will be searched first.

The compiler adds several paths to the unit search path:


    1.  The  contents  of  the  environment  variable  XXUNITS,  where  XX  must  be  replaced  with
        one of the supported targets:  GO32V2, LINUX,WIN32, OS2, BEOS, FREEBSD, NETBSD.

    2.  The standard unit directory.  This directory is determined from the FPCDIR environment
        variable.  If this variable is not set, then it is defaulted to the following:

            o  On linux:

                  /usr/local/lib/fpc/FPCVERSION
               or
                  /usr/lib/fpc/FPCVERSION

               whichever is found first.

            o  On other OSes:  the compiler binary directory, with '../' appended to it, if it exists.
               For instance, on Windows, this would mean

               C:\FPC\1.9.6\units\i386-win32

               This is assuming the compiler was installed in the directory

               C:\FPC\1.9.6

        After this directory is determined , the following paths are added to the search path:

          (a)  FPCDIR/units/FPCTARGET

         (b)   FPCDIR/units/FPCTARGET/rtl

        Here target must be replaced by the name of the target you are compiling for:  this is
        a combination of CPU and OS, so for instance


        /usr/local/lib/fpc/1.9.6/units/i386-linux/


        or, when cross-compiling


        /usr/local/lib/fpc/1.9.6/units/i386-win32/


The -Fu option accepts a single * wildcard, which will be replaced by all directories found
on that location.  For example, given the directories


rtl/units/i386-linux
fcl/units/i386-linux
packages/base
packages/extra


fpc  -Fu"*/units/i386-linux"



                                                                 16

___________________________________________________________________________________CHAPTER_3.___COMPILER_USAGE_____________________*
 *___
will have the same effect as


fpc  -Furtl/units/i386-linux  -Fufcl/units/i386-linux


since  both  the  rtl  and  fcl  directories  contain  further  units/i386-linux  subdirectories.   The
packages directory will not be added, since it doesn't contain a units/i386-linux subdirectory.

Note that (for optimization) the compiler will drop any non-existing paths from the search
path, i.e.  the existence of the path (after wildcard and environment variable expansion) will
be tested.

You can see what paths the compiler will search by giving the compiler the -vu option.

On systems where filenames are case sensitive (such as unix and linux), the compiler will :


    1.  Search for the original file name, i.e.  preserves case.

    2.  Search for the filename all lowercased.

    3.  Search for the filename all uppercased.


This is necessary, since Pascal is case-independent, and the statements Uses  Unit1; or uses
unit1; should have the same effect.

It will do this first with the extension .pp and then with the extension .pas.

For instance, suppose that the file foo.pp needs the unit bar.  Then the command


fpc  -Fu..  -Fuunits  foo.pp


will tell the compiler to look for the unit bar in the following places:


    1.  In the current directory.

    2.  In the directory where the compile binary is (not under linux).

    3.  In the parent directory of the current directory.

    4.  In the subdirectory units of the current directory

    5.  In the standard unit directory.


Also,  unit  names  that  are  longer  than  8  characters  will  first  be  looked  for  with  their  full
length.  If the unit is not found with this name, the name will be truncated to 8 characters,
and the compiler will look again in the same directories, but with the truncated name.

If the compiler finds the unit it needs, it will look for the source file of this unit in the same
directory where it found the unit.  If it finds the source of the unit, then it will compare the
file times.  If the source file was modified more recent than the unit file,  the compiler will
attempt to recompile the unit with this source file.

If the compiler doesn't find a compiled version of the unit, or when the -B option is specified,
then  the  compiler  will  look  in  the  same  manner  for  the  unit  source  file,  and  attempt  to
recompile it.

It is recommended to set the unit search path in the configuration file fpc.cfg.  If you do this,
you don't need to specify the unit search path on the command-line every time you want to
compile something.
                                                                 17

___________________________________________________________________________________CHAPTER_3.___COMPILER_USAGE_____________________*
 *___
3.1.3        Include  files

If you include files in your source with the {$I  filename} directive, the compiler will look
for it in the following places:


    1.  It will look in the path specified in the include file name.

    2.  It will look in the directory where the current source file is.

    3.  it will look in all directories specified in the include file search path.


You can add files to the include file search path with the -I (see page 5.1.3  ) or -Fi (see page
5.1.3  ) options.

As an example, consider the following include statement in a file units/foo.pp:
{$i  ../bar.inc}
Then the following command :


fpc  -Iincfiles  units/foo.pp


will cause the compiler to look in the following directories for bar.inc:


    1.  the parent directory of the current directory

    2.  the units subdirectory of the current directory

    3.  the incfiles directory of the current directory.
3.1.4        Object  files

When you link to object files (using the {$L  file.o} directive,  the compiler will look for
this file in the same way as it looks for include files:


    1.  It will look in the path specified in the object file name.

    2.  It will look in the directory where the current source file is.

    3.  it will look in all directories specified in the object file search path.


You can add files to the object file search path with the -Fo (see page 5.1.3  ) option.
3.1.5        Configuration  file

Not all options mus be given on the compiler commandline.  The compiler can use a config-
uration file wich can contain the same options as on the command-line.  Unless you specify
the -n (see page 5.1.1  ) option, the compiler will look for a configuration file fpc.cfg  in the
following places:


     o  Under unix (such as linux)

           1.  The current directory.

           2.  In your home directory, it looks for .fpc.cfg.



                                                                 18

___________________________________________________________________________________CHAPTER_3.___COMPILER_USAGE_____________________*
 *___
           3.  The directory specified in the environment variable PPC_CONFIG_PATH, and if it is
               not set, it will look in the etc directory above the compiler directory.  (for instance,
               if the compiler is in /usr/local/bin, it will look in /usr/local/etc)

           4.  In the directory /etc.

     o  Under all other OSes:

           1.  The current directory.

           2.  If it is set, the directory specified in the environment variable.  PPC_CONFIG_PATH.

           3.  The directory where the compiler is.


Versions prior to version 1.0.6 of the compiler used a configuration file ppc386.cfg.  This file
is still searched,  but it's usage is considered deprecated.  For compatibility,  fpc.cfg  will be
searched first, and if not found, the file ppc386.cfg will be used.
3.1.6        About  long  filenames

Free Pascal can handle long filenames under on all platforms, except DOS; On windows, it
will use support for long filenames if it is available (which is not always the case on older
windowses).

If no support for long filenames is present, it will truncate unit names to 8 characters.

It is not recommended to put units in directories that contain spaces in their names, since
the linker doesn't understand such filenames.
3.2         Compiling  a  program


Compiling a program is very simple.  Assuming that you have a program source in the file
prog.pp, you can compile this with the following command:


    fpc  [options]  prog.pp


The square brackets [  ] indicate that what is between them is optional.

If your program file has the .pp or .pas extension, you can omit this on the command line,
e.g.  in the previous example you could have typed:


    fpc  [options]  prog


If  all  went  well,  the  compiler  will  produce  an  executable  file.  You  can  execute  it  straight
away, you don't need to do anything else.

You  will  notice  that  there  is  also  another  file  in  your  directory,  with  extensions  .o.   This
contains  the  object  file  for  your  program.  If  you  compiled  a  program,  you  can  delete  the
object file (.o), but not if you compiled a unit.

Then the object file contains the code of the unit, and will be linked in any program that
uses the unit you compiled, so you shouldn't remove it.
3.3         Compiling  a  unit


Compiling  a  unit  is  not  essentially  different  from  compiling  a  program.   The  difference  is
mainly that the linker isn't called in this case.

To compile a unit in the file foo.pp, just type :



                                                                 19

               ___________________________________________________________________________________CHAPTER_3.___COMPILER_USAGE______*
 *__________________
                  fpc    foo


               Recall the remark about file extensions in the previous section.

               When all went well, you will be left with 2 (two) unit files:


                   1.  foo.ppu This is the file describing the unit you just compiled.

                   2.  foo.o This file contains the actual code of the unit.  This file will eventually end up in
                       the executables.


               Both files are needed if you plan to use the unit for some programs.  So don't delete them.
               If you want to distribute the unit, you must provide both the .ppu and .o file.  One is useless
               without the other.
               3.4         Units,  libraries  and  smartlinking


               The Free Pascal compiler supports smartlinking and the creation of libraries.  However, the
               default  behaviour  is  to  compile  each  unit  into  1  big  object  file,  which  will  be  linked  as  a
               whole into your program.  Shared libraries can be created on any platform except MS-DOS.

               It is also possible to take existing units and put them together in 1 static or shared library
               (using the ppumove tool, section 8.7 , page 101  ).
               3.5         Reducing  the  size  of  your  program


               When you created your program, it is possible to reduce its size.  This is possible, because the
               compiler leaves a lot of information in the program which, strictly speaking, isn't required
               for  the  execution  of  it.  The  surplus  of  information  can  be  removed  with  a  small  program
               called strip.The usage is simple.  Just type


               strip  prog


               On the command line, and the strip program will remove all unnecessary information from
               your program.  This can lead to size reductions of up to 30 %.

Remark:         In the Win32 version, strip is called stripw.

               You can use the -Xs switch to let the compiler do this stripping automatically at program
               compile time (the switch has no effect when compiling units).

               Another technique to reduce the size of a program is to use smartlinking.  Normally, units
               (including  the  system  unit)  are  linked  in  as  a  whole.   It  is  however  possible  to  compile
               units such that the can be smartlinked.  This means that only the functions and procedures
               are  linked  in  your  program,  leaving  out  any  unnecessary  code.  The  compiler  will  turn  on
               smartlinking with the -XX (see page 5.1.4  ) switch.  This technique is described in full in the
               programmers guide.

                                                                                20


Chapter   4


Compiling   problems
4.1         General  problems


     o  IO-error  -2  at  ...  :  Under linux you can get this message at compiler startup.  It
        means typically that the compiler doesn't find the error definitions file.  You can correct
        this mistake with the -Fr (see page 5.1.3  ) option under linux.

     o  Error :  File not found :  xxx or Error:  couldn't compile unit xxx: This typically
        happens when your unit path isn't set correctly.  Remember that the compiler looks
        for units only in the current directory, and in the directory where the compiler itself
        is.  If you want it to look somewhere else too, you must explicitly tell it to do so using
        the -Fu (see page 5.1.3  ) option.  Or you must set op a configuration file.
4.2         Problems  you  may  encounter  under  DOS


     o  No space in environment.
        An error message like this can occur, if you call SET_PP.BAT in the AUTOEXEC.BAT.
        To solve this problem, you must extend your environment memory.  To do this, search
        a line in the CONFIG.SYS like


        SHELL=C:\DOS\COMMAND.COM


        and change it to the following:


        SHELL=C:\DOS\COMMAND.COM  /E:1024


        You may just need to specify a higher value, if this parameter is already set.

     o   Coprocessor missing
        If the compiler writes a message that there is no coprocessor,  install the coprocessor
        emulation.

     o  Not enough DPMI memory
        If you want to use the compiler with DPMI you must have at least 7-8 MB free DPMI
        memory, but 16 Mb is a more realistic amount.

                                                              21


Chapter   5


Compiler   configuration



The output of the compiler can be controlled in many ways.  This can be done essentially in
two distinct ways:


     o  Using command-line options.

     o  Using the configuration file:  fpc.cfg.


The  compiler  first  reads  the  configuration  file.   Only  then  the  command  line  options  are
checked.  This creates the possibility to set some basic options in the configuration file, and
at the same time you can still set some specific options when compiling some unit or program.
First we list the command line options, and then we explain how to specify the command
line options in the configuration file.  When reading this, keep in mind that the options are
case sensitive.
5.1         Using  the  command-line  options


The  available  options  for  the  current  version  of  the  compiler  are  listed  by  category.  Also,
chapter 11 , page 118   for a listing as generated by the current compiler.
5.1.1        General  options

-h   if you specify this option, the compiler outputs a list of all options, and exits after that.

-?   idem as -h, waiting after every screenfull for the enter key.

-i  This  option  tells  the  compiler  to  print  the  copyright  information.   You  can  give  it  an
        option, as -ixxx where xxx can be one of the following:

         D  :  Returns the compiler date.

         V  :  Returns the compiler version.

         SO   :  Returns the compiler OS.

         SP   :  Returns the compiler processor.

         TO    :  Returns the target OS.

         TP    :  Returns the target Processor.

-l  This option tells the compiler to print the Free Pascal logo on standard output.  It also
        gives you the Free Pascal version number.



                                                              22

__________________________________________________________________CHAPTER_5.___COMPILER_CONFIGURATION______________________________*
 *___
-n  Tells the compiler not to read default the configuration file.  You can still pass a config-
       uration file with the @ option.
5.1.2        Options  for  getting  feedback

-vxxx      Be verbose.  xxx is a combination of the following :

            o  e :  Tells the compiler to show only errors.  This option is on by default.

            o  i :  Tells the compiler to show some general information.

            o  w :  Tells the compiler to issue warnings.

            o  n :  Tells the compiler to issue notes.

            o  h :  Tells the compiler to issue hints.

            o  i :  Tells the compiler to issue informational messages.

            o  l :  Tells the compiler to show the line numbers as it processes a file.  Numbers
               are shown per 100.

            o  u :  Tells the compiler to print information on the units it loads.

            o  t :  Tells the compiler to print the names of the files it tries to open.

            o  p  :  Tells  the  compiler  to  print  the  names  of  procedures  and  functions  as  it  is
               processing them.

            o  c :  Tells the compiler to warn you when it processes a conditional.

            o  m :  Tells the compiler to write which macros are defined.

            o  d :  Tells the compiler to write other debugging info.

            o  0  :  Tells  the  compiler  to  write  no  messages.   This  is  useful  when  you  want  to
               override the default setting in the configuration file.

            o  b :  Tells the compiler to show all procedure declarations if an overloaded function
               error occurs.

            o  x :  Tells the compiler to output some executable info (for Win32 platform only).

            o  r  :  Rhide/GCC  compatibility  mode:  formats  the  errors  differently,  so  they  are
               understood by RHIDE.

            o  a :  Tells the compiler to write all possible info.  (this is the same as specifying all
               options)

            o  v  write  a  file  fpcdebug.txt  with  lots  of  debugging  info.  Mainly  for  the  compiler
               developers.

            o  p write a file tree.log with the parse tree.  Mainly for the compiler developers.
5.1.3        Options  concerning  files  and  directories

-exxx     xxx specifies the directory where the compiler can find the executables as (the assem-
        bler) and ld (the linker).

-FaXYZ        loads units XYZ after the system unit, but before any other unit is loaded.  XYZ is
        a comma-separated list of unit names.  This can only be used for programs, and has
        the same effect as if  XYZ were inserted as the first item in the program's uses clause.

-FcXXX         set the input codepage to XXX. Experimental.

-FD     same as -e.

-Fexxx      This option tells the compiler to write errors, etc.  to the file named xxx.



                                                                 23

__________________________________________________________________CHAPTER_5.___COMPILER_CONFIGURATION______________________________*
 *___
-FExxx       tells the compiler to write the executable and units in directory xxx instead of the
       current directory.  If this option is followed by a -o option (-o (see page 5.1.4  )), and
       this option contains a path component, then it will override the -FE setting.

-Fixxx     Adds xxx to the include file search path.

-Flxxx     Adds xxx to the library searching path, and is passed to the linker.

-FLxxx      (linux only) Tells the compiler to use xxx as the dynamic linker.  Default this is
       /lib/ld-linux.so.2, or /Hlib/ld-linux.so.1, depending on which one is found first.

-Foxxx      Adds  xxx  to  the  object  file  search  path.  This  path  is  used  when  looking  for  files
       that need to be linked in.

-Frxxx     xxx specifies the file which contain the compiler messages.  Default the compiler has
       built-in messages.  Specifying this option will override the default messages.

-Fuxxx      Add xxx to the unit search path.  Units are first searched in the current directory.  If
       they are not found there then the compiler searches them in the unit path.  You must
       always supply the path to the system unit.  The xxx path can contain a single wildcard
       (*) which will be expanded to all possible directory names found at that location.

-FUxxx       Tells the compiler to write units in directory xxx instead of the current directory.
       It overrides the -FE option.

-Ixxx    Add xxx to the include file search path.  This option has the same effect as -Fi.
5.1.4        Options  controlling  the  kind  of  output.

for more information on these options, see also Programmers guide


-a   Tells  the  compiler  not  to  delete  the  assembler  files  it  generates  (not  when  using  the
        internal assembler).  This also counts for the (possibly) generated batch script.

-al   Tells the compiler to include the sourcecode lines in the assembler file as comments.

-an    Tells the compiler to write node information in the assember file (nodes are the way the
        compiler represents statements or parts thereof internally).  This is primarily intended
        for debugging the code generated by the compiler.

-ap    use pipes instead of creating temporary assembler files.  This may speed up the compiler
        on os/2 and linux.  Only with assemblers (such as gnu if the internal assembler is
        used.

-ar   tells the compiler to list register allocation and release info in the assembler file.  This is
        primarily intended for debugging the code generated by the compiler.

-at   tells the compiler to list information about temporary allocations and deallocations in
        the assembler file.

-Axxx      specifies what kind of assembler should be generated .  Here xxx is one of the following
        :

         default     use the built-in default.

         as  assemble using gnu as.

         nasmcoff      coff (Go32v2) file using Nasm.

         nasmelf      elf32 (Linux) file using Nasm.
                                                                 24

__________________________________________________________________CHAPTER_5.___COMPILER_CONFIGURATION______________________________*
 *___
        nasmwin32         Windows 32-bit file using Nasm.

        nasmwdosx          Windows 32-bit/DOSX file using Nasm.

        nasmobj       object file using Nasm.

        masm      object file using Masm (Microsoft).

        tasm     object file using Tasm (Borland).

        elf  elf32 (Linux) using internal writer.

        coff  coff object file (Go32v2) using the internal binary object writer.

        pecoff    pecoff object file (Win32) using the internal binary object writer.

-B   tells the compiler to re-compile all used units, even if the unit sources didn't change since
       the last compilation.

-b  tells  the  compiler  to  generate  browser  info.  This  information  can  be  used  by  an  Inte-
       grated  Development  Environment  (IDE)  to  provide  information  on  classes,  objects,
       procedures, types and variables in a unit.

-bl  is the same as -b but also generates information about local variables, types and proce-
       dures.

-Cc    set the default calling convention used by the compiler.

-CD     Create a dynamic library.  This is used to transform units into dynamically linkable
       libraries on linux.

-Ce    Emulate floating point operations.

-CfXXX        set the used floating point processor.

-Cg    enable generation of PIC code.

-Chxxx       Reserves xxx bytes heap.  xxx should be between 1024 and 67107840.

-Ci   Generate Input/Output checking code.  In case some input/output code of your program
       returns  an  error  status,  the  program  will  exit  with  a  run-time  error.  Which  error  is
       generated depends on the I/O error.

-Cn    Omit the linking stage.

-Co    Generate Integer overflow checking code.  In case of integer errors, a run-time error will
       be generated by your program.

-CpXXX         set the processor type to XXX

-Cr   Generate Range checking code.  In case your program acesses an array element with an
       invalid index, or if it increases an enumerated type beyond it's scope, a run-time error
       will be generated.

-CR     Generate  checks  when  calling  methods  to  verify  if  the  virtual  method  table  for  that
       object is valid.

-Csxxx      Set stack size to xxx.

-Ct   generate stack checking code.  In case your program performs a faulty stack operation,
       a run-rime error will be generated.

-CX     Create a smartlinked unit when writing a unit.  smartlinking will only link in the code
       parts that are actually needed by the program.  All unused code is left out.  This can
       lead to substantially smaller binaries.



                                                                 25

__________________________________________________________________CHAPTER_5.___COMPILER_CONFIGURATION______________________________*
 *___
-dxxx     Define the symbol name xxx.  This can be used to conditionally compile parts of your
       code.

-D   generate a DEF file (for OS/2)

-Dd    set the description of the executable/library (Windows)

-Dv    set the version of the executable/library (Windows)

 -E Same as -Cn.

-g  Generate debugging information for debugging with gdb

-gc   generate  checks  for  pointers.   This  must  be  used  with  the  -gh  command-line  option.
       When  this  options  is  enabled,  it  will  verify  that  all  pointer  accesses  are  within  the
       heap.

-gd   generate debugging info for dbx.

-gg   idem as -g.

-gh   use  the  heaptrc  unit  (see  Unit reference      ).  (produces  a  report  about  heap  usage  after
       the program exits)

-gl  use the lineinfo unit (see Unit reference      ).  (produces file name/line number information
       if the program exits due to an error.)

-gv   emit info for valgrind.

-gw    emit dwarf debugging info.

-kxxx     pass xxx to the linker.

-Oxxx      optimize the compiler's output; xxx can have one of the following values :

        a  specify alignment of structures.

        g  optimize for size, try to generate smaller code.

        G   optimize for time, try to generate faster code (default).

        r keep certain variables in registers (experimental, use with caution).

        u  Uncertain optimizations

        1  Level 1 optimizations (quick optimizations).

        2  Level 2 optimizations (-O1 plus some slower optimizations).

        3  Level 3 optimizations (-O2 plus -Ou).

        Pn   (Intel only) Specify processor:  n can be one of

               1  optimize for 386/486

               2  optimize for Pentium/PentiumMMX (tm)

               3  optimizations for PentiumPro/PII/Cyrix 6x86/K6 (tm)

       The exact effect of these optimizations can be found in the Programmers guide          .

-oxxx     Tells the compiler to use xxx as the name of the output file (executable).  Only with
       programs.  The output filename can contain a path, and if it does, it will override any
       previous -FE setting.  If the output filename does not contain a path, the -FE setting
       is observed.

-pg   Generate profiler code for gprof.  This will define the symbol FPC_PROFILE, which can
       be used in conditional defines.



                                                                 26

__________________________________________________________________CHAPTER_5.___COMPILER_CONFIGURATION______________________________*
 *___
-s  Tells  the  compiler  not  to  call  the  assembler  and  linker.  Instead,  the  compiler  writes  a
       script, PPAS.BAT under dos, or ppas.sh under linux, which can then be executed to
       produce an executable.  This can be used to speed up the compiling process or to debug
       the  compiler's  output.  This  option  can  take  some  extra  parameter,  mainly  used  for
       cross-compilation.  It can have one of the following values:

        h  Generate script to link on host.  The generated script can be run on the compilation
              platform (host platform).

        t Generate script to link on target platform.  The generated script can be run on the
              target platform.  (where the binary must be run)

        r Skip register allocation phase (optimizations will be disabled).

-Txxx      Specifies the target operating system.  xxx can be one of the following:

           o  emx :  OS/2 via EMX (and DOS via EMX extender)

           o  freebsd :  FreeBSD.

           o  go32v2 :  dos and version 2 of the DJ DELORIE extender.

           o  linux :  linux.

           o  netbsd :  NetBSD.

           o  netware :  Novell Netware Module (clib)

           o  netwlibc :  Novell Netware Module (libc)

           o  openbsd :  OpenBSD.

           o  os2 :  OS/2 (2.x) using the EMX extender.

           o  sunos :  SunOS/Solaris.

           o  watcom :  watcom compatible DOS extender

           o  wdosx :  WDOSX extender.

           o  win32 :  Windows 32 bit.

           o  wince :  Windows for handhelds (ARM processor) bit.

-uxxx     Undefine the symbol xxx.  This is the opposite of the -d option.

-Ur    Generate release unit files.  These files will not be recompiled, even when the sources
       are available.  This is useful when making release distributions.  This also overrides the
       -B option for release mode units.

-W    set some Windows or os/2 attributes of the generated binary.  It can be one or more
       of the following

        Bhhh      set preferred base address to hhh (a hexadecimal address)

        C   Generate a console application (+) or a gui application (-).

        D   Force use of Def file for exports.

        F  Generate a FS application (+) or a console application (-).

        G   Generate a GUI application (+) or a console application (-).

        N   Do not generate relocation section.

        R   Generate a relocation section.

        T  Generate a TOOL application (+) or a console application (-).

-Xx    executable options.  This tells the compiler what kind of executable should be generated.
       the parameter x can be one of the following:



                                                                 27

__________________________________________________________________CHAPTER_5.___COMPILER_CONFIGURATION______________________________*
 *___
           o  c :  (linux only) Link with the C library.  You should only use this when you start
              to port Free Pascal to another operating system.

           o  d  don't  use  the  standard  library  path.  This  is  needed  for  cross-compilation,  to
              avoid linking with the host platform's libraries.

           o  D : Link with dynamic libraries (defines the FPC_LINK_DYNAMIC symbol)

           o  MXXX : Set the name of the program entry routine The default is 'main'.

           o  PXXX : Prepend binutils names with XXX for cross-compiling.

           o  rXXX : set library path to XXX.

           o  s :  Strip the symbols from the executable.

           o  S : Link with static units (defines the FPC_LINK_STATIC symbol)

           o  t :  link static.  It passes the -static option to the linker.

           o  X : Link with smartlinked units (defines the FPC_LINK_SMART symbol)
5.1.5        Options  concerning  the  sources  (language  options)

for more information on these options, see also Programmers guide


-Mmode         set language mode to mode, which can be one of the following:

         delphi    tries to be Delphi compatible.  This is more strict than the objfpc mode, since
               some Free Pascal extensions are switched off.

         fpc  free pascal dialect (default)

         gpc   tries to be gpc compatible.

         macpas      tries to be compatible to the macintosh pascal dialects.

         objfpc     switch some Delphi 2 extensions on.  This is different from Delphi mode.  be-
               cause some Free Pascal constructs are still available.

         tp  tries to be TP/BP 7.0 compatible.  This means, no function overloading etc.

-Rxxx      Specifies what kind of assembler you use in your asm assembler code blocks.  Here
        xxx is one of the following:

         att   asm blocks contain AT&T-style assembler.  This is the default style.

         intel   asm blocks contain Intel-style assembler.

         direct    asm blocks should be copied as-is in the assembler, only replacing certain vari-
               ables.  file.

-S2    Switch on Delphi 2 extensions (objfpc mode).  Deprecated, use -Mobjfpc instead.

-Sa    Include  assert  statements  in  compiled  code.   Omitting  this  option  will  cause  assert
        statements to be ignored.

-Sc    Support C-style operators, i.e.  *=,  +=,  /=  and  -=.

-Sd    Tells the compiler to be Delphi compatible.  Deprecated, use -Mdelphi instead.

-SeN      The  compiler  stops  after  the  N-th  error.   Normally,  the  compiler  tries  to  continue
        compiling after an error,  until 50 errors are reached,  or a fatal error is reached,  and
        then  it  stops.  With  this  switch,  the  compiler  will  stop  after  the  N-th  error  (if  N  is
        omitted, a default of 1 is assumed).  Instead of a number, one of  n, h or w can also be
        specified, in that case the compiler will consider notes, hints or warnings as errors and
        stop when one is encountered.



                                                                 28

__________________________________________________________________CHAPTER_5.___COMPILER_CONFIGURATION______________________________*
 *___
-Sg   Support the label and goto commands.  By default these are not supported.  You must
       also specify this option if you use labels in assembler statements.  (if you use the AT&T
       style assember)

-Sh   Use  ansistrings  by  default  for  strings.   If  this  keyword  is  specified,  the  compiler  will
       interpret the string keyword as a ansistring.  Otherwise it is supposed to be a short
       strings (TP style).

-Si  Support C++ style INLINE.

-SIXXX        set interfaces style to XXX.

-Sm    Support C-style macros.

-So   Try to be Borland TP 7.0 compatible.  Deprecated, use -Mtp instead.

-Sp   Try to be gpc (gnu pascal compiler) compatible.  Deprecated, use -Mgpc instead.

-Ss   The name of constructors must be init, and the name of destructors should be done.

-St   Allow the static keyword in objects.

-Un    Do  not  check  the  unit  name.  Normally,  the  unit  name  is  the  same  as  the  filename.
       This option allows both to be different.

-Us    Compile a system unit.  This option causes the compiler to define only some very basic
       types.
5.2         Using  the  configuration  file


Using  the  configuration  file  fpc.cfg  is  an  alternative  to  command  line  options.   When  a
configuration file is found, it is read, and the lines in it are treated like you typed them on
the command line.  They are treated before the options that you type on the command line.

You can specify comments in the configuration file with the # sign.  Everything from the #
on will be ignored.

The algorithm to determine which file is used as a configuration file is decribed in 3.1.5   on
page 18 .

When  the  compiler  has  finished  reading  the  configuration  file,  it  continues  to  treat  the
command line options.

One of the command-line options allows you to specify a second configuration file:  Specifying
@foo on the command line will open file foo, and read further options from there.  When the
compiler has finished reading this file, it continues to process the command line.

The configuration file allows some kind of preprocessing.  It understands the following direc-
tives, which you should place on the first column of a line :


#IFDEF

#IFNDEF

#ELSE

#ENDIF

#DEFINE

#UNDEF



                                                                 29

__________________________________________________________________CHAPTER_5.___COMPILER_CONFIGURATION______________________________*
 *___
#WRITE

#INCLUDE

#SECTION


They work the same way as their {$...} counterparts in Pascal.  All the default defines used
to compile source code are also defined while processing the configuration file.  For example,
if the target compiler is an intel 80x86 compatile linux platform, both cpu86 and linux will
be  defined  while  interpreting  the  configuration  file.  For  the  possible  default  defines  when
compiling, consult Appendix G of the Programmers guide          .

What follows is a description of the different directives.
5.2.1        #IFDEF

Syntax:


#IFDEF  name


Lines following #IFDEF are skipped read if the keyword name following it is not defined.

They  are  read  until  the  keywords  #ELSE  or  #ENDIF  are  encountered,  after  which  normal
processing is resumed.

Example :


#IFDEF  VER0_99_5
-Fu/usr/lib/fpc/0.99.5/linuxunits
#ENDIF


In the above example, /usr/lib/fpc/0.99.5/linuxunits will be added to the path if you're com-
piling with version 0.99.5 of the compiler.
5.2.2        #IFNDEF

Syntax:


#IFNDEF  name


Lines following #IFNDEF are skipped read if the keyword name following it is defined.

They  are  read  until  the  keywords  #ELSE  or  #ENDIF  are  encountered,  after  which  normal
processing is resumed.

Example :


#IFNDEF  VER0_99_5
-Fu/usr/lib/fpc/0.99.6/linuxunits
#ENDIF


In the above example, /usr/lib/fpc/0.99.6/linuxunits will be added to the path if you're NOT
compiling with version 0.99.5 of the compiler.


                                                                 30

__________________________________________________________________CHAPTER_5.___COMPILER_CONFIGURATION______________________________*
 *___
5.2.3        #ELSE

Syntax:


#ELSE


#ELSE can be specified after a #IFDEF or #IFNDEF directive as an alternative.  Lines following
#ELSE are skipped read if the preceding #IFDEF or #IFNDEF was accepted.

They are skipped until the keyword #ENDIF is encountered, after which normal processing is
resumed.

Example :


#IFDEF  VER0_99_5
-Fu/usr/lib/fpc/0.99.5/linuxunits
#ELSE
-Fu/usr/lib/fpc/0.99.6/linuxunits
#ENDIF


In the above example, /usr/lib/fpc/0.99.5/linuxunits will be added to the path if you're com-
piling  with  version  0.99.5  of  the  compiler,  otherwise  /usr/lib/fpc/0.99.6/linuxunits  will  be
added to the path.
5.2.4        #ENDIF

Syntax:


#ENDIF


#ENDIF  marks  the  end  of  a  block  that  started  with  #IF(N)DEF,  possibly  with  an  #ELSE
between it.
5.2.5        #DEFINE

Syntax:


#DEFINE  name


#DEFINE defines a new keyword.  This has the same effect as a -dname command-line option.
5.2.6        #UNDEF

Syntax:


#UNDEF  name


#UNDEF un-defines a keyword if it existed.  This has the same effect as a -uname command-line
option.
5.2.7        #WRITE

Syntax:
                                                                 31

__________________________________________________________________CHAPTER_5.___COMPILER_CONFIGURATION______________________________*
 *___
#WRITE  Message  Text


#WRITE writes Message  Text to the screen.  This can be useful to display warnings if certain
options are set.

Example:


#IFDEF  DEBUG
#WRITE  Setting  debugging  ON...
-g
#ENDIF


if  DEBUG is defined, this will produce a line


Setting  debugging  ON...


and will then switch on debugging information in the compiler.
5.2.8        #INCLUDE

Syntax:


#INCLUDE  filename


#INCLUDE instructs the compiler to read the contents of filename before continuing to process
options in the current file.

This can be useful if you want to have a particular configuration file for a project (or, under
linux, in your home directory), but still want to have the global options that are set in a
global configuration file.

Example:


#IFDEF  LINUX
    #INCLUDE  /etc/fpc.cfg
#ELSE
    #IFDEF  GO32V2
       #INCLUDE  c:\pp\bin\fpc.cfg
    #ENDIF
#ENDIF


This will include /etc/fpc.cfg if you're on a linux machine, and will include c:\pp\bin\fpc.cfg
on a dos machine.
5.2.9        #SECTION

Syntax:


#SECTION  name


The #SECTION directive acts as a #IFDEF directive, only it doesn't require an #ENDIF directive.
the special name COMMON always exists, i.e.  lines following #SECTION  COMMON are always read.
                                                                 32

__________________________________________________________________CHAPTER_5.___COMPILER_CONFIGURATION______________________________*
 *___
5.3         Variable  substitution  in  paths


To avoid having to edit your configuration files too often, the compiler allows you to specify
the following variables in the paths that you feed to the compiler:


FPCFULLVERSION                     is replaced by the compiler's version string.

FPCVERSION                is replaced by the compiler's version string.

FPCDATE            is replaced by the compiler's date.

FPCTARGET               is replaced by the compiler's target (combination of CPU-OS)

FPCCPU           is also replaced by the compiler's target CPU.

FPCOS         is replaced by the compiler's target OS.


To have these variables subsituted, just insert them with a $ prepended, as follows:


-Fu/usr/lib/fpc/$FPCVERSION/rtl/$FPCOS


This is equivalent to


-Fu/usr/lib/fpc/0.99.12a/rtl/linux


If the compiler version is 0.99.12a and the target os is linux.

These replacemens are valid on the command-line and also in the configuration file.

On the linux command-line,  you must be careful to escape the $ since otherwise the shell
will expand the variable for you, which may have undesired effects.
                                                                 33


               Chapter   6


               The   IDE



               The IDE (Integrated Development Environment) provides a comfortable user interface to
               the  compiler.  It  contains  an  editor  with  syntax  highlighting,  a  debugger,  symbol  browser
               etc.  The IDE is a text-mode application which has the same look and feel on all supported
               operating systems.  It is modelled after the IDE of Turbo Pascal, so many people should feel
               comfortable using it.

               Currently, the IDE is available for dos, Windows and linux.
               6.1         First  steps  with  the  IDE



               6.1.1        Starting  the  IDE

               The IDE is started by entering the command:


               fp


               at the command line.  It can also be started from a graphical user interface such as Windows.

Remark:         Under Windows, it is possible to switch between windowed mode and full screen mode by
               pressing Alt-Enter).
               6.1.2        IDE  Command  line  options

               When starting the IDE, command line options can be passed:


               fp  [-option]  [-option]  ...  <file  name>  ...


               Option is one of the following switches (the option letters are case insensitive):


               -N    (dos only) Do not use long file names.  Windows 95 and later versions of  Windows
                       provide  an  interface  to  DOS  applications  to  access  long  file  names.   The  IDE  uses
                       this interface by default to access files.  Under certain circumstances, this can lead to
                       problems.  This switch tells the IDE not to use the long filenames.

               -Cfilename         This  option,  followed  by  a  filename,  tells  the  IDE  to  read  its  options  from
                       filename.  There should be no whitespace between the file name and the -C.

               -F   use  alternative  graphic  characters.   This  can  be  used  to  run  the  IDE  on  linux  in  an
                       X-term or through a telnet session.



                                                                             34

               __________________________________________________________________________________________________CHAPTER_6.___THE_I*
 *DE________________
               -R   After starting the IDE, it changes automatically to the directory which was active when
                      the IDE exited the last time.

               -S  Disable the mouse.  When this option is used, then the mouse is disabled, even if a mouse
                      is present.

               -Tttyname         (linux/unix only) Sends program output to tty ttyname.  This is useful so one
                      doesn't have to switch between program output and ide all the time.


               The files given at the command line are loaded into edit windows automatically.

Remark:         Under  DOS/Win32,  the  first  character  of  a  command-line  option  can  be  a  /  character
               instead of a - character.  So /S is equivalent to -S.
               6.1.3        The  IDE  screen

               After start up, the screen of the IDE can look like figure (6.1 ).



                                         Figure 6.1:  The IDE screen immediately after startup

               At top of the screen the menu bar  is visible, at the bottom the status bar.  The empty space
               between them is called the desktop.

               The status bar shows the keyboard shortcuts for frequently used commands, and allows quick
               access to these commands by clicking them with the mouse.  At the right edge of the status
               bar,  the  current  amount  of  unused  memory  is  displayed.  This  is  only  an  indication,  since
               the IDE tries to allocate more memory from the operating system if it runs out of memory.

               The menu provides access to all of the IDE's functionality, and at the right edge of the menu,
               a clock is displayed.

               The IDE can be left by selecting "File_Exit" in the menu 1  or by pressing Alt-X.

Remark:          If  a  file  fp.ans  is  found  in  the  current  directory,  then  it  is  loaded  and  used  to  paint  the
               background.  This file should contain ANSI drawing commands to draw on a screen.
               ___________________________________________________1
                    "File_Exit" means select the item 'Exit' in the menu 'File'.



                                                                                35

               __________________________________________________________________________________________________CHAPTER_6.___THE_I*
 *DE________________
               6.2         Navigating  in  the  IDE


               The  IDE  can  be  navigated  both  with  the  keyboard  and  with  a  mouse,  if  the  system  is
               equipped with a mouse.
               6.2.1        Using  the  keyboard

               All functionality of the IDE is available through use of the keyboard.


                    o  It is used for typing and navigating through the sources.

                    o  Editing commands such as copying and pasting text.

                    o  Moving and resizing windows.

                    o  It can be used to access the menu, by pressing ALT and the appropriate highlighted
                       menu letter, or by pressing F10 and navigating through the menu with the arrow keys.

                       more information on the menu can be found in section 6.4 , page 40

                    o  Many commands in the IDE are bound to shortcuts, i.e.  typing a special combination
                       of keys will execute a command immediately.


Remark:


                    o  When  working  in  a  linux  X-Term  or  through  a  telnet  session,  the  key  combination
                       with Alt may not be available.  To remedy this, the Ctrl-Z combination can be typed
                       first.  This means that e.g.  Alt-X can be replaced by Ctrl-Z X.

                    o  A complete reference of all keyboard shortcuts can be found in section 6.14  , page 84 .
               6.2.2        Using  the  mouse

               If the system is equipped with a mouse, it can be used to work with the IDE. The left button
               is used to select menu items, press buttons, select text blocks etc.

               The  right  mouse  button  is  used  to  access  the  local  menu,  if  available.  Holding  down  the
               Ctrl  or  Alt  key  and  clicking  the  right  button  will  execute  user  defined  functions,  see
               section 6.12.4  , page 80 .

Remark:


                   1.  Occasionally, the manual uses the term "drag the mouse".  This means that the mouse
                       is moved while the left mouse button is being pressed.

                   2.  The action of mouse buttons may be reversed, i.e.  the actions of the left mouse button
                       can be assigned to the right mouse button and vice versa 2 .  Throughout the manual,
                       it is assumed that the actions of the mouse buttons are not reversed.

                   3.  The mouse is not always available, even if a mouse is installed:

                           o  The IDE is running under linux through a telnet connection from a Windows
                              machine.

                           o  The IDE is running under linux in an X-term under X-windows.

                   4.  On  Windows,  the  console  has  an  option  'Quick  edit',  allowing  to  copy  text  to  the
                       clipboard by selecting text in the console window.  If this mode is enabled, the mouse
                       will  not  work.   The  'Quick  edit'  option  should  be  disabled  in  the  console  window's
               ________properties_for_the_IDE_to_receive_mouse_events._
                   2See section 6.12.4 , page 80  for more information on how to reverse the actions of the mouse buttons.



                                                                                36

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
6.2.3        Navigating  in  dialogs

Dialogs usually have a lot of elements in them such as buttons, edit fields, memo fields, list
boxes and so on.  To activate one of these fields, it is sufficient to:


    1.  Click on the element with the mouse.

    2.  Press the Tab key till the focus reaches the mouse

    3.  Press the highlighted letter in the element's label.  If the focus is currently on an element
        that allows to edit,  then Alt should be pressed simultaneously with the highlighted
        letter.  For a button, the action associated with the button will then be executed.


Inside  edit  fields,  list  boxes,  memos,  navigation  is  carried  out  with  the  usual  arrow  key
commands.
6.3         Windows


Nowadays, working with windowed applications should be no problem for most Windows
and linux users.  Nevertheless, the following section describes how the windows work in the
Free Pascal IDE, to allow efficient work with it.
6.3.1        Window  basics

A common IDE window is displayed in figure (6.2 ).



                                      Figure 6.2:  A common IDE window
The window is surrounded by a so-called frame, the white double line around the window.

At the top of the window 4 things are displayed:


     o  At  the  upper  left  corner  of  the  window,  a  close  icon  is  shown.   When  clicked,  the
        window will be closed.  It can be also closed by pressing Alt-F3 or selecting the menu
        item "Window_Close".  All open windows can be closed by selecting the menu item
        "Window_Close all".

     o  In the middle, the title of the window is displayed.
                                                                 37

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
     o Almost  at  the  upper  right  corner,  a  number  is  visible.   This  number  identifies  the
       editor window, and pressing Alt-Number will jump to this window.  Only the first 9
       windows will get such a number.

     o At the upper right corner, a small green arrow is visible.  Clicking this arrow zooms the
       window so it covers the whole desktop.  Clicking this arrow on a zoomed window will
       restore old size of the window.  Pressing the key F5 has the same effect as clicking that
       arrow.   The  same  effect  can  be  achieved  with  the  menu  item  "Window_Zoom".
       Windows and dialogs which aren't resizeable can't be zoomed, either.


The  right  edge  and  bottom  edges  of  a  window  contain  scrollbars.   They  can  be  used  to
scroll the window contents with the mouse.  The arrows at the ends of the scrollbars can be
clicked to scroll the contents line by line.  Clicking on the dotted area between the arrows
and the cyan-coloured rectangle will scroll the window's content page by page.  By dragging
the rectangle the content can be scrolled continuously.

The star and the numbers in the lower left corner of the window display information about
the contents of the window.  They are explained in the section about the editor, see section
6.5 , page 46 .
6.3.2        Sizing  and  moving  windows

A window can be moved and sized using the mouse and the keyboard:  To move a window:


     o  using the mouse, click on the title bar and drag the window with the mouse.

     o  using the keyboard, go into the size/move mode by pressing Ctrl-F5 or selecting the
        menu  item  "Window_Size/Move".  .  Using  the  cursor  keys  the  window  can  be
        moved.  The size/move mode can be left by pressing Enter.  In this case, the window
        will keep its size and position.  Alternatively, pressing Esc will restore the old position.


To resize a window:


     o  using the mouse, click on the lower right corner of the window and drag it.

     o  using the keyboard, go into the size/move mode by pressing Ctrl-F5 or selecting the
        menu  item  "Window_Size/Move".  The  window  frame  will  be  green  to  indicate
        that the IDE is in size/move mode.  By pressing shift and the cursor keys simultane-
        ously, the window can be resized.  The size/move mode can be left by pressing Enter.
        In this case, the window will keep the new size.  Pressing Esc will restore the old size.


Not all windows can be resized.  This applies, for example, to dialog windows  (section 6.3.4  ,
page 39 ).

A  window  can  also  be  hidden.  To  hide  a  window,  the  Ctrl-F6  key  combination  can  be
used, or the "Window_Hide" menu may be selected.  To restore a Hidden window, it is
necessary to select it from the window list.  More information about the window list can be
found in the next section.
6.3.3        Working  with  multiple  windows

When  working  with  larger  projects,  it  is  likely  that  multiple  windows  will  appear  on  the
desktop.  However, only one of these windows will be the active window, all other windows
will be inactive.

An inactive window is identified by a grey frame.  An inactive window can be made active
in one of several ways:



                                                                 38

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
     o using the mouse, activate a window by clicking on it.

     o using  the  keyboard,  pressing  F6  will  step  trough  all  open  windows.  To  activate  the
       previously activated window, Shift-F6 can be used.

     o the  menu  item  "Window_Next"  can  be  used  to  activate  the  next  window  in  the
       list of windows, while Window|Previous will select the previous window.

     o If the window has a number in the upper right corner, it can be activated by pressing
       Alt-<number>.

     o Pressing Alt-0 will pop up a dialog with all available windows which allows a quick
       activation of windows which don't have a number.


The windows can be ordered and placed on the IDE desktop by zooming and resizing them
with the mouse or keyboard.  This is a time-consuming task, and particularly difficult with
the keyboard.  Instead, the menu items "Window_Tile  nd "Window_Cascade" can
be used:


Tile   will divide whole desktop space evenly between all resizable windows.

Cascade       puts all windows in a cascaded position.


In very rare cases the screen of the IDE may be mixed up.  In this case the whole IDE screen
can be refreshed by selecting the menu item "Window_Refresh display".
6.3.4        Dialog  windows

In many cases the IDE displays a dialog window to get user input.  The main difference to
normal windows is that other windows cannot be activated while a dialog is active.  Also the
menu is not accessible while in a dialog.  This behaviour is called modal.  To activate another
window, the modal window or dialog must be closed first.

A typical dialog window is shown in figure (6.3 ).



                                      Figure 6.3:  A typical dialog window
                                                                 39

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
6.4         The  Menu


The main menu (the gray bar at the top of the IDE) provides access to all the functionality of
the IDE. It also displays a clock, displaying the current time.  The menu is always available,
except  when  a  dialog  is  opened.  If  a  dialog  is  opened,  it  must  be  closed  first  in  order  to
access the menu.

In  certain  windows,  a  local  menu  is  also  available.  The  local  menu  will  appear  where  the
cursor is, and provides additional commands that are context-sensitive.
6.4.1        Accessing  the  menu

The menu can be accessed in a number of ways:


    1.  By  using  the  mouse  to  select  items.   The  mouse  cursor  should  be  located  over  the
        desired menu item, and a left mouse click will then select it.

    2.  By pressing F10.  This will switch the IDE focus to the menu.  Use the arrow keys can
        then be used to navigate in the menu, the Enter key should be used to select items.

    3.  To access menu items directly, Alt-<highlighted  menu  letter> can be used to
        select a menu item.  Afterwards submenu entries can be selected by pressing the high-
        lighted letter, but without Alt.  E.g.  Alt-S  G is a fast way to display the goto line
        dialog.


Every menu item is explained by a short text in the status bar.

When  a  local  menu  is  available,  it  can  be  accessed  by  pressing  the  right  mouse  button  or
Alt-F10.

In the subsequent, all menu entries and their actions are described.
6.4.2        The  File  menu

The "File" menu contains all menu items that allow to load and save files, as well as to exit
the IDE.


New      Opens a new, empty editor window.

New from template                Prompts  for  a  template  to  be  used,  asks  to  fill  in  any  parameters,
        and then starts a new editor window with the template.

Open      (F3)  Presents  a  file  selection  dialog,  and  opens  the  selected  file  in  a  new  editor
        window.

Save     (F2) Saves the contents of the current edit window with the current filename.  If the
        current  edit  window  does  not  yet  have  a  filename,  a  dialog  is  presented  to  enter  a
        filename.

Save as      Presents a dialog in which a filename can be entered.  The current window's contents
        are then saved to this new filename, and the filename is stored for further save actions.

Change dir         Presents a dialog in which a directory can be selected.  The current working
        directory is then changed to the selected directory.

Command shell             Executes  a  command  shell.   After  the  shell  exited,  the  IDE  resumes.
        Which command shell is executed depends on the system.
                                                                 40

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
Exit    (ALT-X) Exits the IDE. If any unsaved files are in the editor, the IDE will ask if these
       files should be saved.


Under the "Exit" menu appear some filenames of recently used files.  These entries can be
used to quickly reload these files in the editor.
6.4.3        The  Edit  menu

The "Edit" menu contains entries for accessing the clipboard, and undoing or redoing editing
actions.  Most of these functions have shortcut keys associated with them.


Undo      (ALT-BKSP) Undo the last editing action.  The editing actions are stored in a buffer,
        selecting this mechanism will move backwards through this buffer, i.e.  multiple undo
        levels are possible.  The selection is not preserved, though.

Redo      Redo  the  last  action  that  was  previously  undone.   Redo  can  redo  multiple  undone
        actions.

Cut     (Shift-DEL) Copy the current selection to the clipboard and delete the selection from
        the text.  Any previous clipboard contents is lost after this action.  After this action,
        the clipboard contents can be pasted elsewhere in the text.

Copy      (Ctrl-INS)  Copy  the  current  selection  to  the  clipboard.   Any  previous  clipboard
        contents  is  lost  after  this  action.   After  this  action,  the  clipboard  contents  can  be
        pasted elsewhere in the text.

Paste     (Shift-INS) Insert the current clipboard contents in the text at the cursor position.
        The clipboard contents remains as it was.

Clear     (Ctrl-DEL) Clears (i.e.  deletes) the current selection.

Show clipboard            Opens a window in which the current clipboard contents is shown.


When running an IDE under Windows, the "Edit" menu has two additional entries.  The
IDE  maintains  a  separate  clipboard  which  does  not  share  its  contents  with  the  windows
clipboard.  To access the Windows clipboard, the following two entries are also present:


Copy to Windows               this will copy the selection to the Windows clipboard.

Paste from Windows                 this will insert the content of the windows clipboard (if it contains
        text) in the edit window at the current cursor position.
6.4.4        The  Search  menu

The "Search" menu provides access to the search and replace dialogs, as well as access to
the symbol browser of the IDE.


Find     (Ctrl-Q F) Presents the search dialog.  A search text can be entered, and when the
        dialog is closed, the entered text is searched in the active window.  If the text is found,
        it will be selected.

Replace       (Ctrl-Q  A)  Presents  the  search  and  replace  dialog.  After  the  dialog  is  closed,
        the search text will be replaced by the replace text in the active window.

Search again          (CTRL-L) Repeats the last search or search and replace action,  using the
        same parameters.



                                                                 41

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
Go to line number             (Alt-G)  Prompts  for  a  line  number,  and  then  jumps  to  this  line
       number.


When the program and units are compiled with browse information, then the following menu
entries are also enabled:


Find procedure           Not yet implemented.

Objects      Asks for the name of an object and opens a browse window for this object.

Modules        Asks for the name of a module and opens a browse window for this object.

Globals      Asks for the name of a global symbol and opens a browse window for this object.

Symbol       Opens a window with all known symbols, so a symbol can be selected.  After the
       symbol is selected, a browse window for that symbol is opened.
6.4.5        The  Run  menu

The R n" menu contains all entries related to running a program,


Run      (Ctrl-F9)  If  the  sources  were  modified,  compiles  the  program.   If  the  compile  is
        successful,  the program is executed.  If the primary file was set,  then that is used to
        determine which program to execute.  See section 6.4.6  , page 42  for more information
        on how to set the primary file.

Step over        (F8) Run the program till the next source line is reached.  If any calls to proce-
        dures are made, these will be executed completely as well.

Trace into        (F7)  Execute  the  current  line.   If  the  current  line  contains  a  call  to  another
        procedure, the process will stop at the entry point of the called procedure.

Goto cursor          (F4) Runs the program till the execution point matches the line where the
        cursor is.

Until return         Runs the current procedure till it exits.

Parameters          This  menu  item  allows  to  enter  parameters  that  will  be  passed  on  to  the
        program when it is being executed.

Program reset           (Ctrl-F2) if the program is being run or debugged, the debug session is
        aborted, and the running program is killed.
6.4.6        The  Compile  menu

The C mpile" menu contains all entries related to compiling a program or unit.


Compile        (Alt-F9) Compiles the contents of the active window, irrespective of the primary
        file setting.

Make      (F9)  Compiles  the  contents  of  the  active  window,  and  any  files  that  the  unit  or
        program depends on and that were modified since the last compile.  If the primary file
        was set, the primary file is compiled instead.

Build     Compiles the contents of the active window, and any files that the unit or program
        depends on, whether they were modified or not.  If the primary file was set, the primary
        file is compiled instead.



                                                                 42

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
Target     Sets the target operating system for which should be compiled.

Primary file        Sets  the  primary  file.   If  set,  any  run  or  compile  command  will  act  on  the
       primary file instead of on the active window.  The primary file need not be loaded in
       the IDE for this to have effect.

Clear primary file           Clears the primary file.  After this command, any run or compile action
       will act on the active window.

Information         Displays some information about the current program.

Compiler messages              (F12)  Displays  the  compiler  messages  window.   This  window  will
       display the messages generated by the compiler during the last compile.
6.4.7        The  Debug  menu

The "Debug" menu contains menu entries to aid in debugging a program, such as setting
breakpoints and watches.


Output

User screen         (Alt-F5) Switches to the screen as it was last left by the running program.

Breakpoint         (Ctrl-F8) Sets a breakpoint at the current line.  When debugging, program
        execution will stop at this breakpoint.

Call stack       (Ctrl-F3)  Shows  the  call  stack.   The  call  stack  is  the  list  of  addresses  (and
        filenames and line numbers, if this information was compiled in) of procedures that are
        currently being called by the running program.

Registers       Shows the current content of the CPU registers.

Add watch          (Ctrl-F7) Add a watch.  A watch is an expression that can be evaluated by
        the IDE and will be shown in a special window.  Usually this is the content of some
        variable.

Watches        Shows the current list of watches in a separate window.

Breakpoint list          Shows the current list of breakpoints in a separate window.

GDB window             Shows  the  GDB  debugger  console.  This  can  be  used  to  interact  with  the
        debugger directly; here arbitrary GDB commands can be typed and the result will be
        shown in the window.
6.4.8        The  Tools  menu

The Tols" menu defines some standard tools.  If new tools are defined by the user, they
are appended to this menu as well.


Messages        (F11) Show the messages window.  This window contains the output from one
        of the tools.  For more information, see section 6.10.1  , page 58 .

Goto next         (Alt-F8) Goto next message.

Goto previous           (Alt-F7) Goto previous message
                                                                 43

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
Grep     (SHIFT-F2) Prompts for a regular expression and options to be given to grep, and
       then executes grep with the given expression and options.  For this to work, the grep
       program must be installed on the system,  and be in a directory that is in the PATH.
       For more information, see section 6.10.2  , page 59 .

Calculator        Displays the calculator.  For more information, see section 6.10.4  , page 60

Ascii table       Displays the ASCII table.  For more information, see section 6.10.3  , page 59
6.4.9        The  Options  menu

The   ptions"  menu  is  the  entry  point  for  all  dialogs  that  are  used  to  set  options  for
compiler and IDE, as well as the user preferences.


Mode       Presents a dialog to set the current mode of the compiler.  The current mode is shown
        at the right of the menu entry.  For more information, see section 6.11.8  , page 75 .

Compiler        Presents  a  dialog  that  can  be  used  to  set  common  compiler  options.   These
        options will be used when compiling a program or unit.

Memory sizes           Presents  a  dialog  where  the  stack  size  and  the  heap  size  for  the  program
        can be set.  These options will be used when compiling a program.

Linker      Presents a dialog where some linker options can be set.  These options will be used
        when a program or library is compiled.

Debugger         Presents a dialog where the debugging options can be stored.  These options are
        used when compiling units or programs.  Note that the debugger will not work unless
        debugging information is generated in the program.

Directories        Presents a dialog where the various directories needed by the compiler can be
        set.  These directories will be used when a program or unit is compiled.

Browser        Presents a dialog where the browser options can be set.  The browser options affect
        the behaviour of the symbol browser of the IDE.

Tools     Presents  a  dialog  to  configure  the  tools  menu.   For  more  information,  see  section
        6.10.5  , page 61 .

Environment           Presents  a  dialog  to  configure  the  behaviour  of  the  IDE.  A  sub  menu  is
        presented with the various aspects of the IDE:

         Preferences        General preferences, such as whether to save files or not, and which files
               should be saved.  The video mode can also be set here.

         Editor     Controls various aspects of the edit windows.

         CodeComplete            Used to set the words which can be automatically completed when
               typing in the editor windows.

         Codetemplates           Used  to  define  code  templates,  which  can  be  inserted  in  an  edit
               window.

         Desktop       Used  to  control  the  behaviour  of  the  desktop,  i.e.  several  features  can  be
               switched on or off.

         Mouse      Can be used to control the actions of the mouse, and to assign commands to
               various mouse actions.

         Startup      Not yet implemented.

         Colors     Here the various colors used in the IDE and the editor windows can be set.



                                                                 44

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
Open      Presents  a  dialog  in  which  a  file  with  editor  preferences  can  be  selected.  after  the
       dialog is closed, the preferences file will be read and the preferences will be applied.

Save    Save the current options in the default file.

Save as      Saves  the  current  options  in  an  alternate  file.  A  file  selection  dialog  box  will  be
       presented in which the alternate settings file can be entered.


Please note that options are not saved automatically, they should be saved explicitly with
the  ptions_Save" command.
6.4.10         The  Window  menu

The "Window" menu provides access to some window functions.  More information on all
these functions can be found in section 6.3 , page 37


Tile    Tiles all opened windows on the desktop.

Cascade        Cascades all opened windows on the desktop.

Close all      Close all opened windows.

Size/move         (Ctrl-F5) Put the IDE in Size/move modus;  after this command the active
        window can be moved and resized using the arrow keys.

Zoom       (F5) Zooms or unzooms the current window.

Next      (F6) Activates the next window in the window list.

Previous        (SHIFT-F6) Activates the previous window in the window list.

Hide     (Ctrl-F6) Hides the active window.

Close     (ALT-F3) Closes the active window.

List    (Alt-0)  Shows  the  list  of  opened  windows.  From  there  a  window  can  be  activated,
        closed, shown and hidden.

Refresh display           Redraws the screen.
6.4.11         The  Help  menu

The "Help" menu provides entry points to all the help functionality of the IDE, as well as
the entry to customize the help system.


Contents        Shows the help table of contents

Index      (SHIFT-F1) Jumps to the help Index.

Topic search         (CTRL-F1)  Jumps  to  the  topic  associated  with  the  currently  highlighted
        text.

Previous topic           (ALT-F1) Jumps to the previously visited topic.

Using help         Displays help on using the help system.

Files    Allows to configure the help menu.  With this menu item, help files can be added to
        the help system.

About       Displays information about the IDE. See section 6.13.3  , page 83  for more informa-
        tion.



                                                                 45

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
6.5         Editing  text


In this section, the basics of editing (source) text are explained.  The IDE works like many
other  text  editors  in  this  respect,  so  mainly  the  distinguishing  points  of  the  IDE  will  be
explained.
6.5.1        Insert  modes

Standard, the IDE is in insert mode.  This means that any text that is typed will be inserted
before text that is present after the cursor.

In overwrite mode, any text that is typed will replace existing text.

When in insert mode, the cursor is a flat blinking line.  If the IDE is in overwrite, the cursor
is  a  cube  with  the  height  of  one  line.   Switching  between  insert  mode  or  overwrite  mode
happens with the Insert key or with the Ctrl-V key.
6.5.2        Blocks

The  IDE  handles  selected  text  just  as  the  Turbo  Pascal  IDE  handles  it.   This  is  slightly
different from the way e.g.  Windows applications handle selected text.

Text can be selected in 3 ways:


    1.  Using the mouse, dragging the mouse over existing text selects it.

    2.  Using the keyboard, press Ctrl-K B to mark the beginning of the selected text, and
        Ctrl-K K to mark the end of the selected text.

    3.  Using  the  keyboard,  hold  the  Shift  key  depressed  while  navigating  with  the  cursor
        keys.


There are also some special select commands:


    1.  The current line can be selected using Ctrl-K L.

    2.  The current word can be selected using Ctrl-K T.


In  the  Free  Pascal  IDE,  selected  text  is  persistent.   After  selecting  a  range  of  text,  the
cursor can be moved, and the selection will not be destroyed; hence the term 'block' is more
appropriate for the selection, and will be used henceforth...

Several commands can be executed on a block:


     o  Move the block to the cursor location (Ctrl-K V).

     o  Copy the block to the cursor location (Ctrl-K C).

     o  Delete the block (Ctrl-K Y).

     o  Write the block to a file (Ctrl-K W).

     o  Read the contents of a file into a block (Ctrl-K  R). If there is already a block, this
        block  is  not  replaced  by  this  command.   The  file  is  inserted  at  the  current  cursor
        position, and then the inserted text is selected.

     o  Indent a block (Ctrl-K I).

     o  Undent a block (Ctrl-K U).



                                                                 46

               __________________________________________________________________________________________________CHAPTER_6.___THE_I*
 *DE________________
                    o Print the block contents (Ctrl-K P).


               When searching and replacing, the search can be restricted to the block contents.
               6.5.3        Setting  bookmarks

               The IDE provides a feature which allows to set a bookmark at the current cursor position.
               Later, the cursor can be returned to this position by pressing a keyboard shortcut.

               Up  to  9  bookmarks  per  source  file  can  be  set  up,  they  are  set  by  Ctrl-K  <Number>
               (where  number  is  the  number  of  the  mark).   To  go  to  a  previously  set  bookmark,  press
               Ctrl-Q <Number>.

Remark:          Currently,  the  bookmarks  are  not  stored  if  the  IDE  is  left.   This  may  change  in  future
               implementations of the IDE.
               6.5.4        Jumping  to  a  source  line

               It is possible to go directly to a specific source line.  To do this, open the goto line dialog via
               the "Search_Goto line" menu.

               In the dialog that appears,  the line-number the IDE should jump to can be entered.  The
               goto line dialog is shown in figure (6.4 ).



                                                        Figure 6.4:  The goto line dialog.


               6.5.5        Syntax  highlighting

               The IDE is capable of syntax highlighting, i.e.  the color of certain Pascal elements can be
               set.  As text is entered in an editor window, the IDE will try to recognise the elements, and
               set the color of the text accordingly.

               The syntax highlighting can be customized in the colors preferences dialog, using the menu
               option   ptions_Environment_Colors".   In  the  colors  dialog,  the  group  "Syntax"
               must be selected.  The item list will then display the various syntactical elements that can
               be colored:


               Whitespace          The empty text between words.  Remark that for whitespace, only the back-
                       ground color will be used.

               Comments           All styles of comments in Free Pascal.

               Reserved words             All reserved words of Free Pascal.  (see also Reference guide       ).

               Strings      Constant string expressions.



                                                                                47

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
Numbers         Numbers in decimal notation.

Hex numbers           Numbers in hexadecimal notation.

Assembler        Any assembler blocks.

Symbols       Recognised symbols (variables, types)

Directives       Compiler directives.

Tabs    Tab characters in the source can be given a different color than other whitespace.


The editor uses some default settings, but experimentation is the best way to find a fitting
color scheme.  A good color scheme helps detecting errors in sources, since errors will result
in wrong syntax highlighting.
6.5.6        Code  Completion

Code  completion  means  the  editor  will  try  to  guess  the  text  as  it  is  being  typed.  It  does
this by checking what text is typed, and as soon as the typed text can be used to identify
a keyword in a list of keywords, the keyword will be presented in a small colored box under
the typed text.  Pressing the Enter key will complete the word in the text.

There is no code completion yet for filling in function arguments, choosing object methods
as in e.g.  Delphi.

Code completion can be customized in the Code completion dialog, reachable through the
menu  option   ptions_Preferences_Codecompletion".   The  list  of  keywords  that
can  be  completed  can  be  maintained  here.  The  code  completion  dialog  is  shown  in  figure
(6.5 ).



                                    Figure 6.5:  The code completion dialog.


The dialog shows the currently defined keywords that will be completed in alphabetical order.
The following buttons are available:


Ok    Saves all changes and closes the dialog.
                                                                 48

               __________________________________________________________________________________________________CHAPTER_6.___THE_I*
 *DE________________
               Edit    Pops up a dialog that allows to edit the currently highlighted keyword.

               New     Pops up a dialog that allows to enter a new keyword which will be added to the list.

               Delete     Deletes the currently highlighted keyword from the list

               Cancel      Discards all changes and closes the dialog.


               All keywords are saved and are available the next time the IDE is started.  Duplicate names
               are  not  allowed.  If  an  attempt  is  made  to  add  a  duplicate  name  to  the  list,  an  error  will
               follow.
               6.5.7        Code  Templates

               Code  templates  are  a  way  to  insert  large  pieces  of  code  at  once.   Each  code  templates  is
               identified by a unique name.  This name can be used to insert the associated piece of code
               in the text.

               For example, the name ifthen could be associated to the following piece of code:


               If  |  Then
                   begin
                   end


               A code template can be inserted by typing its name, and pressing Ctrl-J when the cursor
               is positioned right after the template name.

               If there is no template name before the cursor, a dialog will pop up to allow selection of a
               template.

               If a vertical bar (_) is present in the code template, the cursor is positioned on it, and the
               vertical bar is deleted.  In the above example, the cursor would be positioned between the
               if and then, ready to type an expression.

               Code  templates  can  be  added  and  edited  in  the  code  templates  dialog,  reachable  via  the
               menu option  ptions_Preferences_Codetemplates".  The code templates dialog is
               shown in figure (6.6 ).

               The top listbox in the code templates dialog shows the names of all known templates.  The
               bottom  half  of  the  dialog  shows  the  text  associated  with  the  currently  highlighted  code
               template.  The following buttons are available:


               Ok    Saves all changes and closes the dialog.

               Edit     Pops up a dialog that allows to edit the currently highlighted code template.  Both the
                       name and text can be edited.

               New      Pops up a dialog that allows to enter a new code template which will be added to the
                       list.  A name must be entered for the new template.

               Delete      Deletes the currently highlighted code template from the list

               Cancel      Discards all changes and closes the dialog.


               All templates are saved and are available the next time the IDE is started.

Remark:         Duplicates are not allowed.  If an attempt is made to add a duplicate name to the list, an
               error will occur.


                                                                                49

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___

                                    Figure 6.6:  The code templates dialog.



6.6         Searching  and  replacing


The IDE allows to search for text in the active editor window.  To search for text, one of the
following can be done:


    1.  Select "Search_Find" in the menu.

    2.  Press Ctrl-Q F.


After  that,  the  dialog  shown  in  figure  (6.7 )  will  pop  up,  and  the  following  options  can  be
entered



                                          Figure 6.7:  The search dialog.

                                                                 50

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
Text to find        The text to be searched for.  If a block was active when the dialog was started,
       the first line of this block is proposed.

Case sensitive         When checked, the search is case sensitive.

Whole words only              When checked, the search text must appear in the text as a complete
       word.

Direction       The direction in which the search must be conducted, starting from the specified
       origin.

Scope     Specifies if the search should be on the whole file, or just the selected text.

Origin     Specifies if the search should start from the cursor position or the start of the scope.


After the dialog has closed, the search is performed using the given options.

A search can be repeated (using the same options) in one of 2 ways:


    1.  Select "Search_Find again" from the menu.

    2.  Press Ctrl-L.


It is also possible to replace occurrences of a text with another text.  This can be done in a
similar manner to searching for a text:


    1.  Select "Search_Replace" from the menu.

    2.  Press Ctrl-Q A.


A dialog, similar to the search dialog will pop up, as shown in figure (6.8 ).



                                          Figure 6.8:  The replace dialog.



In this dialog, in addition to the things that can be filled in in the search dialog, the following
things can be entered:


New text        Text by which found text will be replaced.

Prompt on replace              Before a replacement is made, the IDE will ask for confirmation.



                                                                 51

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
If the dialog is closed with the 'OK' button, only the next occurrence of the the search text
will be replaced.  If the dialog is closed with the 'Change All' button, all occurrences of the
search text will be replaced.
6.7         The  symbol  browser


The symbol browser allows to find all occurrences of a symbol.  A symbol can be a variable,
type, procedure or constant that occurs in the program or unit sources.

To enable the symbol browser, the program or unit must be compiled with browser informa-
tion.  This can be done by setting the browser information options in the compiler options
dialog.

The IDE allows to browse several types of symbols:


procedures         Allows to quickly jump to a procedure definition or implementation.

Objects       Allows to quickly browse an object.

Modules        Allows to browse a module.

Globals       Allows to browse any global symbol.

Arbitrary symbol             Allows to browse an arbitrary symbol.


In  all  cases,  first  a  symbol  to  be  browsed  must  be  selected.  After  that,  a  browse  window
appears.  In the browse window, all locations where the symbol was encountered are shown.
Selecting a location and pressing the space bar will cause the editor to jump to that location;
the line containing the symbol will be highlighted.

If the location is in a source file that is not yet displayed, a new window will be opened with
the source file loaded.

After  the  desired  location  was  reached,  the  browser  window  can  be  closed  with  the  usual
commands.

The behaviour of the browser can be customized with the browser options dialog, using the
 ptions_Browser" menu.  The browser options dialog looks like figure (6.9 ).

The following options can be set in the browser options dialog:


Symbols        Here the types of symbols displayed in the browser can be selected:

         Labels     labels are shown.

         Constants       Constants are shown.

         Types     Types are shown.

         Variables      Variables are shown.

         Procedures        Procedures are shown.

         Inherited

Sub-browsing           Specifies  what  the  browser  should  do  when  displaying  the  members  of  a
        complex symbol such as a record or class:

         New browser          The members are shown in a new browser window.

         Replace current           The contents of the current window are replaced with the members
               of the selected complex symbol.

Preferred pane           Specifies what pane is shown in the browser when it is initially opened:



                                                                 52

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___

                                    Figure 6.9:  The browser options dialog.

        scope

        Reference

Display      Determines how the browser should display the symbols:

        Qualified symbols

        Sort always        sorts the symbols in the browser window.
6.8         Running  programs


A compiled program can be run straight from the IDE. This can be done in one of several
ways:


    1.  select the R n_Run" menu, or

    2.  press Ctrl-F9.


If command-line parameters should be passed to the program, then these can be set through
the R n_Parameters" menu.  The program parameters dialog looks like figure (6.10  ).



                                Figure 6.10:  The program parameters dialog.



Once the program started, it will continue to run, until


    1.  the program quits normally,



                                                                 53

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
    2.  an error happens,

    3.  a breakpoint is encountered or

    4.  the program is reset by the user.


The last alternative is only possible if the program is compiled with debug information.

Alternatively,  it  is  possible  to  position  the  cursor  somewhere  in  a  source  file,  and  run  the
program till the execution reaches the source-line where the cursor is located.  This can be
done by


    1.  selecting R n_Goto Cursor" in the menu,

    2.  pressing F4.


Again, this is only possible if the program was compiled with debug information.

The program can also executed line by line.  Pressing  F8 will execute the next line of the
program.   If  the  program  wasn't  started  yet,  it  is  started.   Repeatedly  pressing  F8  will
execute  line  by  line  of  the  program,  and  the  IDE  will  show  the  line  to  be  executed  in  an
editor window.  If somewhere in the code a call occurs to a subroutine, then pressing F8 will
cause the whole routine to be executed before control returns to the IDE. If the code of the
subroutine should be stepped through as well,  then F7 should be used instead.  Using  F7
will cause the IDE to execute line by line of any subroutine that is encountered.

If a subroutine is being stepped through, then the R n_Until return" menu will execute
the program till the current subroutine ends.

If the program should be stopped before it quits by itself, then this can be done by


    1.  selecting R n_Program reset" from the menu, or

    2.  pressing Ctrl-F2.


The running program will then be aborted.
6.9         Debugging  programs


To  debug  a  program,  it  must  be  compiled  with  debug  information.  Compiling  a  program
with debug information allows to:


    1.  Execute the program line by line.

    2.  Run the program till a certain point (a breakpoint)

    3.  Inspect the contents of variables or memory locations while the program is running.
6.9.1        Using  breakpoints

Breakpoints will cause a running program to stop when the execution reaches the line where
the breakpoint was set.  At that moment, control is returned to the IDE, and it is possible
to continue execution.

To set a breakpoint on the current source line, use the "Debug_Breakpoint" menu entry,
or press Ctrl-F8.

A  list  of  current  breakpoints  can  be  obtained  through  the  "Debug_Breakpoint  list"
menu.  The breakpoint list window is shown in figure (6.11  ).

In the breakpoint list window, the following things can be done:



                                                                 54

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___

                                   Figure 6.11:  The breakpoint list window
New     Shows the breakpoint property dialog where the properties for a new breakpoint can
       be entered.

Edit    Shows the breakpoint property dialog where the properties of the highlighted break-
       point can be changed.

Delete     Deletes the highlighted breakpoint.


The dialog can be closed with the 'Close' button.  The breakpoint properties dialog is shown
in figure (6.12  )



                                Figure 6.12:  The breakpoint properties dialog


The following properties can be set:


type     function      function  breakpoint.   The  program  will  stop  when  the  function  with  the
              given name is reached.

        file-line   Source line breakpoint.  The program will stop when the source file with given
              name and line is reached;

                                                                 55

               __________________________________________________________________________________________________CHAPTER_6.___THE_I*
 *DE________________
                       watch     Expression breakpoint.  An expression may be entered, and the program will
                             stop as soon as the expression changes.

                       awatch      (access watch) Expression breakpoint.  An expression that references a mem-
                             ory location may be entered, and the program will stop as soon as the memory
                             indicated by the expression is accessed.

                       rwatch      (read  watch)  Expression  breakpoint.  An  expression  that  references  a  mem-
                             ory location may be entered, and the program will stop as soon as the memory
                             indicated by the expression is read.

               name      Name of the function or file where to stop.

               line   Line number in the file where to stop.  Only for breakpoints of type file-line.

               Conditions        Here an expression can be entered which must evaluate True for the program
                      to  stop  at  the  breakpoint.  The  expressions  that  can  be  entered  must  be  valid  GDB
                      expressions.

               Ignore count         The number of times the breakpoint will be ignored before the program stops;


Remark:


                   1.  Because the IDE uses GDB to do its debugging, it is necessary to enter all expressions
                       in uppercase on FreeBSD.

                   2.  Expressions  that  reference  memory  locations  should  be  no  longer  than  16  bytes  on
                       linux or go32v2 on an Intel processor, since the Intel processor's debug registers are
                       used to monitor these locations.

                   3.  Memory location watches will not function on Win32 unless a special patch is applied.
               6.9.2        Using  watches

               When  debugging  information  is  compiled  in  the  program,  watches  can  be  used.  Watches
               are expressions which can be evaluated by the IDE and shown in a separate window.  When
               program execution stops (e.g.  at a breakpoint) all watches will be evaluated and their current
               values will be shown.

               Setting  a  new  watch  can  be  done  with  the  "Debug_Add  watch"  menu  command  or
               by  pressing  Ctrl-F7.  When  this  is  done,  the  watch  property  dialog  appears,  and  a  new
               expression can be entered.  The watch property dialog is shown in figure (6.13  ).

               In the dialog, the expression can be entered, any possible previous value and current value
               are shown.

Remark:         Because the IDE uses GDB to do it's debugging, it is necessary to enter all expressions in
               uppercase in FreeBSD.

               A list of watches and their present value is available in the watches window, which can be
               opened  with  the  "Debug_Watches"  menu.   The  watch  list  window  is  shown  in  figure
               (6.11  ).

               Pressing  Enter  or  the  space  bar  will  show  the  watch  property  dialog  for  the  currently
               highlighted watch in the watches window.

               The list of watches is updated whenever the IDE resumes control when debugging a program.

                                                                                56

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___

                                    Figure 6.13:  The watch property dialog



                                      Figure 6.14:  The watch list window.

6.9.3        The  call  stack

The call stack helps in showing the program flow.  It shows the list of procedures that are
being called at this moment, in reverse order.  The call stack window can be shown using the
"Debug_Call  Stack" It will show the address or procedure name of all currently active
procedures with their filename and addresses.  If parameters were passed they will be shown
as well.  The call stack is shown in figure (6.15  ).

By pressing the space bar in the call stack window, the line corresponding to the call will be
highlighted in the edit window.
6.9.4        The  GDB  window

The GDB window provides direct interaction with the GDB debugger.  In it, GDB commands
can be typed as they would be typed in GDB. The response of GDB will be shown in the
window.

Some more information on using GDB can be found in section 10.2  , page 113  , but the final
reference is of course the GDB manual itself 3 .  The GDB window is shown in figure (6.16  ).
___________________________________________________3
     Available from the Free Software Foundation website.



                                                                 57

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___

                                      Figure 6.15:  The call stack window.
                                          Figure 6.16:  The GDB window



6.10          Using  Tools


The  tools  menu  provides  easy  access  to  external  tools.  It  also  has  three  pre-defined  tools
for programmers:  an ASCII table, a grep tool and a calculator.  The output of the external
tools can be accessed through this menu as well.
6.10.1         The  messages  window

The output of the external utilities is redirected by the IDE and it will be displayed in the
messages window.  The messages window is displayed automatically, if an external tool was
run.  The messages window can be also displayed manually by the selecting the menu item
Tols_Messages  r by pressing the key F11.  The messages window is shown in figure
(6.17  ).

If the output of the tool contains filenames and line numbers, the messages window can be
used to navigate the source as in a browse window:


    1.  Pressing  Enter  or  double  clicking  the  output  line  will  jump  to  the  specified  source



                                                                 58

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___

                                       Figure 6.17:  The messages window



       line and close the messages window.

    2.  Pressing the space bar will jump to the specified source line, but will leave the messages
        window open, with the focus on it.  This allows to quickly select another message line
        with the arrow keys and jump to another location in the sources.


The algorithm which extracts the file names and line numbers from the tool output is quite
sophisticated, but in some cases it may fail4 .
6.10.2         Grep

One  external  tool  in  the  Tools  menu  is  already  predefined:  a  menu  item  to  call  the  grep
utility (Tols_Grep  r Shift-F2).  Grep searches for a given string in files and returns
the lines which contain the string.  The search string can be even a regular expression.  For
this  menu  item  to  work,  the  grep  program  must  be  installed,  since  it  does  not  come  with
Free Pascal.

The messages window displayed in figure (6.17  ) in the previous section shows the output of
a typical grep session.  The messages window can be used in combination with grep to find
special occurrences in the text.

Grep supports regular expressions.  A regular expression is a string with special characters
which describe a whole class of expressions.  The command line in dos or linux have limited
support for regular expressions:  entering ls  *.pas (or dir  *.pas) to get a list of all Pascal
files in a directory.  *.pas is something similar to a regular expression.  It uses a wildcard to
describe a whole class of strings:  those which end on ".pas".  Regular expressions offer much
more:  for example [A-Z][0-9]+ describes all strings which begin with a upper case letter
followed by one or more digits.

It is outside the scope of this manual to describe regular expressions in great detail.  Users
of a linux system can get more information on grep using man  grep on the command-line.
6.10.3         The  ASCII  table

The  tools  menu  provides  also  an  ASCII  table  (Tols_Ascii  table"),  The  ASCII  table
can be used to look up ASCII codes as well as inserting characters into the window which
was active when invoking the table.  To get the ASCII code of a char move the cursor on
this char or click with the mouse on it.  To insert a char into an editor window either:


    1.  using the mouse, double click it,

    2.  using the keyboard, press Enter while the cursor is on it.


This is especially useful for pasting graphical characters in a constant string.
___________________________________________________4
     Suggestions for improvement, or better yet, patches that improve the algorithm, are always welcome.



                                                                 59

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
The  ASCII  table  remains  active  till  another  window  is  explicitly  activated,  thus  multiple
characters can be inserted at once.  The ASCII table is shown in figure (6.18  ).



                                           Figure 6.18:  The ASCII table

6.10.4         The  calculator

The calculator allows to do some quick calculations.  It is a simple calculator, since it does
not take care of operator precedence, and bracketing of operations is not (yet) supported.

The result of the calculations can be pasted into the text using the Ctrl-Enter keystroke.
The calculator dialog is shown in figure (6.19  ).

The  calculator  supports  all  basic  mathematical  operations  such  as  addition,  subtraction,
division and multiplication.  They are summarised in table (6.1 ).



                                  Table 6.1:  Advanced calculator commands

         _Operation___________________________________________________________________Button_______Key_________________
           Add two numbers                                                            +             +
           Subtract two numbers
           Multiply two numbers                                                       *             *
           Divide two numbers                                                         /             /
           Delete the last typed digit                                                <-            Backspace
           Delete the display                                                         C             C
           Change the sign                                                            +
         __Do_per_cent_calculation____________________________________________________%_____________%__________________
         __Get_result_of_operation____________________________________________________=_____________Enter______________
But also more sophisticated mathematical operations such as exponentiation and logarithms
are supported.  The available mathematical calculations are shown in table (6.2 ).

Like  many  calculators,  the  calculator  in  the  IDE  also  supports  storing  a  single  value  in
memory, and several operations can be done on this memory value.  The available operations



                                                                 60

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___

                                        Figure 6.19:  The calculator dialog



                                  Table 6.2:  Advanced calculator commands

              __Operation__________________________________________________________________Button________Key_____
                Calculate power                                                            x^y
                Calculate the inverse value                                                1/x
                Calculate the square root                                                  sqr
                Calculate the natural logarithm                                            log
              __Square_the_display_contents________________________________________________x^2___________________
                .

are listed in table (6.3 )
6.10.5         Adding  new  tools

The tools menu can be extended with any external program which is command-line oriented.
The output of such a program will be caught and displayed in the messages window.

Adding a tool to the tools menu can be done using the  ptions_Tools" menu.  This will
display the tools dialog.  The tools dialog is shown in figure (6.20  ).

In the tools dialog, the following actions are available:


New      Shows the tool properties dialog where the properties of a new tool can be entered.

Edit     Shows the tool properties dialog where the properties of the highlighted tool can be
        edited.

Delete      Removes the currently highlighted tool.

Cancel      Discards all changes and closes the dialog.
                                                                 61

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___

                                  Table 6.3:  Advanced calculator commands

              __Operation__________________________________________________________________Button________Key_____
                Add the displayed number to the memory                                     M+
                Subtract the displayed number from the memory                              M-
                Move the memory contents to the display                                    M->
                Move the display contents to the memory                                    M<-
              __Exchange_display_and_memory_contents_______________________________________M<->__________________

                                  Figure 6.20:  The tools configuration dialog



OK     Saves all changes and closes the dialog.


The definitions of the tools are written in the desktop configuration file, so unless auto-saving
of the desktop file is enabled, the desktop file should be saved explicitly after the dialog is
closed.
6.10.6         Meta  parameters

When specifying the command line for the called tool, meta parameters can be used.  Meta
parameters  are  variables  and  and  they  are  replaced  by  their  contents  before  passing  the
command line to the tool.


$CAP       Captures the output of the tool.

$CAP__MSG()             Captures the output of the tool and puts it in the messages window.

$CAP__EDIT()             Captures the output of the tool and puts it in a separate editor window.

$COL       Replaced  by  the  column  of  the  cursor  in  the  active  editor  window.  If  there  is  no
        active window or the active window is a dialog, then it is replaced by 0.

$CONFIG           Replaced by the complete filename of the current configuration file.

                                                                 62

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
$DIR()       Replaced by the full directory of the filename argument, including trailing directory
       separator.  e.g.


           $DIR('d:\data\myfile.pas')


       would return d:\data\.

$DRIVE()          Replaced by the drive letter of the filename argument.  e.g.


           $DRIVE('d:\data\myfile.pas')


       would return d:.

$EDNAME            Replaced by the complete file name of the file in the active edit window.  If
       there is no active edit window, this is an empty string.

$EXENAME              Replaced by the executable name that would be created if the make com-
       mand was used.  (i.e.  from the 'Primary File' setting or the active edit window).

$EXT()       Replaced by the extension of the filename argument.  The extension includes the
       dot.  e.g.


           $EXT('d:\data\myfile.pas')


       would return .pas.

$LINE       Replaced  by  the  line  number  of  the  cursor  in  the  active  edit  window.  If  no  edit
       window is present or active, this is 0.

$NAME()          Replaced by the name part (excluding extension and dot) of the filename argu-
       ment.  e.g.


           $NAME('d:\data\myfile.pas')


       would return myfile.

$NAMEEXT()               Replaced by the name and extension part of the filename argument.  e.g.


           $NAMEEXT('d:\data\myfile.pas')


       would return myfile.pas.

$NOSWAP            Does nothing in the IDE, it is provided for compatibility with Turbo Pascal
       only.

$PROMPT()             Prompt displays a dialog bow that allows editing of all arguments that come
       after  it.   Arguments  that  appear  before  the  $PROMPT  keyword  are  not  presented  for
       editing.

       If a (optional) filename argument is present, $PROMPT() will load a dialog description
       from the filename argument, e.g.


       $PROMPT(cvsco.tdf)


       would parse the file cvsco.tdf, construct a dialog with it and display it.  After the dialog
       closed, the information entered by the user is used to construct the tool command line.

       See section 6.10.7  , page 64  for more information on how to create a dialog description.



                                                                 63

               __________________________________________________________________________________________________CHAPTER_6.___THE_I*
 *DE________________
               $SAVE       Before executing the command, the active editor window is saved, even if it is not
                      modified.

               $SAVE__ALL           Before  executing  the  command,  all  unsaved  editor  files  are  saved  without
                      prompting.

               $SAVE__CUR            Before executing the command the contents of the active editor window are
                      saved without prompting if they are modified.

               $SAVE__PROMPT                 Before executing the command,  a dialog is displayed asking whether
                      any unsaved files should be saved before executing the command.

               $WRITEMSG()                Writes the parsed tool output information to a file with name as in the
                      argument.
               6.10.7         Building  a  command  line  dialog  box

               When  defining  a  tool,  it  is  possible  to  show  a  dialog  to  the  user,  asking  for  additional
               arguments,  using the $PROMPT(filename) command-macro.  Free Pascal comes with some
               dialogs, such as a 'grep' dialog, a 'cvs checkout' dialog and a 'cvs check in' dialog.  The files
               for these dialogs are in the binary directory and have an extension .tdf.

               In  this  section,  the  file  format  for  the  dialog  description  file  is  explained.   The  format  of
               this  file  resembles  a  windows  .INI  file,  where  each  section  in  the  file  describes  an  element
               (or control) in the dialog.  An OK and an Cancel button will be added to the bottom of the
               dialog, so these should not be specified in the dialog definition.

               A special section is the Main section.  It describes how the result of the dialog will be passed
               on the command-line, and the total size of the dialog.

Remark:         Keywords that contain a string value, should have the string value enclosed in double quotes
               as in


               Title="Dialog  title"


               The Main section should contain the following keywords:


               Title    The title of the dialog.  This will appear in the frame title of the dialog.  The string
                       should be enclosed in quotes.

               Size    The size of the dialog, this is formatted as (Cols,Rows), so


                       Size=(59,9)


                       means the dialog is 59 characters wide, and 9 lines high.  This size does not include the
                       border of the dialog.

               CommandLine              specifies how the command-line will be passed to the program, based on
                       the entries made in the dialog.  The text typed here will be passed on after replacing
                       some control placeholders with their values.

                       A  control  placeholder  is  the  name  of  some  control  in  the  dialog,  enclosed  in  percent
                       (%) characters.  The name of the control will be replaced with the text, associated with
                       the control.  Consider the following example:


                       CommandLine="-n  %l%  %v%  %i%  %w%  %searchstr%  %filemask%"


                       Here the values associated with the controls named l,  i,  v,  w and searchstr and
                       filemask will be inserted in the command-line string.



                                                                                64

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
Default      The name of the control that is the default control, i.e.  the control that has the
       focus when the dialog is opened.


The following is an example of a valid main section:


[Main]
Title="GNU  Grep"
Size=(56,9)
CommandLine="-n  %l%  %v%  %i%  %w%  %searchstr%  %filemask%"
Default="searchstr"


After the Main section, a section must be specified for each control that should appear on the
dialog.  Each section has the name of the control it describes, as in the following example:


[CaseSensitive]
Type=CheckBox
Name="~C~ase  sensitive"
Origin=(2,6)
Size=(25,1)
Default=On
On="-i"


Each control section must have at least the following keywords associated with it:


Type     The type of control.  Possible values are:

        Label     A plain text label which will be shown on the dialog.  A control can be linked
              to this label, so it will be focused when the user presses the highlighted letter in
              the label caption (if any).

        InputLine        An edit field where a text can be entered.

        CheckBox         A Checkbox which can be in a on or off state.

Origin     Specifies where the control should be located in the dialog.  The origin is specified as
       (left,Top) and the top-left corned of the dialog has coordinate (1,1) (not counting
       the frame).

Size   Specifies the size of the control, which should be specified as (Cols,Rows).


Each control has some specific keywords associated with it; they will be described below.

A label (Type=Label) has the following extra keywords associated with it:


Text    the text displayed in the label.  If one of the letters should be highlighted so it can be
       used as a shortcut, then it should be enclosed in tilde characters (~), e.g.  in


       Text="~T~ext  to  find"


       The T will be highlighted.

Link    here the name of a control in the dialog may be specified.  If specified,  pressing the
       label's  highlighted  letter  in  combination  with  the  Alt  key  will  put  the  focus  on  the
       control specified here.


A  label  does  not  contribute  to  the  text  of  the  command-line,  it  is  for  informational  and
navigational purposes only.  The following is an example of a label description section:



                                                                 65

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
[label2]
Type=Label
Origin=(2,3)
Size=(22,1)
Text="File  ~m~ask"
Link="filemask"


An edit control (Type=InputLine) allows to enter arbitrary text.  The text of the edit control
will be pasted in the command-line if it is referenced there.  The following keyword can be
specified in a inputline control section:


Value     here a standard value (text) for the edit control can be specified.  This value will be
       filled in when the dialog appears.


The following is an example of a input line section:


[filemask]
Type=InputLine
Origin=(2,4)
Size=(22,1)
Value="*.pas  *.pp  *.inc"


A combo-box control (Type=CheckBox) presents a checkbox which can be in one of two states,
on or off.  With each of these states, a value can be associated which will be passed on to
the command-line.  The following keywords can appear in a checkbox type section:


Name      the text that appears after the checkbox.  If there is a highlighted letter in it, this
       letter can be used to set or unset the checkbox using the Alt-letter combination.

Default      specifies whether the checkbox is checked or not when the dialog appears (values
       on or off)

On    the text associated with this checkbox if it is in the checked state.

Off   the text associated with this checkbox if it is in the unchecked state.


The following is a example of a valid checkbox description:


[i]
Type=CheckBox
Name="~C~ase  sensitive"
Origin=(2,6)
Size=(25,1)
Default=On
On="-i"


If the checkbox is checked, then the value -i will be added on the command-line of the tool.
If it is unchecked, no value will be added.
6.11          Pro ject  management  and  compiler  options


Project  management  in  Pascal  is  much  easier  than  with  C.  The  compiler  knows  from  the
source which units, sources etc.  it needs.  So the Free Pascal IDE does not need a full featured
project manager like some C development environments offer,  nevertheless there are some
settings in the IDE which apply to projects.



                                                                 66

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
6.11.1         The  primary  file

Without  a  primary  file  the  IDE  compiles/runs  the  source  of  the  active  window  when  a
program is started.  If a primary file is specified, the IDE compiles/runs always this source,
even if another source window is active.  With the menu item C mpile_Primary file..."
a  file  dialog  can  be  opened  where  the  primary  file  can  be  selected.   Only  the  menu  item
C mpile_Compile" compiles still the active window, this is useful if a large project is
being edited, and only the syntax of the current source should be checked.

The  menu  item  C mpiler_Clear  primary  file"  restores  the  default  behaviour  of  the
IDE, i.e.  the 'compile' and 'run' commands apply to the active window.
6.11.2         The  directory  dialog

In the directory dialog, the directories can be specified where the compiler should look for
units,  libraries,  object files.  It also says where the output files should be stored.  Multiple
directories (except for the output directory) can be entered, separated by semicolons.  The
directories dialog is shown in figure (6.21  ).



                              Figure 6.21:  The directories configuration dialog
The following directories can be specified:


EXE & PPU directories                   Specifies where the compiled units and executables will go.  (-FE
        (see page 5.1.3  ) on the command line.)

Object directories            Specifies where the compiler looks for external object files.  (-Fo (see
        page 5.1.3  ) on the command line.)

Library directories            Specifies where the compiler (more exactly,  the linker) looks for ex-
        ternal libraries.  (-Fl (see page 5.1.3  ) on the command line.)

Include directories            Specifies where the compiler will look for include files, included with
        the {$i  } directive.  (-Fi (see page 5.1.3  ) or -I (see page 5.1.3  ) on the command line.)

Unit directories           Specifies where the compiler will look for compiled units.  The compiler
        always looks first in the current directory, and also in some standard directories.  (-Fu
        (see page 5.1.3  ) on the command line.)
6.11.3         The  target  operating  system

The menu item C mpile_Target  llows to specify the target operating system for which
the sources will be compiled.  Changing the target doesn't affect any compiler switches or



                                                                 67

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
directories.  It does affect some defines defined by the compiler.  The settings here correspond
to  the  option  -T  (see  page  5.1.4  )  on  the  command-line.   The  compilation  target  dialog  is
shown in figure (6.22  ).



                                  Figure 6.22:  The compilation target dialog



The following targets can be set:


Dos (go32v1)          This  switch  will  dissapear  in  time  as  this  target  is  no  longer  being  main-
       tained.

Dos (go32v2)          Compile for dos, using version 2 of the Go32 extender.

FreeBSD        Compile for FreeBSD.

Linux     Compile for linux.

OS/2     Compile for OS/2 (using the EMX extender)

Win32      Compile for windows 32 bit.


The currently selected target operating system is shown in the menu item in the C mpile"
menu.  Standard this should be the operating system for which the IDE was compiled.
6.11.4         Compiler  options

The  menu   ptions_Compiler"  allows  to  set  other  options  that  affect  the  compilers
behaviour.  When this menu item is chosen, a dialog pops up that displays several tabs.

There are 5 tabs:


Syntax       Here options can be set that affect the various syntax aspects of the code.  They
        correspond mostly to the -S option on the command line (section 5.1.5  , page 28 ).

Code generation             These  options  control  the  generated  code;  they  are  mostly  concerned
        with the -C and -X command-line options.
                                                                 68

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
Verbose       These  set  the  verbosity  of  the  compiler  when  compiling.   The  messages  of  the
       compiler are shown in the compiler messages window (can be called with F12).

Browser       options concerning the generated browser information.  Browser information needs
       to be generated for the symbol browser to work.

Assembler        Options concerning the reading of assembler blocks (-R on the command line)
       and the generated assembler (-A on the command line)


Under  the  tab  pages,  the  Conditional  defines  entry  box  is  visible;  here  symbols  to  define
can be entered.  The symbols should be separated with semicolons.  The syntax tab of the
compiler options dialog is shown in figure (6.23  ).



                                      Figure 6.23:  The syntax options tab

In this dialog, the following options can be set:


Delphi 2 extensions on               Enables  the  use  of  classes  and  exceptions  (-Sd  (see  page  5.1.5  )
       on the command-line).

C-like operators           Allows the use of some extended operators such as +=,  -= etc.  (-Sc (see
       page 5.1.5  ) on the command-line).

Stop after first error            when checked, the compiler stops after the first error.  Normally the
       compiler continues compiling till a fatal error is reached.  (-Se (see page 5.1.5  ) on the
       command-line)

Allow label and goto              Allow the use of label declarations and goto statements (-Sg (see
       page 5.1.5  ) on the command line).

C++ styled inline             allows the use of inlined functions (-Sc (see page 5.1.5  ) on the command-
       line).

TP/BP 7.0 compatibility                  Try to be more Turbo Pascal compatible (-So (see page 5.1.5  )
       on the command-line).

Delphi compatibility              try to be more Delphicompatible (-Sd (see page 5.1.5  ) on the command-
       line).

Allow STATIC in objects                  Allow the Static modifier for object methods (-St (see page
       5.1.5  ) on the command-line)



                                                                 69

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
Strict var-strings          Not used.

Extended syntax             Not used.

Allow MMX operations                   Allow MMX operations.


The code generation tab of the compiler options dialog is shown in figure (6.24  ).



                                Figure 6.24:  The code generation options tab

In this dialog, the following options can be set:


Run-time checks            Controls what run-time checking code is generated.  If such a check fails,
       a run-time error is generated.  the following checking code can be generated:

        Range checking           Code that checks the results of enumeration and subset type oper-
              ations is generated (-Cr (see page 5.1.4  ) command-line option)

        Stack checking          Code that checks whether the stack limit is not reached is generated
              (-Cs (see page 5.1.4  ) command-line option)

        I/O checking         Code that checks the result of IO operations is generated.  (-Ci (see
              page 5.1.4  ) command-line option).

        Integer overflow checking                The result of integer operations is checked (-Co (see page
              5.1.4  ) command-line option)

Target processor           Set the target process for optimizations.  The compiler can use different
       optimizations for different processors.  This corresponds to the Op option.

        i386/i486       Code is optimized for less than Pentium processors.

        Pentium/pentiumMMX                     Code is optimized for Pentium processors.

        PPro/PII/c6x86/K6                Code is optimized for Pentium pro and higher processors.

Optimizations          What optimizations should be used when compiling:

        Generate faster code              Corresponds to the -OG command-line option.

        Generate smaller code               Corresponds to the -Og command-line option.

        Use register variables             Corresponds to the -Or command-line option.

        Uncertain optimizations                Corresponds to the -Ou command-line option.
                                                                 70

               __________________________________________________________________________________________________CHAPTER_6.___THE_I*
 *DE________________
                       Level 1 optimizations              Corresponds to the O1 command-line option.

                       Level 2 optimizations              Corresponds to the O1 command-line option.


               More information on these switches can be found in section 5.1.4  , page 24 .  The verbose tab
               of the compiler options dialog is shown in figure (6.25  ).



                                                   Figure 6.25:  The verbosity options tab

               In this dialog, the following verbosity options (-v (see page 5.1.2  ) on the command-line) can
               be set:


               Warnings        Generate warnings, corresponds to -vw on the command-line.

               Notes     Generate notes, corresponds to -vn on the command-line.

               Hints     Generate hints, corresponds to -vh on the command-line.

               General info         Generate general information, corresponds to -vi on the command-line.

               User,tried info         Generate information on used and tried files.  Corresponds to -vut on the
                      command-line.

               All   Switch on full verbosity.  Corresponds to -va on the command-line.

               Show all procedure if error                 If an error using overloaded procedure occurs, show all pro-
                      cedures.  Corresponds to -vb on the command-line.


               The browser tab of the compiler options dialog is shown in figure (6.26  ).

               In this dialog, the browser options can be set:


               No browser         (default) no browser information is generated by the compiler.

               Only global browser              Browser information is generated for global symbols only, i.e.  sym-
                      bols defined not in a procedure or function (-b on the command-line)

               Local and global browser                 Browser information is generated for all symbols, i.e.  also for
                      symbols that are defined in procedures or functions (-bl on the command-line)


Remark:         If no browser information is generated, the symbol browser of the IDE will not work.

               The assembler tab of the compiler options dialog is shown in figure (6.27  ).

               In this dialog, the assembler reader and writer options can be set:



                                                                                71

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___

                                     Figure 6.26:  The browser options tab


                                    Figure 6.27:  The assembler options tab


Assembler reader             This allows to set the style of the assembler blocks in the sources:

        Direct assembler           The assembler blocks are copied as-is to the output (-Rdirect on
              the command-line).

        AT&T assembler              The  assembler  is  written  in  AT&T  style  assembler  (-Ratt  on  the
              command-line).

        Intel style assembler            The assembler is written in Intel style assembler blocks (-Rintel
              on the command-line).

       remark that this option is global, but locally the assembler style can be changed with
       compiler directives.

Assembler info           When writing assembler files, this option decides which extra information
       is written to the assembler file in comments:

        List source       The source lines are written to the assembler files together with the gen-
              erated assembler (-al on the command line).

                                                                 72

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
        List register allocation             The  compilers  internal  register  allocation/deallocation  in-
              formation is written to the assembler file (-ar on the command-line).

        List temp allocation             The  temporary  register  allocation/deallocation  is  written  to
              the assembler file.  (-at on the command-line).

       The latter two of these options are mainly useful for debugging the compiler itself, it
       should be rarely necessary to use these.

Assembler output             This option tells the compiler what assembler output should be gener-
       ated.

        Use default output             This depends on the target.

        Use GNU as           assemble using gnu as (-Aas on the command-line).

        Use NASM coff             produce NASM coff assembler (go32v2, -Anasmcoff on the command-
              line)

        Use NASM elf            produce NASM elf assembler (linux, -Anasmelf on the command-
              line).

        Use NASM obj             produce NASM obj assembler (-Anasmobj on the command-line).

        Use MASM            produce MASM (Microsoft assembler) assembler (-Amasm on the command-
              line).

        Use TASM          produce TASM (Turbo Assembler) assembler (-Atasm on the command-
              line).

        Use coff      Write binary coff files directly using the internal assembler (go32v2, -Acoff
              on the command-line).

        Use pecoff       Write binary pecoff files files directly using the internal writer.  (Win32)
6.11.5         Linker  options

The linker options can be set in the menu  ptions_Linker".  It allows to determine how
libraries and units are linked, and how the linker should be called.  The linker options dialog
is shown in figure (6.28  ).



                                     Figure 6.28:  The linker options dialog


The following options can be set:


Call linker after          If this option is set then a script is written which calls the linker.  This
        corresponds to the -s (see page 5.1.4  ) on the command-line.

Preferred library type               With this option, the type of library to be linked in can be set:

         Target default         This depends on the platform.
                                                                 73

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
        Dynamic libraries            Tries to link in units in dynamical libraries.  (option -XD on the
              command-line)

        Static libraries        Tries to link in units in statical libraries.  (option -XS on the command-
              line)

        Smart libraries          Tries  to  link  in  units  in  smartlinked  libraries.  (option  -XX  on  the
              command-line)
6.11.6         Memory  sizes

The memory sizes dialog (reachable via  ptions_Memory  sizes") allows to enter the
memory sizes for the project.  The memory sizes dialog is shown in figure (6.29  ).



                                     Figure 6.29:  The memory sizes dialog



The following sizes can be entered:


Stack size       Sets the size of the stack in bytes; (option -Cs on the command line).  This size
        may be ignored on some systems.

Heap size        Sets the size of the heap in bytes; (option -Ch on the command-line).  Note that
        the heap grows dynamically as much as the OS allows.
6.11.7         Debug  options

In the debug options dialog some options for inclusion of debug information in the binary
can be set; it is also possible to add additional compiler options in this dialog.  The debug
options dialog is shown in figure (6.30  ).

The following options can be set:


Debugging information                 tells the compiler which debug information should be compiled
        in.  One of following options can be chosen:

         Strip all debug symbols from executable                         Will  strip  all  debug  nd  symbol  infor-
               mation from the binary.  (option -Xs on the command-line).

         Generate debug symbol information                         include debug information in the binary (op-
               tion -g on the command-line).  Please note that no debug information for units
               in the Run-Time Library will be included, unless a version of the RTL compiled
               with debug information is available.  Only units specific to the current project will
               have debug information included.
                                                                 74

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___

                                     Figure 6.30:  The debug options dialog


        Generate also backtrace lines information                          Will compile with debug information,
              and will additionally include the lineinfo unit in the binary, so in case of an error
              the  backtrace  will  contain  the  filenames  and  linenumbers  of  procedures  in  the
              call-stack.  (Option -gl on the command-line)

Profiling switches           Tells  the  compiler  whether  or  not  profile  code  should  be  included  in
       the binary.

        No profile information              Has no effect, as it is the default.

        Generate Profile code for gprof                   If checked, profiling code is included in the binary
              (option -p on the command-line).

Addition compiler args                Here arbitrary options can be entered as they would be entered
       on the command-line, they will be passed on to the compiler as typed here.

Debuggee redirection               If checked, an attempt will be made to redirect the output of the
       program being debugged to another window (terminal).
6.11.8         The  switches  mode

The IDE allows to save a set of compiler settings under a common name; it provides 3 names
under which the switches can be saved:


Normal        For normal (fast) compilation.

Debug       For  debugging;  intended  to  set  most  debug  switches  on.   Also  useful  for  setting
        conditional defines that e.g.  allow to include some debug code.

release     For a compile of the program as it should be released, debug information should be
        off, the binary should be stripped, and optimizations should be used.


Selecting one of these modes will load the compiler options as they were saved the last time
the selected mode was active, i.e.  it doesn't specifically set or unset options.

                                                                 75

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
When setting and saving compiler options, be sure to select the correct switch mode first; it
makes little sense to set debug options while the release switch is active.  The switches mode
dialog is shown in figure (6.31  ).



                                     Figure 6.31:  The switches mode dialog



6.12          Customizing  the  IDE


The  IDE  is  configurable  in  a  wide  range:  Colors  can  be  changed,  screen  resolution.   The
configuration setting can reached via the sub-menu Environment in the Options menu.
6.12.1         Preferences

The preferences dialog is called by the menu item  ptions_Environment_Preferences".
The preferences dialog is shown in figure (6.32  ).



                                       Figure 6.32:  The preferences dialog

Video modes           The drop down list at the top of the dialog allows to select a video mode.
        The available video modes depend on the system on which the IDE is running.



                                                                 76

        __________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____*
 *___________
Remark:

                   1.  The video mode must be selected by pressing space or clicking on it.  If the drop
                       down  list  is  opened  while  leaving  the  dialog,  the  new  video  mode  will  not  be
                       applied.

                   2.  For the dos version of the IDE, the following should be noted:  When using VESA
                       modes,  the display refresh rate may be very low.  On older graphics card (1998
                       and before), it is possible to use the UniVBE driver of SciTech5

        Desktop File          Specifies where the desktop file is saved:  the current directory, or the direc-
                tory where the config file was found;

        Auto save         Here it is possible to set which files are saved when a program is run or when
                the IDE is exited:

                 Editor files      The contents of all open edit windows will be saved.

                 Environment          The current environment settings will be saved

                 Desktop       The desktop file with all desktop settings (open windows, history lists, break-
                       points etc.)  will be saved.

        Options       Some special behaviour of the IDE can be specified here:

                 Auto track source

                 Close on go to source              When checked, the messages window is closed when the 'go
                       to source line' action is executed.

                 Change dir on open              When  a  file  is  opened,  the  directory  of  that  file  is  made  the
                       current working directory.
        6.12.2         The  desktop

        The  desktop  preferences  dialog  allows  to  specify  what  elements  of  the  desktop  are  saved
        across sessions, i.e.  they are saved when the IDE is left, and they are again restored when
        the IDE is started the next time.  They are saved in a file fp.dsk.  The desktop preferences
        dialog is shown in figure (6.33  ).

        The following elements can be saved and restored across IDE sessions:


        History lists        Most entry boxes have a history list where previous entries are saved and can
                be selected.  When this option is saved, these entries are saved in the desktop file.  On
                by default.

        Clipboard content             When checked, the contents of the clipboard is also saved to disk.  Off
                by default.

        Watch expressions              When checked, all watch expressions are saved in the desktop file.  Off
                by default.

        Breakpoints          When checked, all break points with their properties are saved in the desktop
                file.  Off by default.

        Open windows             When  checked,  the  list  of  files  in  open  editor  windows  is  saved  in  the
                desktop file,  and the windows will be restored the next time the IDE is run.  On by
        ________default.___________________________________
            5It can be downloaded from http://www.informatik.fh-muenchen.de/ ifw98223/vbehz.htm


                                                                         77

               __________________________________________________________________________________________________CHAPTER_6.___THE_I*
 *DE________________

                                                Figure 6.33:  The desktop preferences dialog


               Symbol information              When checked,  the information for the symbol browser is saved in
                      the desktop file.  Off by default.

               CodeComplete wordlist                 When checked,  the list of code-completion words is saved.  On
                      by default.

               CodeTemplates            When checked, the defined code-templates are saved.  On by default.


Remark:         The format of the desktop file changes between editor versions,  so when installing a new
               version, it may be necessary to delete the fp.dsk files wherever the IDE searches for them.
               6.12.3         The  Editor

               Several aspects of the editor window behaviour can be set in this dialog.  The editor prefer-
               ences dialog is shown in figure (6.34  ).

               The following elements can be set in the editor preferences dialog:


               Create backup files             Whenever an editor file is saved, a backup is made of the old file.  On
                       by default.

               Auto indent mode               Smart indenting is on.  This means that pressing Enter will position
                       the cursor on the next line in the same column where text starts on the current line.
                       On by default.

               Use tab characters             When the tab key is pressed, use a tab character.  Normally, when the
                       tab  key  is  pressed,  spaces  are  inserted.  When  this  option  is  checked,  tab  characters
                       will be inserted instead.  Off by default.

               Backspace unindents                Pressing  the  Bksp  key  will  unindent  if  the  beginning  of  the  text
                       on the current line is reached, instead of deleting just the previous character.  On by
                       default.
                                                                                78

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___

                                  Figure 6.34:  The editor preferences dialog



Persistent blocks           When a selection is made, and the cursor is moved, the selection is not
       destroyed, i.e.  the selected block stays selected.  On by default.

Syntax highlight           Use syntax highlighting on the files that have an extension which appears
       in the list of highlight extensions.  On by default.

Block insert cursor            The insert cursor is a block instead of an underscore character.  By
       default  the  overwrite  cursor  is  a  block.  This  option  reverses  that  behaviour.  Off  by
       default.

Vertical blocks         When selecting blocks over several lines, the block doesn't select the whole
       lines in the block, it selects the lines till the column on which the cursor is located.  Off
       by default.

Highlight column             When checked, the current column (i.e.  the column where the cursor
       is) is highlighted.  Off by default.

Highlight row          When checked, the current row (i.e.  the row where the cursor is) is high-
       lighted.  Off by default.

Auto closing brackets              When an opening bracket character is typed, the closing bracket
       is also inserted at once.  Off by default.

Keep trailing spaces             When saving a file, the spaces at the end of lines are stripped off.
       This behaviour disables that behaviour, i.e.  any trailing spaces are also saved to file.
       Off by default.

Codecomplete enabled                 Enable code completion.  On by default.

enable folds        ???.  Off by default.

Tab size      The number of spaces that are inserted when the Tab key is pressed.  The default
       value is 8.

Indent size       The number of spaces a block is indented when calling the block indent func-
       tion.  The default value is 2.



                                                                 79

               __________________________________________________________________________________________________CHAPTER_6.___THE_I*
 *DE________________
               Highlight extensions             When syntax highlighting is on, the list of file masks entered here
                      will be used to determine which files are highlighted.  File masks should be separated
                      with semicolon (;) characters.  The default is *.pas;*.pp;*.inc.

               File patterns needing tabs                 Some files (such as makefiles) need actual tab characters in-
                      stead of spaces.  Here a series of file masks can be entered for which tab characters will
                      always be used.  Default is make*;make*.*.


Remark:         These options will not be applied to already opened windows, only newly opened windows
               will have these options.
               6.12.4         Mouse

               The mouse options dialog is called by the menu item  ptions_Environment_Mouse".
               It allows to adjust the behaviour of the mouse as well as the sensitivity of the mouse.  The
               mouse options dialog is shown in figure (6.35  ).



                                                    Figure 6.35:  The mouse options dialog


               Mouse double click              The slider can be used to adjust the double click speed.  Fast means
                       that the time between two clicks is very short, slow means that the time between two
                       mouse clicks can be quite long.

               Reverse mouse buttons                  the behaviour of the left and right mouse buttons can be changed
                       by by checking the checkbox; this is especially useful for left-handed people.

               Ctrl+Right mouse button                    Assigns an action to a right mouse button click while holding
                       the Ctrl key pressed.

               Ctrl+Left mouse button                  Assigns an action to a left mouse button click while holding the
                       Ctrl key pressed.


               The  following  actions  can  be  assigned  to  Ctrl-right  mouse  button  or  Alt-right  mouse
               button:


               Topic search         The keyword at the mouse cursor is searched in the help index.

               Go to cursor          The program is executed until the line where the mouse cursor is located.



                                                                                80

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
Breakpoint         Set a breakpoint at the mouse cursor position.

Evaluate       Evaluate the value of the variable at the mouse cursor.

Add watch         Add the variable at the mouse cursor to the watch list.

Browse symbol            The symbol at the mouse cursor is displayed in the browser.
6.12.5         Colors

Almost all elements of the IDE such as borders input fields, buttons and so on can have their
color set in this dialog.  The dialog sets the colors for all elements at once, i.e.  it is not so
that the color of one particular button can be set.

The  syntax  highlighting  colors  for  the  editor  windows  of  the  IDE  can  also  be  set  in  this
dialog.  The colors dialog is shown in figure (6.36  ).



                                          Figure 6.36:  The colors dialog

The following elements are visible in the color dialog:


Group       Here the group to be customized is displayed; A group is a specific window or series
        of windows in the editor.  A special group is Syntax which sets the colors for syntax
        highlighting.

         Browser       Sets the colors for the symbol browser window.

         Clock     Sets the colors for the clock in the menu.

         Desktop       Sets the colors for the desktop.

         Dialogs     Sets the colors for the dialog windows.

         Editor     Sets the colors for the editor windows.

         Help    Sets the colors for the help windows.

         Menus      Sets the colors used in the menus.

         Syntax      Sets the colors used when performing syntax highlighting in the editor win-
               dows.

item     Here the item for the current group can be selected.  The foreground and background
        of this item can be set using the color selectors on the right of the dialog.



                                                                 81

               __________________________________________________________________________________________________CHAPTER_6.___THE_I*
 *DE________________
               Foreground         Sets the foreground color of the selected item.

               background         Sets the background color of the selected item.

               Sample text         This shows the colors of the selected item in a sample text.


               Setting a good color scheme is important especially for syntax highlighting; a good syntax
               highlighting scheme helps in eliminating errors when typing, without needing to compile the
               sources.
               6.13          The  help  system


               More information on how to handle the IDE, or about the use of various calls in the RTL,
               explanations regarding the syntax of a Pascal statement, can be found in the help  system.
               The help system is activated by pressing F1.
               6.13.1         Navigating  in  the  help  system

               The help system contains hyperlinks; these are sensitive locations that lead to another topic
               in the help system.  They are marked by a different color.  The hyperlinks can be activated
               in 2 ways:


                   1.  by clicking them with the mouse,

                   2.  by using the Tab and Shift-Tab keys to move between the different hyperlinks of a
                       page and the Enter key can be used to activate them.


               The  contents  of  the  help  system  is  displayed,  if  Shift-F1  is  pressed.   To  go  back  to  the
               previous help topic, press Alt-F1.  This also works if the help window isn't displayed on the
               desktop; the help window will then be activated.
               6.13.2         Working  with  help  files

               The IDE contains a help system which can display the following file formats:


               TPH       The help format for the Turbo Pascal help viewer.

               INF     The OS/2 help format.

               NG     The Norton Guide Help format.

               HTML         HTML files.


               In future some more formats may be added.  However, the above formats should cover already
               a wide spectrum of help files available.

Remark:         Concerning the support for HTML files the following should be noted:


                   1.  The  HTML  viewer  of  the  help  system  is  limited,  it  can  only  handle  the  most  basic
                       HTML  files  (graphics  excluded),  since  it  is  only  designed  to  display  the  Free  Pascal
                       help files.  6.
               ___________________________________________________6
                    ...but feel free to improve it and send patches to the Free Pascal development team...


                                                                                82

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
    2.  When the HTML help viewer encounters a graphics file, it will try and find a file with
        the same name but an extension of .ans; If this file is found, this will be interpreted as
        a file with ANSI escape sequences, and these will be used to display a text image.  The
        displays of the IDE dialogs in the IDE help files are made in this way.


The menu item "Help_Files" permits to add and delete help files to the list of files in the
help table of contents.  The help files dialog is displayed in figure (6.37  ).



                                        Figure 6.37:  The help files dialog


The dialogs lists the files that will be presented in the table of contents window of the help
system.  Each  entry  has  a  small  descriptive  title  and  a  filename  next  to  it.  The  following
actions are available when adding help files:


New      Adds  a  new  file.   IDE  will  display  a  prompt,  in  which  the  location  of  the  help  file
        should be entered.

        If the added file is an HTML file, a dialog box will be displayed which asks for a title.
        This title will then be included in the contents of help.

Delete      Deletes the currently highlighted file from the help system.  It is not  deleted from
        the hard disk, only the help system entry is removed.

Cancel      Discards all changes and closes the dialog.

OK     Saves the changes and closes the dialog.


The Free Pascal documentation in HTML format can be added to the IDE's help system,
this  way  the  documentation  can  be  viewed  from  within  the  IDE.  If  Free  Pascal  has  been
installed using the installer, the installer should have added the FPC documentation to the
list of help files, if the documentation was installed as well.
6.13.3         The  about  dialog

The  about  dialog,  reachable  through  ("Help_About...")  shows  some  information  about
the IDE, such as the version number, the date it was built, what compiler and debugger it
uses.  When reporting bugs about the IDE, please use the information given by this dialog
to identify the version of the IDE that was used.

It also displays some copyright information.



                                                                 83

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
6.14          Keyboard  shortcuts


A lot of keyboard shortcuts used by the IDE are compatible with WordStar and should be
well known to Turbo Pascal users.

Below are the following tables:


    1.  In table (6.4 ) some shortcuts for handling the IDE windows and Help are listed.

    2.  In table (6.5 ) the shortcuts for compiling, running and debugging a program are pre-
        sented.

    3.  In table (6.6 ) the navigation keys are described.

    4.  In table (6.7 ) the editing keys are listed.

    5.  In table (6.8 ) lists all block command shortcuts.

    6.  In table (6.9 ) all selection-changing shortcuts are presented.

    7.  In table (6.10  ) some general shortcuts are presented, which do not fit in the previous
        categories.
                                                  Table 6.4:  General

                 __Command__________________________________________Key_shortcut____________Alternative______
                   Help                                             F1
                   Goto last help topic                             Alt-F1
                   Search word at cursor position in                Ctrl-F1
                   help
                   Help index                                       Shift-F1
                   Close active window                              Alt-F3
                   Zoom/Unzoom window                               F5
                   Move/Zoom active window                          Ctrl-F5
                   Switch to next window                            F6
                   Switch to last window                            Shift-F6
                   Menu                                             F10
                   Local menu                                       Alt-F10
                   List of windows                                  Alt-0
                   Active another window                            Alt-<digit>
                   Call grep utility                                Shift-F2
                   Exit IDE                                         Alt-X



                                                                 84

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___


                                                 Table 6.5:  Compiler


                  __Command__________________________________________Key_shortcut_________Alternative_______
                    Reset debugger/program                           Ctrl-F2
                    Display call stack                               Ctrl-F3
                    Run til cursor                                   F4
                    Switch to user screen                            Alt-F5
                    Trace into                                       F7
                    Add watch                                        Ctrl-F7
                    Step over                                        F8
                    Set breakpoint at current line                   Ctrl-F8
                    Make                                             F9
                    Run                                              Ctrl-F9
                    Compile the active source file                   Alt-F9
                    Message                                          F11
                    Compiler messages                                F12


                                             Table 6.6:  Text navigation


             _Command__________________________________________Key_shortcut_____________________Alternative________
               Char left                                        Arrow left                       Ctrl-S
               Char right                                       Arrow right                      Ctrl-D
               Line up                                          Arrow up                         Ctrl-E
               Line down                                        Arrow down                       Ctrl-X
               Word left                                        Ctrl-Arrow left                  Ctrl-A
               Word right                                       Ctrl-Arrow right                 Ctrl-F
               Scroll one line up                               Ctrl-W
               Scroll one line down                             Ctrl-Z
               Page up                                          PageUp                           Ctrl-R
               Page down                                        PageDown
               Beginning of Line                                Pos1                             Ctrl-Q-S
               End of Line                                      End                              Ctrl-Q-D
               First line of window                             Ctrl-Pos1                        Ctrl-Q-E
               Last line of window                              Ctrl-End                         Ctrl-Q-X
               First line of file                               Ctrl-PageUp                      Ctrl-Q-R
               Last line of file                                Ctrl-PageDown                    Ctrl-Q-C
               Last cursor position                             Ctrl-Q-P
               Find matching block delimiter                    Ctrl-Q-[
               Find last matching block delim-                  Ctrl-Q-]
               iter


                                                                 85

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___
                                                     Table 6.7:  Edit

                  __Command__________________________________________Key_shortcut_________Alternative_______
                    Delete char                                      Del                  Ctrl-G
                    Delete left char                                 Backspace            Ctrl-H
                    Delete line                                      Ctrl-Y
                    Delete til end of line                           Ctrl-Q-Y
                    Delete word                                      Ctrl-T
                    Insert line                                      Ctrl-N
                    Toggle insert mode                               Insert               Ctrl-V


                                            Table 6.8:  Block commands

                  __Command_________________________________________Key_shortcut___________Alternative_______
                    Goto Beginning of selected text                  Ctrl-Q-B
                    Goto end of selected text                        Ctrl-Q-K
                    Select current line                              Ctrl-K-L
                    Print selected text                              Ctrl-K-P
                    Select current word                              Ctrl-K-T
                    Delete selected text                             Ctrl-Del               Ctrl-K-Y
                    Copy selected text to cursor po-                 Ctrl-K-C
                    sition
                    Move selected text to cursor po-                 Ctrl-K-V
                    sition
                    Copy selected text to clipboard                  Ctrl-Ins
                    Move  selected  text  to  the  clip-             Shift-Del
                    board
                    Indent block one column                          Ctrl-K-I
                    Unindent block one column                        Ctrl-K-U
                    Insert text from clipboard                       Shift-Insert
                    Insert file                                      Ctrl-K-R
                    Write selected text to file                      Ctrl-K-W
                    Uppercase current block                          Ctrl-K-N
                    Lowercase current block                          Ctrl-K-O
                    Uppercase word                                   Ctrl-K-E
                    Lowercase word                                   Ctrl-K-F
                                                                 86

__________________________________________________________________________________________________CHAPTER_6.___THE_IDE_____________*
 *___

                                            Table 6.9:  Change selection


__Command__________________________________________Key_shortcut_______________________________Alternative_____________________
  Mark beginning of selected text                  Ctrl-K-B
  Mark end of selected text                        Ctrl-K-K
  Remove selection                                 Ctrl-K-Y
  Extend selection one char to the                 Shift-Arrow left
  left
  Extend selection one char to the                 Shift-Arrow right
  right
  Extend  selection  to  the  begin-               Shift-Pos1
  ning of the line
  Extend  selection  to  the  end  of              Shift-End
  the line
  Extend selection to the same col-                Shift-Arrow up
  umn in the last row
  Extend selection to the same col-                Shift-Arrow down
  umn in the next row
  Extend  selection  to  the  end  of              Shift-End
  the line
  Extend selection one word to the                 Ctrl-Shift-Arrow left
  left
  Extend selection one word to the                 Ctrl-Shift-Arrow right
  right
  Extend selection one page up                     Shift-PageUp
  Extend selection one page down                   Shift-PageDown
  Extend  selection  to  the  begin-               Ctrl-Shift-Pos1                            Ctrl-Shift-PageUp
  ning of the file
  Extend  selection  to  the  end  of              Ctrl-Shift-End                             Ctrl-Shift-PageUp
  the file

                                           Table 6.10:  Misc.  commands

     __Command_________________________________________Key_shortcut_____________________________________Alternative_______
       Save file                                        F2                                              Ctrl-K-S
       Open file                                        F3
       Search                                           Ctrl-Q-F
       Search again                                     Ctrl-L
       Search and replace                               Ctrl-Q-A
       Set mark                                         Ctrl-K-n (where n can be 0..9)
       Goto mark                                        Ctrl-Q-n (where n can be 0..9)
       Undo                                             Alt-Backspace

                                                                 87


Chapter   7


Porting   and   Portable   code
7.1         Turbo  Pascal


Free Pascal was originally designed to resemble Turbo Pascal as closely as possible.  There
are,  of  course,  restrictions.  Some  of  these  are  due  to  the  fact  that  Free  Pascal  is  a  32-bit
compiler.  Other restrictions result from the fact that Free Pascal works on more than one
operating system.

In general we can say that if you keep your program code close to ANSI Pascal, you will have
no problems porting from Turbo Pascal, or even Delphi, to Free Pascal.  To a large extent,
the constructs defined by Turbo Pascal are supported.  This is even more so if you use the
-So or -S2 switches.

In the following sections we will list the Turbo Pascal and Delphi constructs which are not
supported in Free Pascal, and we will list in what ways Free Pascal extends the Turbo Pascal.
7.1.1        Things  that  will  not  work

Here we give a list of things which are defined/allowed in Turbo Pascal, but which are not
supported by Free Pascal.  Where possible, we indicate the reason.


    1.  Duplicate case labels are not allowed.  This is a bug in Turbo Pascal and will not be
        changed.

    2.  Parameter  lists  of  previously  defined  functions  and  procedures  must  match  exactly.
        The reason for this is the function overloading mechanism of Free Pascal.  (however,
        the -M (see page 5.1.5  ) option solves this.)

    3.  The MEM,  MEMW,  MEML and PORT variables for memory and port access are not available
        in the system unit.  This is due to the operating system.  Under dos, the extender unit
        (GO32.PPU) implements the mem constuct.  under linux, the ports unit implements
        such a construct.

    4.  There  are  more  reserved  words.   PROTECTED,  PUBLIC,  PUBLISHED,  TRY,  FINALLY,
        EXCEPT,  RAISE are reserved words.  This means you cannot create procedures or vari-
        ables with the same name.  While they are not reserved words in Turbo Pascal, they
        are in Delphi.  Using the -Mtp switch will solve this problem if you want to compile
        Turbo Pascal code that uses these words (chapter 12 , page 122   for a list of all reserved
        words).

                                                              88

___________________________________________________________CHAPTER_7.___PORTING_AND_PORTABLE_CODE__________________________________*
 *___
    5.  The  reserved  words  FAR,  NEAR  are  ignored.  This  is  because  Free  Pascal  is  a  32  bit
        compiler, so they're obsolete.

    6.  INTERRUPT will work only on the dos target.

    7.  By default the compiler uses AT&T assembler syntax.  This is mainly because Free Pascal
        uses gnu as.  However, other assembler forms are available.  For more information, see
        Programmers guide          .

    8.  Turbo Vision is available under the name of FreeVision, which should be almost 100%
        compatible with Turbo Vision.

    9.  The 'overlay' unit is not available.  It also isn't necessary, since Free Pascal is a 32 bit
        compiler, so program size shouldn't be a point.

   10.  There are more reserved words.  (see appendix 12  for a list of all reserved words.)

   11.  The command-line parameters of the compiler are different.

   12.  Compiler switches and directives are mostly the same, but some extra exist.

   13.  Units are not binary compatible.

   14.  The  TextRec  structure  (for  internal  description  of  files)  is  not  binary  compatible  to
        TP or Delphi.

   15.  Sets  are  always  4  bytes  in  Free  Pascal;  this  means  that  some  typecasts  which  were
        possible in Turbo Pascal are no longer possible in Free Pascal.

   16.  A file is opened for output only (using fmOutput) when it is opened with Rewrite.  In
        order to be able to read from it, it should be reset with Reset.

   17.  Destructors cannot have parameters.  This restriction can be solved by using the -So
        switch.

   18.  There can be only one destructor.  This restriction can also be solved by using the -So
        switch.

   19.  The  order  in  which  expressions  are  evaluated  is  not  necessarily  the  same.   In  the
        following expression:


        a  :=  g(2)  +  f(3);


        it is not guaranteed that g(2) will be evaluated before f(3).
7.1.2        Things  which  are  extra

Here  we  give  a  list  of  things  which  are  possible  in  Free  Pascal,  but  which  didn't  exist  in
Turbo Pascal or Delphi.


    1.  Functions can also return complex types, such as records and arrays.

    2.  You can handle function results in the function itself, as a variable.  Example


        function  a  :  longint;


        begin
             a:=12;
             while  a>4  do



                                                                 89

___________________________________________________________CHAPTER_7.___PORTING_AND_PORTABLE_CODE__________________________________*
 *___
                begin
                     {...}
                end;
       end;


       The  example  above  would  work  with  TP,  but  the  compiler  would  assume  that  the
       a>4 is a recursive call.  To do a recursive call in this you must append () behind the
       function name:


       function  a  :  longint;


       begin
            a:=12;
            {  this  is  the  recursive  call  }
            if  a()>4  then
                begin
                     {...}
                end;
       end;


    3.  There  is  partial  support  of  Delphi  constructs.  (see  the  Programmers guide            for  more
        information on this).

    4.  The exit call accepts a return value for functions.


        function  a  :  longint;


        begin
             a:=12;
             if  a>4  then
                begin
                     exit(a*67);  {function  result  upon  exit  is  a*67  }
                end;
        end;


    5.  Free  Pascal  supports  function  overloading.   That  is,  you  can  define  many  functions
        with the same name, but with different arguments.  For example:


        procedure  DoSomething  (a  :  longint);
        begin
        {...}
        end;


        procedure  DoSomething  (a  :  real);
        begin
        {...}
        end;


        You can then call procedure DoSomething with an argument of type Longint or Real.
        This feature has the consequence that a previously declared function must always be
        defined with the header completely the same:


        procedure  x  (v  :  longint);  forward;

                                                                 90

___________________________________________________________CHAPTER_7.___PORTING_AND_PORTABLE_CODE__________________________________*
 *___
       {...}


       procedure  x;{  This  will  overload  the  previously  declared  x}
       begin
       {...}
       end;


       This construction will generate a compiler error, because the compiler didn't find a def-
       inition of  procedure  x  (v  :    longint);.  Instead you should define your procedure
       x as:


       procedure  x  (v  :  longint);
       {  This  correctly  defines  the  previously  declared  x}
       begin
       {...}
       end;


       (The -So (see page 5.1.5  ) switch disables overloading.  When you use it, the above will
       compile, as in Turbo Pascal.

    6.  Operator overloading.  Free Pascal allows to overload operators, i.e.  you can define e.g.
        the '+' operator for matrices.

    7.  On FAT16 and FAT32 systems, long file names are supported.
7.1.3        Turbo  Pascal  compatibility  mode

When you compile a program with the -Mtp switch, the compiler will attempt to mimic the
Turbo Pascal compiler in the following ways:


     o  Assigning a procedural variable doesn't require a @ operator.  One of the differences
        between  Turbo  Pascal  and  Free  Pascal  is  that  the  latter  requires  you  to  specify  an
        address  operator  when  assigning  a  value  to  a  procedural  variable.   In  Turbo  Pascal
        compatibility mode, this is not required.

     o  Procedure overloading is disabled.  If procedure overloading is disabled,  the function
        header doesn't need to repeat the function header.

     o  Forward defined procedures don't need the full parameter list when they are defined.
        Due to the procedure overloading feature of Free Pascal, you must always specify the
        parameter list of a function when you define it, even when it was declared earlier with
        Forward.  In Turbo Pascal compatibility mode, there is no function overloading, hence
        you can omit the parameter list:


        Procedure  a  (L  :  Longint);  Forward;


        ...


        Procedure  a  ;  {  No  need  to  repeat  the  (L  :  Longint)  }


        begin
          ...
        end;


                                                                 91

               ___________________________________________________________CHAPTER_7.___PORTING_AND_PORTABLE_CODE___________________*
 *__________________
                    o recursive function calls are handled differently.  Consider the following example :


                      Function  expr  :  Longint;


                      begin
                          ...
                          Expr:=L:
                          Writeln  (Expr);
                          ...
                      end;


                      In Turbo Pascal compatibility mode, the function will be called recursively when the
                      writeln statement is processed.  In Free Pascal, the function result will be printed.  In
                      order  to  call  the  function  recusively  under  Free  Pascal,  you  need  to  implement  it  as
                      follows :


                      Function  expr  :  Longint;


                      begin
                          ...
                          Expr:=L:
                          Writeln  (Expr());
                          ...
                      end;


                    o Any text after the final End.  statement is ignored.  Normally,  this text is processed
                      too.

                    o You cannot assign procedural variables to untyped pointers; so the following is invalid:


                        a:  Procedure;
                        b:  Pointer;
                      begin
                        b  :=  a;  //  Error  will  be  generated.


                    o The @ operator is typed when applied on procedures.

                    o You cannot nest comments.


Remark:         The MemAvail and MaxAvail functions are no longer available in Free Pascal as of version
               2.0.  The reason for this incompatibility is below:

               On  modern  operating  systems,  1 the  idea  of   vailable  Free  Memory"  is  not  valid  for  an
               application.  The reasons are:


                   1.  One  processor  cycle  after  an  application  asked  the  OS  how  much  memory  is  free,
                       another application may have allocated everything.

                   2.  It  is  not  clear  what  "free  memory"  means:   does  it  include  swap  memory,  does  it
                       include  disk  cache  memory  (the  disk  cache  can  grow  and  shrink  on  modern  OS'es),
                       does it include memory allocated to other applications but which can be swapped out,
               ________etc._______________________________________
                   1The DOS extender GO32V2 falls under this definition of m dern" because it can use paged memory
               and run in multitasked environments


                                                                                92

___________________________________________________________CHAPTER_7.___PORTING_AND_PORTABLE_CODE__________________________________*
 *___
Therefore, programs using MemAvail and MaxAvail functions should be rewritten so they no
longer use these functions, because it does not make sense anymore on modern OS'es.  There
are 3 possibilities:


    1.  Use exceptions to catch out-of-memory errors.

    2.  Set the global variable "ReturnNilIfGrowHeapFails" to True and check after each al-
        location whether the pointer is different from Nil.

    3.  Don't care and declare a dummy function called MaxAvail which always returns High(LongInt)
        (or some other constant).
7.1.4        A  note  on  long  file  names  under  dos

Under  Windows  95  and  higher,  long  filenames  are  supported.   Compiling  for  the  win32
target ensures that long filenames are supported in all functions that do file or disk access
in any way.

Moreover, Free Pascal supports the use of long filenames in the system unit and the dos unit
also  for  go32v2  executables.   The  system  unit  contains  the  boolean  variable  LFNsupport.
If it is set to True then all system unit functions and DOS unit functions will use long file
names if they are available.  This should be so on Windows 95 and 98, but not on Windows
NT or Windows 2000.  The system unit will check this by calling dos function 71A0h and
checking whether long filenames are supported on the C: drive.

It  is  possible  to  disable  the  long  filename  support  by  setting  the  LFNSupport  variable  to
False;  but in general it is recommended to compile programs that need long filenames as
native Win32 applications;
7.2         Porting  Delphi  Code


Porting Delphi code should be quite painless.  The Delphi mode of the compiler tries to mimic
Delphi as closely as possible.  This mode can be enabled using the -Mdelphi command line
switch, or by inserting the following code in the sources before the unit or program clause


{$IFDEF  FPC}
{$MODE  DELPHI}
{$ENDIF  FPC}


This ensures that the code will still compile with both Delphi and FPC.

Nevertheless,  there  are  some  things  that  will  not  work.  Delphi  compatibility  is  relatively
complete up to Delphi 7.  New constructs in higher versions of Delphi (notably, the versions
that work with .NET) are not supported.
7.2.1        Missing  language  constructs

At the level of language compatibility, FPC is very compatible with Delphi:  it can compile
most of FreeCLX, the free Widget library that was shipped with Delphi 6,7 and Kylix.

Currently, the only missing language constructs are


    1.  The Dispinterface interface.

    2.  Delegation of interfaces is not supported.



                                                                 93

___________________________________________________________CHAPTER_7.___PORTING_AND_PORTABLE_CODE__________________________________*
 *___
    3.  Dynamic methods are actually the same as virtual.

    4.  Reintroduce is not supported.

    5.  Const for a parameter to a procedure does not necessarily mean that the variable or
        value is passed by reference.

    6.  Packages are not supported.


There are some inline assembler constructs which are not supported, but since Free Pascal
is  designed  to  be  platform  independent,  it  is  quite  unlikely  that  these  constructs  will  be
supported in the future.

Note  that  the  -Mobjfpc  mode  switch  is  to  a  large  degree  Delphi  compatible,  but  is  more
strict than Delphi.  The most notable differences are:


    1.  Parameters or local variables of methods cannot have the same names as properties of
        the class in which they are implemented.

    2.  The address operator is needed when assigning procedural variables (or event handlers).

    3.  AnsiStrings are not switched on by default.
7.2.2        Missing  calls/API  incompatibilities

Delphi is heavily bound to Windows.  Because of this, it has introduces a lot of Windows-isms
in the API (e.g.  file searching and opening, loading libraries).

Free Pascal was designed to be portable, so things that are very Windows specific are missing,
although the Free Pascal team tries to minimize this.  The following are the main points that
should be considered:


     o  By  default,  Free  Pascal  generates  console  applications.   This  means  that  you  must
        explicitly enable the GUI application type for windows:


        {$APPTYPE  GUI}


     o  The Windows unit provides access to most of the core Win32 API. Some calls may have
        different parameter lists:  instead of declaring a parameter as passed by reference (var),
        a pointer is used (as in C). For most cases, Free Pascal provides overloaded versions of
        such calls.

     o  Widestrings.  Widestring  management  is  not  automatic  in  Free  Pascal,  since  various
        platforms  have  different  ways  of  dealing  with  widestring  encodings  and  Multi-Byte
        Character Sets.  FPC supports Widestrings, but may not use the same encoding as on
        Windows.

     o  Threads:  At this moment, Free Pascal does not offer native thread management on all
        platforms; on Unix, linking to the C library is needed to provide thread management
        in an FPC application.  This means that a cthreads unit must be included to enable
        threads.

     o  a much-quoted example is the SetLastOSError call.  This is not supported, and will
        never be supported.

     o  Filename  Case  sensitivity:  Pascal  is  a  case-insensitive  language,  so  the  uses  clause
        should also be case insensitive.  Free Pascal ensures case insensitive filenames by also
        searching for a lowercase version of the file.  Kylix does not do this, so this could create
        problems if 2 differently cased versions of the same filename are in the path.



                                                                 94

___________________________________________________________CHAPTER_7.___PORTING_AND_PORTABLE_CODE__________________________________*
 *___
     o RTTI is NOT stored in the same way as for Delphi.  The format is mostly compatible,
       but may differ.  This should not be a problem if the API of the TypeInfo unit is used
       and no direct access to the RTTI information is attempted.

     o Sets are of different size than in Delphi.

     o Enumerateds are of different size than in Delphi.

     o In general, one should not make assumptions about the internal structure of complex
       types such as records, objects, classes and their associated structure:  For example the
       VMT table layout is different, the alignment of fields in a record may be different, etc.

     o The same is true for basic types:  on other processors the high and low bytes of a word
       or integer may not be on the same location as on an Intel processor (the endianness is
       different).
7.2.3        Best  practices  for  porting

When  encountering  differences  in  Delphi/FPC  calls,  the  best  thing  to  do  is  not  to  insert
IFDEF statements whenever a difference is encountered, but to create a separate unit which
is only used when compiling with FPC. The missing/incompatible calls can then be imple-
mented in that unit.  This will keep the code more readable and easier to maintain.

If a language construct difference is found, then the Free Pascal team should be contacted
and a bug should be reported.
7.3         Writing  portable  code


Free Pascal is designed to be cross-platform.  This means that the basic RTL units are usable
on  all  platforms,  and  the  compiler  behaves  the  same  on  all  platforms  (as  far  as  possible).
The  Object  Pascal  langauge  is  the  same  on  all  platforms.  Nevertheless,  FPC  comes  with
a  lot  of  units  that  are  not  portable,  but  provide  access  to  all  possibilities  that  a  platform
provides.

The following are some guidelines to consider when writing portable code:


     o  Avoid  system-specific  units.  The  system  unit,  the  objects  and  classes  units  and  the
        SysUtils unit are guaranteed to work on all systems.  So is the DOS unit, but that is
        deprecated.

     o  Avoid  direct  hardware  access.  Limited,  console-like  Hardware  access  is  available  for
        most platforms in the Video, Mouse and Keyboard units.

     o  Do not use hard-coded filename conventions.  See below for more information on this.

     o  Make no assumptions on the internal representation of types.  Various processors store
        information in different ways ('endianness').

     o  If system-specific functionality is needed, it is best to separate this out in a single unit.
        Porting efforts will then be limited to re-implementing this unit for the new platform.

     o  Don't use assembler, unless you have to.  Assembler is processor specific.  Some instruc-
        tions will not work even on the same processor family.

     o  Do not assume that pointers and integers have the same size.  They do on an intel 32-
        bit processor, but not necesarily on other processors.  The PtrInt type is an alias for
        the integer type that has the same size as a pointer.  SizeInt is used for all size-related
        issues.



                                                                 95

___________________________________________________________CHAPTER_7.___PORTING_AND_PORTABLE_CODE__________________________________*
 *___
The system unit contains some constants which describe file access on a system:


LineEnding         A character or string which describes the end-of-line marker used on the cur-
       rent platform.  Commonly, this is one of #10, #13#10 or #13.

LFNSupport           A boolean that indicates whether the system supports long filenames (i.e.  is
       not limited to MS-DOS 8.3 filenames).

DirectorySeparator              is the character which acts as a separator between directory parts of
       a path.

DriveSeparator           for systems that supports driveletters,  this is the character that is used
       to separate the drive indication from the path..

PathSeparator           the character used to separate items in a list (notably, a PATH).

maxExitCode            The maximum value for a process exitcode.

MaxPathLen            The maximum length of a filename, including a path.

FileNameCaseSensitive                 a boolean that indicates whether filenames are handled case sen-
       sitively.

UnusedHandle            a value used to indicate an unused/invalid file handle.

StdInputHandle             the value of the standard input file handle.  This is not always zero, as is
       commonly the case on Unices.

StdOutputHandle              the value of the standard input file handle.  This is not always 1, as is
       commonly the case on Unices.

StdErrorHandle            the value of the standard input file handle.  This is not always 2,  as is
       commonly the case on Unices.

CtrlZMarksEOF              a boolean that indicates whether the #26 character marks the end of a
       file.  (an old MS-DOS convention)

                                                                 96


Chapter   8


Utilities   that   come   with   Free



Pascal



Besides the compiler and the Run-Time Library, Free Pascal comes with some utility pro-
grams and units.  Here we list these programs and units.
8.1         Demo  programs  and  examples


Also distributed with Free Pascal comes a series of demonstration programs.  These programs
have no other purpose than demonstrating the capabilities of Free Pascal.  They are located
in the demo directory of the sources.

All  example  programs  of  the  documentation  are  available.  Check  out  the  directories  that
end on ex in the documentation sources.  There you will find all example sources.
8.2         fpcmake


fpcmake is the Free Pascal makefile constructor program.

It reads a Makefile.fpc configuration file and converts it to a Makefile suitable for reading by
GNU make to compile your projects.  It is similar in functionality to GNU autoconf or Imake
for making X projects.

fpcmake accepts filenames of makefile description files as its command-line arguments.  For
each  of  these  files  it  will  create  a  Makefile  in  the  same  directory  where  the  file  is  located,
overwriting any other existing file.

If no options are given, it just attempts to read the file Makefile.fpc in the current directory
and tries to construct a makefile from it.  any previously existing Makefile will be erased.

The format of the fpcmake configuration file is described in great detail in the appendices of
the Programmers guide          .
8.3         fpdoc  -  Pascal  Unit  documenter


fpdoc is a program which generates fully cross-referenced documentation for a unit.  It gen-
erates documentation for each identifier found in the unit's interface section.  The generated

                                                              97

__________________________________________CHAPTER_8.___UTILITIES_THAT_COME_WITH_FREE_PASCAL________________________________________*
 *___
documentation can be in many formats for instance HTML and LaTeX. Unlike other doc-
umentation  tools,  the  documentation  can  be  in  a  separate  file  (in  XML  format),  so  the
sources aren't cluttered with documentation.  It's companion program makeskel creates an
empty XML file with entries for all identifiers.

fpdoc and makeskel are described in FPDoc reference guide          .
8.4         h2pas  -  C  header  to  Pascal  Unit  converter


h2pas attempts to convert a C header file to a pascal unit.  it can handle most C constructs
that one finds in a C header file, and attempts to translate them to their pascal counterparts.
see below (constructs) for a full description of what the translator can handle.  The unit with
pascal declarations can then be used to access code written in C.

The output of the h2pas program is written to a file with the same name as the C header
file that was used as input,  but with the extension .pp The output file that h2pas creates
can be customized in a number of ways by means of many options.
8.4.1        Options

The output of  h2pas can be controlled with the following options:


-d   use external; for all procedure and function declarations.

-D    use external  libname  name  'func_name' for function and procedure declarations.

-e   Emit a series of constants instead of an enumeration type for the C enum construct.

-i  create an include file instead of a unit (omits the unit header).

-l  libname specify the library name for external function declarations.

-o   outfile Specify the output file name.  Default is the input file name with the extension
        replaced by .pp

-p   use the letter P in front of pointer type parameters instead of ^.

-s  Strip  comments  from  the  input  file.  By  default  comments  are  converted  to  comments,
        but they may be displaced, since a comment is handled by the scanner.

-t  prepend typedef type names with the letter T (used to follow Borland's convention that
        all types should be defined with T).

-v   replace pointer parameters by call by reference parameters.  Use with care because some
        calls can expect a Nil pointer.

-w    Header file is a win32 header file (adds support for some special macros).

-x   handle SYS_TRAP of the PalmOS header files.
8.4.2        Constructs

The following C declarations and statements are recognized:

                                                                 98

__________________________________________CHAPTER_8.___UTILITIES_THAT_COME_WITH_FREE_PASCAL________________________________________*
 *___
defines     defines  are  changed  into  pascal  constants  if  they  are  simple  defines.   macros  are
       changed  -  wherever  possible  to  functions;  however  the  arguments  are  all  integers,  so
       these must be changed manually.  Simple expressions in define staments are recognized,
       as are most arithmetic operators:  addition, substraction, multiplication, division, log-
       ical operators, comparision operators, shift operators.  The C construct ( A ? B : C)
       is also recognized and translated to a pascal construct with an IF statement (this is
       buggy, however).

preprocessor statements                the  conditional  preprocessing  commands  are  recognized  and
       translated into equivalent pascal compiler directives.  The special


       #ifdef  __cplusplus


       is also recognized and removed.

typedef      A typedef statement is changed into a pascal type statement.  The following basic
       types are recognized:

           o  char changed to char.

           o  float changed to real (=double in Free Pascal).

           o  int changed to longint.

           o  long changed to longint.

           o  long  int changed to longint.

           o  short changed to integer.

           o  unsigned changed to cardinal.

           o  unsigned  char changed to byte.

           o  unsigned  int changed to cardinal.

           o  unsigned  long  int changed to cardinal.

           o  unsigned  short changed to word.

           o  void ignored.

       These types are also changed if they appear in the arguments of a function or procedure.

functions and procedures                 functions and procedures are translated as well; pointer types
       may be changed to call by reference arguments (using the var argument) by using the
       -p command line argument.  functions that have a variable number of arguments are
       changed to a function with an array  of  const argument.

specifiers     The extern specifier is recognized; however it is ignored.  the packed specifier is
       also recognised and changed with the PACKRECORDS directive.  The const specifier is
       also recognized, but is ignored.

modifiers       If the -w option is specified, then the following modifiers are recognized:


       STDCALL
       CDECL
       CALLBACK
       PASCAL
       WINAPI
       APIENTRY
       WINGDIAPI


       as defined in the win32 headers.  If additionally the -x option is specified then the



                                                                 99

__________________________________________CHAPTER_8.___UTILITIES_THAT_COME_WITH_FREE_PASCAL________________________________________*
 *___
       SYS_TRAP


       specifier is also recognized.

enums      enum constructs are changed into enumeration types; bear in mind that in C enu-
       meration  types  can  have  values  assigned  to  them;  Free  Pascal  also  allows  this  to  a
       certain degree.  If you know that values are assigned to enums, it is best to use the -e
       option to change the enus to a series of integer constants.

unions     unions are changed to variant records.

structs     are changed to pascal records, with C packing.
8.5         h2paspp  -  preprocessor  for  h2pas


h2paspp can be used as a simple preprocessor for h2pas.  It removes some of the constructs
that h2pas has difficulties with.  h2paspp reads one or more C header files and preprocesses
them,  writing  the  result  to  files  with  the  same  name  as  the  originals  as  it  goes  along.  It
does  not  accept  all  preprocesser  tokens  of  C,  but  takes  care  of  the  following  preprocessor
directives:


#define symbol             Defines the new symbol symbol.  Note that macros are not supported.

#if symbol         The text following this directive is included if  symbol is defined.

#ifdef symbol           The text following this directive is included if  symbol is defined.

#ifndef symbol            The text following this directive is included if  symbol is not defined.

#include filename             Include directives are removed, unless the -I option was given, in which
        case the include file is included and written to the output file.

#undef symbol             The symbol symbol is undefined.
8.5.1        Usage

h2paspp accepts one or more filenames and preprocesses them.  It will read the input, and
write output to a file with the same name unless the -o option is given, in which case the
file is written to the specified file.  Note that only one output filename can be given.
8.5.2        Options

h2paspp has a small number of options to control its behaviour:


-dsymbol        Define the symbol symbol before processing is started.

-h   emit a small helptext.

-I  include include files instead of dropping the include statement.

-ooutfile      If this option is given, the output will be written to a file named outfile.  Note that
        only one output file can be given.

                                                                 100

__________________________________________CHAPTER_8.___UTILITIES_THAT_COME_WITH_FREE_PASCAL________________________________________*
 *___
8.6         ppudump  program


ppudump is a program which shows the contents of a Free Pascal unit.  It is distributed with
the compiler.  You can just issue the following command


    ppudump  [options]  foo.ppu


to display the contents of the foo.ppu unit.  You can specify multiple files on the command
line.

The  options  can  be  used  to  change  the  verbosity  of  the  display.  By  default,  all  available
information is displayed.  You can set the verbosity level using the -Vxxx option.  Here, xxx
is a combination of the following letters:


h:    show header info.

i:   show interface information.

m:     show implementation information.

d:    show only (interface) definitions.

s:   show only (interface) symbols.

b:    show browser info.

a:    show everything (default if no -V option is present).
8.7         ppumove  program


ppumove  is  a  program  to  make  shared  or  static  libraries  from  multiple  units.   It  can  be
compared with the tpumove program that comes with Turbo Pascal.

It should be distributed in binary form along with the compiler.

Its usage is very simple:


ppumove  [options]  unit1.ppu  unit2.ppu  ...  unitn.ppu


Where options is a combination of


-b:    If specified, ppumve will generate a batch file that will contain the external linking and
        archiving commands that must be executed.  The name of this batch file is pmove.sh
        on linux, and pmove.bat otherwise.

-d xxx:       If specified, the output files will put in the directory xxx

-e xxx:       Sets the extension of the moved unit files to xxx.  By default, this is .ppl.  You don't
        have to specify the dot.

-o xxx:       sets the name of the output file, i.e.  the name of the file containing all the units.
        This  parameter  is  mandatory  when  you  use  multiple  files.  On  linux,  ppumove  will
        prepend this name with lib if it isn't already there, and will add an extension appro-
        priate to the type of library.

-q:    Causes ppumove to operate silently.

-s:    Tells ppumove to make a static library instead of a dynamic one; By default a dynamic
        library is made on linux.



                                                                 101

__________________________________________CHAPTER_8.___UTILITIES_THAT_COME_WITH_FREE_PASCAL________________________________________*
 *___
-w:    Tells ppumove that it is working under Windows NT. This will change the names of
       te linker and archiving program to ldw and arw, respectively.

-h or -?:      will display a short help.


The action of the ppumve program is as follows:  It takes each of the unit files, and modifies
it so that the compile will know that it should look for the unit code in the library.  The new
unit files will have an extension .ppu, this can be changed with the -e option.  It will then
put together all the object files of the units into one library, static or dynamic, depending
on the presence of the -s option.

The  name  of  this  library  must  be  set  with  the  -o  option.   If  needed,  the  prefix  lib  will
be prepended under linux..  The extension will be set to .a for static libraries,  for shared
libraries the extensions are .so on linux, and .dll under Windows NT and os/2.

As an example, the following command


./ppumove  -o  both  -e  ppl  ppu.ppu  timer.ppu


under linux, will generate the following output:


PPU-Mover  Version  0.99.7
Copyright  (c)  1998  by  the  Free  Pascal  Development  Team


Processing  ppu.ppu...  Done.
Processing  timer.ppu...  Done.
Linking  timer.o  ppu.o
Done.


And it will produce the following files:


    1.  libboth.so  :  The  shared  library  containing  the  code  from  ppu.o  and  timer.o.   Under
        Windows NT, this file would be called both.dll.

    2.  timer.ppl :  The unit file that tells the Free Pascal compiler to look for the timer code
        in the library.

    3.  ppu.ppl :  The unit file that tells the Free Pascal compiler to look for the timer code in
        the library.


You could then use or distribute the files libboth.so, timer.ppl and ppu.ppl.
8.8         ptop  -  Pascal  source  beautifier



8.8.1        ptop  program

ptop  is  a  source  beautifier  written  by  Peter  Grogono  based  on  the  ancient  pretty-printer
by  Ledgard,  Hueras,  and  Singer,  modernized  by  the  Free  Pascal  team  (objects,  streams,
configurability etc)

This configurability, and the thorough bottom-up design are the advantages of this program
over the diverse TurboPascal sourcebeautifiers on e.g.  SIMTEL.

The program is quite simple to operate:

ptop "[-v] [-i indent] [-b bufsize ][-c optsfile] infile outfile"

The Infile parameter is the pascal file to be processed,  and will be written to outfile,  over-
writing an existing outfile if it exists.



                                                                 102

__________________________________________CHAPTER_8.___UTILITIES_THAT_COME_WITH_FREE_PASCAL________________________________________*
 *___
Some options modify the behaviour of ptop:


-h  Writes an overview of the possible parameters and commandline syntax.

-c ptop.cfg      Read some configuration data from configuration file instead of using the inter-
       nal defaults then.  A config file is not required, the program can operate without one.
       See also -g.

-i ident    Sets the number of indent spaces used for BEGIN END; and other blocks.

-b bufsize      Sets the streaming buffersize to bufsize.  Default 255, 0 is considered non-valid
       and ignored.

-v  be  verbose.   Currently  only  outputs  the  number  of  lines  read/written  and  some  error
       messages.

-g  ptop.cfg     Writes a default configuration file to be edited to the file "ptop.cfg"
8.8.2        The  ptop  configuration  file

Creating and distributing a configuration file for ptop is not necesarry, unless you want to
modify the standard behaviour of  ptop.  The configuration file is never preloaded, so if you
want to use it you should always specify it with a -c  ptop.cfg parameter.

The structure of a ptop configuration file is a simple buildingblock repeated several (20-30)
times,  for each pascal keyword known to the ptop program.  (see the default configuration
file or ptopu.pp source to find out which keywords are known)

The basic building block of the configuration file consists out of one or two lines, describing
how ptop should react on a certain keyword.  First a line without square brackets with the
following format:

keyword=option1,option2,option3,...

If one of the options is "dindonkey" (see further below), a second line (with square brackets)
is needed like this:

[keyword]=otherkeyword1,otherkeyword2,otherkeyword3,...

As you can see the block contains two types of identifiers, keywords(keyword and otherkey-
word1..3 in above example) and options, (option1..3 above).

Keywords  are  the  built-in  valid  Pascal  structure-identifiers  like  BEGIN,  END,  CASE,  IF,
THEN, ELSE, IMPLEMENTATION. The default configuration file lists most of these.

Besides the real Pascal keywords, some other codewords are used for operators and comment
expressions.  table (8.1 )

The Options codewords define actions to be taken when the keyword before the equal sign
is found, table (8.2 )

The  option  "dindonkey"  requires  some  extra  parameters,  which  are  set  by  a  second  line
for that option (the one with the square brackets), which is therefore is only needed if the
options contain "dinkdonkey" (contraction of de-indent on assiociated keyword).

"dinkdonkey" deindents if any of the keywords specified by the extra options of the square-
bracket line is found.

Example:  The lines


else=crbefore,dindonkey,inbytab,upper
[else]=if,then,else
                                                                 103

__________________________________________CHAPTER_8.___UTILITIES_THAT_COME_WITH_FREE_PASCAL________________________________________*
 *___

                                        Table 8.1:  keywords for operators


                       __Name_of_codeword_____________operator_________________________________________
                         casevar                      :  in a case label ( unequal 'colon')
                         becomes                      :=
                         delphicomment                //
                         opencomment                  { or (*
                         closecomment                 } or *)
                         semicolon                    ;
                         colon                        :
                         equals                       =
                         openparen                    [
                         closeparen                   ]
                         period                       .

mean the following:


     o The keyword this block is about is else because it's on the LEFT side of both equal
       signs.

     o The option crbefore signals not to allow other code (so just spaces) before the ELSE
       keyword on the same line.

     o The option dindonkey de-indents if the parser finds any of the keywords in the square
       brackets line (if,then,else)

     o The option inbytab means indent by a tab.

     o The option upper uppercase the keyword (else or Else becomes ELSE)


Try to play with the configfile step by step until you find the effect you desire.  The config-
urability and possibilities of ptop are quite large.  E.g.  I like all keywords uppercased instead
of capitalized, so I replaced all capital keywords in the default file by upper.

ptop is still development software,  so it is wise to visually check the generated source and
try to compile it, to see if  ptop hasn't made any errors.
8.8.3        ptopu  unit

The source of the PtoP program is conveniently split in two files:  One is a unit containing an
object that does the actual beautifying of the source, the other is a shell built around this
object so it can be used from the command line.  This design makes it possible to include
the object in some program (e.g.  an IDE) and use its features to format code.

The object resided in the PtoPU unit, and is declared as follows


    TPrettyPrinter=Object(TObject)
          Indent  :  Integer;       {  How  many  characters  to  indent  ?  }
          InS       :  PStream;
          OutS     :  PStream;
          DiagS    :  PStream;
          CfgS  :  PStream;
          Constructor  Create;
          Function  PrettyPrint  :  Boolean;
       end;



                                                                 104

__________________________________________CHAPTER_8.___UTILITIES_THAT_COME_WITH_FREE_PASCAL________________________________________*
 *___

                                             Table 8.2:  Possible options


                          __Option____________does_what_____________________________________________
                            crsupp            suppress CR before the keyword.
                            crbefore          force CR before keyword
                                              (doesn't go with crsupp :)  )
                            blinbefore        blank line before keyword.
                            dindonkey         de-indent on associated keywords
                                              (see below)
                            dindent           deindent (always)
                            spbef             space before
                            spaft             space after
                            gobsym            Print symbols which follow a
                                              keyword but which do not
                                              affect layout.  prints until
                                              terminators occur.
                                              (terminators are hard-coded in pptop,
                                              still needs changing)
                            inbytab           indent by tab.
                            crafter           force CR after keyword.
                            upper             prints keyword all uppercase
                            lower             prints keyword all lowercase
                            capital           capitalizes keyword:  1st letter
                                              uppercase, rest lowercase.

Using this object is very simple.  The procedure is as follows:


    1.  Create the object, using its constructor.

    2.  Set  the  Ins  stream.  This  is  an  open  stream,  from  which  pascal  source  will  be  read.
        This is a mandatory step.

    3.  Set  the  OutS  stream.  This  is  an  open  stream,  to  which  the  beautified  pascal  source
        will be written.  This is a mandatory step.

    4.  Set  the  DiagS  stream.  Any  diagnostics  will  be  written  to  this  stream.  This  step  is
        optional.  If you don't set this, no diagnostics are written.

    5.  Set the Cfgs stream.  A configuration is read from this stream.  (see the previous section
        for more information about configuration).  This step is optional.  If you don't set this,
        a default configuration is used.

    6.  Set  the  Indent  variable.  This  is  the  number  of  spaces  to  use  when  indenting.  Tab
        characters are not used in the program.  This step is optional.  The indent variable is
        initialized to 2.

    7.  Call  PrettyPrint.   This  will  pretty-print  the  source  in  Ins  and  write  the  result  to
        OutS. The function returns True if no errors occurred, False otherwise.


So, a minimal procedure would be:


Procedure  CleanUpCode;


var



                                                                 105

__________________________________________CHAPTER_8.___UTILITIES_THAT_COME_WITH_FREE_PASCAL________________________________________*
 *___
   Ins,OutS  :  PBufStream;
   PPRinter  :  TPrettyPrinter;


begin
   Ins:=New(PBufStream,Init('ugly.pp',StopenRead,TheBufSize));
   OutS:=New(PBufStream,Init('beauty.pp',StCreate,TheBufSize));
   PPrinter.Create;
   PPrinter.Ins:=Ins;
   PPrinter.outS:=OutS;
   PPrinter.PrettyPrint;
end;


Using  memory  streams  allows  very  fast  formatting  of  code,  and  is  perfectly  suitable  for
editors.
8.9         rstconv  program


The rstconv program converts the resource string files generates by the compiler (when you
use resource string sections) to .po files that can be understood by the GNU msgfmt program.

Its usage is very easy; it accepts the following options:


-i file   Use the specified file instead of stdin as input file.  This option is optional.

-o file    write output to the specified file.  This option is required.

-f format       Specifies the output format.  At the moment, only one output format is supported:
        po for GNU gettext .po format.  It is the default format.


As an example:


rstconv  -i  resdemo.rst  -o  resdemo.po


will convert the resdemo.rst file to resdemo.po.

More information on the rstconv utility can be found in the Programmers guide          , under the
chapter about resource strings.
8.10          unitdiff  program



8.10.1         Synopsis

unitdiff  shows differences between 2 unit interface sections.


unitdiff  [--disable-arguments]  [--disable-private]  [--disable-protected]
[--help]  [--lang=language]  [--list]  [--output=filename]  [--sparse]
file1  file2
8.10.2         Description  and  usage

Unitdiff scans one or two Free Pascal unit source files and either lists all available identifiers,
or describes the differences in identifiers between the two units.

You  can  invoke  unitdiff  with  as  the  only  required  argument  a  input  filename.  It  will  then
simply list all available identifiers.



                                                                 106

__________________________________________CHAPTER_8.___UTILITIES_THAT_COME_WITH_FREE_PASCAL________________________________________*
 *___
The regular use is to invoke unitdiff  with 2 arguments:


unitdiff  input1  input2


It  will  then  show  the  difference  in  interface  between  the  two  units,  or  list  the  available
identifiers in both units.  The output of  unitdiff  will go to standard output by default.
8.10.3         Options

unitdiff  has some options, most of them optional, defaults will be used in most cases.


-disable-arguments              If  this  option  is  specified,  unitdiff  will  not  check  the  arguments  of
        functions and procedures.  By default, these are checked as well.

-disable-private           By default, private methods of classes are checked.  if this option is spec-
        ified, private fields or methods are not checked.

-disable-protected             By default, protected methods of classes are checked.  if this option is
        specified, protected and private fields or methods are not checked.

-help     Emit a short help text and exit.

-lang=language             Sets  the  language  for  the  output  file.   This  will  mainly  set  the  strings
        used for the headers in various parts of the documentation files (by default they're in
        english).  Currently, valid options are

-list   If this option is specified, only the list of available identifiers will be specified for the
        unit or units.  If only 1 unit is specified, this option is automatically assumed.

-output=filename              This option tells unitdiff  where the output should go.  If this option is
        not specified, the output is sent to standard output (the screen).

-sparse      Turns on sparse mode.  In this mode, the output will not contain the types of the
        identifiers.  Only  the  names  of  the  identifiers  are  written  to  the  output.  By  default,
        also type descriptions are written.



                                                                 107


Chapter   9


Units   that   come   with   Free



Pascal



Here we list the units that come with the Free Pascal distribution.  Since there is a difference
in the supplied units per operating system, we first describe the generic ones, then describe
those which are operating specific.
9.1         Standard  units


The following units are standard and are meant to be ported to all supported platforms by
Free Pascal.  A brief description of each unit is also given.


charset      a unit to provide mapping of character sets.

cmem       Using this unit replaces the Free Pascal memory manager with the memory manager
        of the C library.

crt   This unit is similar to the unit of the same name of Turbo Pascal.  It implements writing
        to the console in color, moving the text cursor around and reading from the keyboard.

dos    This unit provides basic routines for accessing the operating system.  This includes file
        searching, environment variables access, getting the operating system version, getting
        and setting the system time.  It is to note that some of these routines are duplicated
        in functionality in the sysutils unit.

dynlibs      provides cross-platform access to loading dynamical libraries.

errors     returns

getopts      This  unit  gives  you  the  gnu  getopts  command-line  arguments  handling  mecha-
        nism.  It also supports long options.

graph      This unit is deprecated.  This unit provides basic graphics handling, with routines to
        draw lines on the screen, display texts etc.  It provides the same functions as the Turbo
        Pascal unit.

heaptrc       a unit which debugs the heap usage.  When the program exits, it outputs a sum-
        mary  of  the  used  memory,  and  dumps  a  summary  of  unreleased  memory  blocks  (if
        any).
                                                             108

________________________________________________CHAPTER_9.___UNITS_THAT_COME_WITH_FREE_PASCAL______________________________________*
 *___
keyboard        provides basic keyboard handling routines in a platform independent way,  and
       supports writing custom drivers.

macpas       this unit implements several functions available only in macpas mode.  This units
       hould not be included, it's automatically included when the MACPAS mode is used.

math     This  unit  contains  common  mathematical  routines  (trigonometric  functions,  loga-
       rithms,  etc.)   as  well  as  more  complex  ones  (summations  of  arrays,  normalization
       functions, etc.).

matrix      a unit providing matrix manipulation routines.

mmx      This unit provides support for mmx extensions in your code.

mouse      provides basic mouse handling routines in a platform independent way, and supports
       writing custom drivers.

objects     This unit provides the base object for standard Turbo Pascal objects.  It also im-
       plements File and Memory stream objects, as well as sorted and non-sorted collections,
       and string streams.

objpas     is  used  for  Delphi  compatibility;  you  should  never  load  this  unit  explicitly;  it  is
       automatically loaded if you request Delphi mode.

printer     This unit provides all you need for rudimentary access to the printer using standard
       I/O routines.

sockets     This gives the programmer access to sockets and TCP/IP programming.

strings     This unit provides basic string handling routines for the pchar type, comparable to
       similar routines in standard C libraries.

system      This unit is available for all supported platforms.  It includes among others, basic file
       I/O routines, memory management routines, all compiler helper routines, and directory
       services routines.

strutils    offers a lot of extended string handling routines.

dateutils      offers a lot of extended date/time handling routines for almost any date and time
       math.

sysutils     is an alternative implementation of the sysutils unit of Delphi.  It includes file I/O
       access routines which takes care of file locking, date and string handling routines, file
       search, date and string conversion routines.

typinfo     Provides functions to acces Run-Time Type Information, just like Delphi.

variants      provides basic variant handling.

video    provides basic screen handling in a platform independent way, and supports writing
       custom drivers.
9.2         Under  DOS


emu387        This unit provides support for the coprocessor emulator.

go32     This unit provides access to possibilities of the GO32 dos extender.


                                                                 109

________________________________________________CHAPTER_9.___UNITS_THAT_COME_WITH_FREE_PASCAL______________________________________*
 *___
9.3         Under  Windows


wincrt      This  implements  a  console  in  a  standard  GUI  window,  contrary  to  the  crt  unit
        which is for the Windows console only.

Windows         This unit provides access to al Win32 API calls.  Effort has been taken to make
        sure that it is compatible to the Delphi version of this unit, so code for Delphi is easily
        ported to Free Pascal.

opengl      provides access to the low-level opengl functions in Windows.

winmouse         provides access to the mouse in Windows.

ole2    provides access to the OLE capabilities of  Windows.

winsock       provides acces to the Windows sockets API Winsock.
9.4         Under  Linux  and  BSD-like  platforms


baseunix        basic unix operations, basically a subset of the POSIX specification.  Using this
        unit should ensure portability across most unix systems.

errors     returns a string describing an operating system error code.

oldlinux      This unit is deprecated.  This unit provides access to the linux operating system.
        It provides most file and I/O handling routines that you may need.  It implements most
        of the standard C library constructs that you will find on a Unix system.  If you do a
        lot of disk/file operations,  the use of this unit is recommended over the one you use
        under Dos.

ports     This implements the various port[] constructs.  These are provided for compatibility
        only, and it is not recommended to use them extensively.  Programs using this construct
        must be run as ruit or setuid root, and are a serious security risk on your system.

unix     extende unix operations.

unixtype        all types used commonly on unix platforms.
9.5         Under  OS/2


doscalls      interface to doscalls.dll.

dive    interface to dive.dll

emx     provides access to the EMX extender.

pm*      interface units for the program manager functions.

viocalls     interface to viocalls.dll screen handling library.

moucalls       interface to moucalls.dll mouse handling library.

kbdcalls       interface to kbdcalls.dll keyboard handling library.

moncalls       interface to moncalls.dll monitoring handling library.


                                                                 110

________________________________________________CHAPTER_9.___UNITS_THAT_COME_WITH_FREE_PASCAL______________________________________*
 *___
9.6         Unit  availability


Standard unit availability for each of the supported platforms is given in the FAQ / Knowl-
edge base.


                                                                 111


Chapter   10


Debugging   your   Programs



Free Pascal supports debug information for the gnu debugger gdb, or its derivatives Insight
on win32 or ddd on linux.

This chapter describes shortly how to use this feature.  It doesn't attempt to describe com-
pletely  the  gnu  debugger,  however.   For  more  information  on  the  workings  of  the  gnu
debugger, see the gdb users' guide.

Free Pascal also suports gprof, the gnu profiler, see section 10.4   for more information on
profiling.
10.1          Compiling  your  program  with  debugger  support


First of all, you must be sure that the compiler is compiled with debugging support.  Unfor-
tunately, there is no way to check this at run time, except by trying to compile a program
with debugging support.

To compile a program with debugging support, just specify the -g option on the command-
line, as follows:


fpc  -g  hello.pp


This  will  generate  debugging  information  in  the  executable  from  your  program.  You  will
notice that the size of the executable increases substantially because of this1 .

Note that the above will only generate debug information for the code that has been generated
when  compiling  hello.pp.   This  means  that  if  you  used  some  units  (the  system  unit,  for
instance) which were not compiled with debugging support,  no debugging support will be
available for the code in these units.

There are 2 solutions for this problem.


    1.  Recompile all units manually with the -g option.

    2.  Specify  the  'build'  option  (-B)  when  compiling  with  debugging  support.   This  will
        recompile all units, and insert debugging information in each of the units.


The second option may have undesirable side effects.  It may be that some units aren't found,
or compile incorrectly due to missing conditionals, etc..

If all went well, the executable now contains the necessary information with which you can
debug it using gnu gdb.
___________________________________________________1
     A good reason not to include debug information in an executable you plan to distribute.



                                                             112

       ____________________________________________________________CHAPTER_10.___DEBUGGING_YOUR_PROGRAMS___________________________*
 *__________
       10.2          Using  gdb  to  debug  your  program


       To use gdb to debug your program, you can start the debugger, and give it as an option the
       full name of your program:


       gdb  hello


       Or, under dos:


       gdb  hello.exe


       This starts the debugger, and the debugger immediately loads your program into memory,
       but it does not run the program yet.  Instead, you are presented with the following (more or
       less) message, followed by the gdb prompt '(gdb)':


       GDB  is  free  software  and  you  are  welcome  to  distribute  copies  of  it
         under  certain  conditions;  type  "show  copying"  to  see  the  conditions.
       There  is  absolutely  no  warranty  for  GDB;  type  "show  warranty"  for  details.
       GDB  4.15.1  (i486-slackware-linux),
       Copyright  1995  Free  Software  Foundation,  Inc...
       (gdb)


       To start the program you can use the run command.  You can optionally specify command-
       line parameters, which will then be fed to your program, for example:


       (gdb)  run  -option  -anotheroption  needed_argument


       If your program runs without problems, gdb will inform you of this, and return the exit code
       of your program.  If the exit code was zero, then the message 'Program  exited  normally'
       is displayed.

       If something went wrong (a segmentation fault or so),  gdb will stop the execution of your
       program, and inform you of this with an appropriate message.  You can then use the other
       gdb commands to see what happened.  Alternatively, you can instruct gdb to stop at a certain
       point in your program, with the break command.

       Here  is  a  short  list  of  gdb  commands,  which  you  are  likely  to  need  when  debugging  your
       program:


       quit     Exits the debugger.

       kill    Stops a running program.

       help      Gives help on all gdb commands.

       file    Loads a new program into the debugger.

       directory        Add a new directory to the search path for source files.



Remark:         My copy of gdb needs '.'  to be added explicitly to the search path, otherwise it doesn't
               find the sources.

       list    Lists the program sources per 10 lines.  As an option you can specify a line number or
               function name.

       break       Sets a breakpoint at a specified line or function
                                                                        113

____________________________________________________________CHAPTER_10.___DEBUGGING_YOUR_PROGRAMS__________________________________*
 *___
awatch       Sets a watch-point for an expression.  A watch-point stops execution of your pro-
       gram whenever the value of an expression is either read or written.


for more information, see the gdb users' guide, or use the 'help' function in gdb.

The  appendix  15   contains  a  sample  init  file  for  gdb,  which  produces  good  results  when
debugging Free Pascal programs.

It is also possible to use RHIDE, a text-based IDE that uses gdb.  There is a version of RHIDE
available that can work together with FPC.
10.3          Caveats  when  debugging  with  gdb


There are some peculiarities of Free Pascal which you should be aware of when using gdb.
We list the main ones here:


    1.  Free Pascal generates information for GDB in uppercare letters.  This is a consequence
        of the fact that pascal is a case insensitive language.  So, when referring to a variable
        or function, you need to make its name all uppercase.

        As an example, of you want to watch the value of a loop variable count, you should
        type


        watch  COUNT


        Or if you want stop when a certain function (e.g MyFunction) is called, type


        break  MYFUNCTION


    2.  gdb does not know sets.

    3.  gdb doesn't know strings.  Strings are represented in gdb as records with a length field
        and an array of char contaning the string.

        You can also use the following user function to print strings:


        define  pst
        set  $pos=&$arg0
        set  $strlen  =  {byte}$pos
        print  {char}&$arg0.st@($strlen+1)
        end


        document  pst
           Print  out  a  Pascal  string
        end


        If you insert it in your gdb.ini file, you can look at a string with this function.  There
        is a sample gdb.ini in appendix 15 .

    4.  Objects are difficult to handle,  mainly because gdb is oriented towards C and C++.
        The workaround implemented in Free Pascal is that object methods are represented as
        functions, with an extra parameter this (all lowercase !)  The name of this function is
        a concatenation of the object type and the function name, separated by two underscore
        characters.

        For example, the method TPoint.Draw would be converted to TPOINT_ _DRAW, and could
        be stopped at with



                                                                 114

____________________________________________________________CHAPTER_10.___DEBUGGING_YOUR_PROGRAMS__________________________________*
 *___
       break  TPOINT__DRAW


    5.  Global overloaded functions confuse gdb because they have the same name.  Thus you
        cannot set a breakpoint at an overloaded function, unless you know its line number, in
        which case you can set a breakpoint at the starting linenumber of the function.
10.4          Support  for  gprof,  the  gnu  profiler


You  can  compile  your  programs  with  profiling  support.  for  this,  you  just  have  to  use  the
compiler switch -pg.  The compiler wil insert the necessary stuff for profiling.

When you have done this, you can run your program as you normally would run it.


yourexe


Where yourexe is the name of your executable.

When  your  program  finishes  a  file  called  gmon.out  is  generated.   Then  you  can  start  the
profiler to see the output.  You can better redirect the output to a file, becuase it could be
quite a lot:


gprof  yourexe  >  profile.log


Hint:  you can use the -flat option to reduce the amount of output of gprof.  It will then only
output the information about the timings

For more information on the gnu profiler gprof, see its manual.
10.5          Detecting  heap  memory  leaks


Free Pascal has a built in mechanism to detect memory leaks.  There is a plug-in unit for
the memory manager that analyses the memory allocation/deallocation and which prints a
memory usage report after the program exits.

The unit that does this is called heaptrc.  If you want to use it, you should include it as the
first unit in you uses clause.  Alternatively, you can supply the -gh switch to the compiler,
and it will include the unit automatically for you.

After the program exits, you will get a report looking like this:


Marked  memory  at  0040FA50  invalid
Wrong  size  :  128  allocated  64  freed
    0x00408708
    0x0040CB49
    0x0040C481
Call  trace  for  block  0x0040FA50  size  128
    0x0040CB3D
    0x0040C481


The output of the heaptrc unit is customizable by setting some variables.  Output can also
be customized using environment variables.

You can find more information about the usage of the heaptrc unit in the Unit reference      .



                                                                 115

____________________________________________________________CHAPTER_10.___DEBUGGING_YOUR_PROGRAMS__________________________________*
 *___
10.6          Line  numbers  in  run-time  error  backtraces


Normally,  when  a  run-time  error  occurs,  you  are  presented  with  a  list  of  addresses  that
represent  the  call  stack  backtrace,  i.e.   the  addresses  of  all  procedures  that  were  invoked
when the run-time error occurred.

This list is not very informative, so there exists a unit that generates the file names and line
numbers  of  the  called  procedures  using  the  addresses  of  the  stack  backtrace.  This  unit  is
called lineinfo.

You can use this unit by giving the -gl option to the compiler.  The unit will be automatically
included.  It is also possible to use the unit explicitly in your uses clause, but you must make
sure that you compile your program with debug info.

Here is an example program:


program  testline;


procedure  generateerror255;


begin
    runerror(255);
end;


procedure  generateanerror;


begin
    generateerror255;
end;


begin
    generateanerror;
end.


When compiled with -gl, the following output is generated:


Runtime  error  255  at  0x0040BDE5
    0x0040BDE5    GENERATEERROR255,    line  6  of  testline.pp
    0x0040BDF0    GENERATEANERROR,    line  13  of  testline.pp
    0x0040BE0C    main,    line  17  of  testline.pp
    0x0040B7B1


Which is more understandable than the normal message.  Make sure that all units you use
are compiled with debug info, because if they are not, no line number and filename can be
found.
10.7          Combining  heaptrc  and  lineinfo


If you combine the lineinfo and the heaptrc information, then the output of the heaptrc unit
will contain the names of the files and line numbers of the procedures that occur in the stack
backtrace.

In such a case, the output will look something like this:


Marked  memory  at  00410DA0  invalid



                                                                 116

____________________________________________________________CHAPTER_10.___DEBUGGING_YOUR_PROGRAMS__________________________________*
 *___
Wrong  size  :  128  allocated  64  freed
   0x004094B8
   0x0040D8F9    main,    line  25  of  heapex.pp
   0x0040D231
Call  trace  for  block  0x00410DA0  size  128
   0x0040D8ED    main,    line  23  of  heapex.pp
   0x0040D231


If lines without filename/line-number occur, this means there is a unit which has no debug
info included.  (in the above case, the getmem call itself)
                                                                 117


Chapter   11


Alphabetical   listing   of



command-line   options



The following is alphabetical listing of all command-line options, as generated by the com-
piler:

Free  Pascal  Compiler  version  2.1.1  [2006/05/25]  for  i386
Copyright  (c)  1993-2006  by  Florian  Klaempfl
/usr/local/lib/fpc/2.1.1/ppc386  [options]  <inputfile>  [options]
put  +  after  a  boolean  switch  option  to  enable  it,  -  to  disable  it
    -a        the  compiler  doesn't  delete  the  generated  assembler  file
          -al             list  sourcecode  lines  in  assembler  file
          -an             list  node  info  in  assembler  file
          -ap             use  pipes  instead  of  creating  temporary  assembler  files
          -ar             list  register  allocation/release  info  in  assembler  file
          -at             list  temp  allocation/release  info  in  assembler  file
    -A<x>    output  format:
          -Adefault    use  default  assembler
          -Aas            assemble  using  GNU  AS
          -Anasmcoff  coff  (Go32v2)  file  using  Nasm
          -Anasmelf    elf32  (Linux)  file  using  Nasm
          -Anasmwin32Win32  object  file  using  Nasm
          -AnasmwdosxWin32/WDOSX  object  file  using  Nasm
          -Awasm        obj  file  using  Wasm  (Watcom)
          -Anasmobj    obj  file  using  Nasm
          -Amasm        obj  file  using  Masm  (Microsoft)
          -Atasm        obj  file  using  Tasm  (Borland)
          -Aelf          elf32  (Linux)  using  internal  writer
          -Acoff        coff  (Go32v2)  using  internal  writer
          -Apecoff     pecoff  (Win32)  using  internal  writer
    -b        generate  browser  info
          -bl             generate  local  symbol  info
    -B        build  all  modules
    -C<x>    code  generation  options:
          -Cc<x>        set  default  calling  convention  to  <x>
          -CD             create  also  dynamic  library  (not  supported)
          -Ce             Compilation  with  emulated  floating  point  opcodes
          -Cf<x>        Select  fpu  instruction  set  to  use,  see  fpc  -i  for  possible  values
          -Cg             Generate  PIC  code



                                                             118

______________________CHAPTER_11.___ALPHABETICAL_LISTING_OF_COMMAND-LINE_OPTIONS___________________________________________________*
 *___
         -Ch<n>        <n>  bytes  heap  (between  1023  and  67107840)
         -Ci             IO-checking
         -Cn             omit  linking  stage
         -Co             check  overflow  of  integer  operations
         -Cp<x>        select  instruction  set,  see  fpc  -i  for  possible  values
         -Cr             range  checking
         -CR             verify  object  method  call  validity
         -Cs<n>        set  stack  size  to  <n>
         -Ct             stack  checking
         -CX             create  also  smartlinked  library
   -d<x>    defines  the  symbol  <x>
   -D        generate  a  DEF  file
         -Dd<x>        set  description  to  <x>
         -Dv<x>        set  DLL  version  to  <x>
   -e<x>    set  path  to  executable
   -E        same  as  -Cn
   -F<x>    set  file  names  and  paths:
         -Fa<x>[,y]  for  a  program  load  first  units  <x>  and  [y]  before  uses  is  parsed
         -Fc<x>        sets  input  codepage  to  <x>
         -FD<x>        sets  the  directory  where  to  search  for  compiler  utilities
         -Fe<x>        redirect  error  output  to  <x>
         -FE<x>        set  exe/unit  output  path  to  <x>
         -Fi<x>        adds  <x>  to  include  path
         -Fl<x>        adds  <x>  to  library  path
         -FL<x>        uses  <x>  as  dynamic  linker
         -Fo<x>        adds  <x>  to  object  path
         -Fr<x>        load  error  message  file  <x>
         -Fu<x>        adds  <x>  to  unit  path
         -FU<x>        set  unit  output  path  to  <x>,  overrides  -FE
   -g        generate  debugger  information:
         -gc             generate  checks  for  pointers
         -gd             use  dbx
         -gg             use  gsym
         -gh             use  heap  trace  unit  (for  memory  leak  debugging)
         -gl             use  line  info  unit  to  show  more  info  for  backtraces
         -gv             generates  programs  traceable  with  valgrind
         -gw             generate  dwarf  debugging  info
   -i        information
         -iD             return  compiler  date
         -iV             return  compiler  version
         -iSO            return  compiler  OS
         -iSP            return  compiler  processor
         -iTO            return  target  OS
         -iTP            return  target  processor
   -I<x>    adds  <x>  to  include  path
   -k<x>    Pass  <x>  to  the  linker
   -l        write  logo
   -M<x>    set  language  mode  to  <x>
         -Mfpc          free  pascal  dialect  (default)
         -Mobjfpc     switch  some  Delphi  2  extensions  on
         -Mdelphi     tries  to  be  Delphi  compatible
         -Mtp            tries  to  be  TP/BP  7.0  compatible
         -Mgpc          tries  to  be  gpc  compatible
         -Mmacpas     tries  to  be  compatible  to  the  macintosh  pascal  dialects



                                                                 119

______________________CHAPTER_11.___ALPHABETICAL_LISTING_OF_COMMAND-LINE_OPTIONS___________________________________________________*
 *___
   -n        don't  read  the  default  config  file
   -N<x>    node  tree  optimizations
         -Nu             unroll  loops
   -o<x>    change  the  name  of  the  executable  produced  to  <x>
   -O<x>    optimizations:
         -O-             disable  optimizations
         -O1             level  1  optimizations  (quick  and  debugger  friendly)
         -O2             level  2  optimizations  (-O1  +  quick  optimizations)
         -O3             level  3  optimizations  (-O2  +  slow  optimizations)
         -Oa<x>=<y>  set  alignment
         -Oo[NO]<x>  enable  or  disable  optimizations,  see  fpc  -i  for  possible  values
         -Op<x>        set  target  cpu  for  optimizing,  see  fpc  -i  for  possible  values
         -Os             generate  smaller  code
   -pg       generate  profile  code  for  gprof  (defines  FPC_PROFILE)
   -R<x>    assembler  reading  style:
         -Rdefault    use  default  assembler
         -Ratt          read  AT&T  style  assembler
         -Rintel       read  Intel  style  assembler
   -S<x>    syntax  options:
         -S2             same  as  -Mobjfpc
         -Sc             supports  operators  like  C  (*=,+=,/=  and  -=)
         -Sa             include  assertion  code.
         -Sd             same  as  -Mdelphi
         -Se<x>        error  options.  <x>  is  a  combination  of  the  following:
              <n>  :  compiler  stops  after  the  <n>  errors  (default  is  1)
              w  :  compiler  stops  also  after  warnings
              n  :  compiler  stops  also  after  notes
              h  :  compiler  stops  also  after  hints
         -Sg             allow  LABEL  and  GOTO
         -Sh             Use  ansistrings
         -Si             support  C++  styled  INLINE
         -Sk             load  fpcylix  unit
         -SI<x>        set  interface  style  to  <x>
              -SIcom        COM  compatible  interface  (default)
              -SIcorba     CORBA  compatible  interface
         -Sm             support  macros  like  C  (global)
         -So             same  as  -Mtp
         -Sp             same  as  -Mgpc
         -Ss             constructor  name  must  be  init  (destructor  must  be  done)
         -St             allow  static  keyword  in  objects
   -s        don't  call  assembler  and  linker
         -sh             Generate  script  to  link  on  host
         -st             Generate  script  to  link  on  target
         -sr             Skip  register  allocation  phase  (use  with  -alr)
   -T<x>    Target  operating  system:
         -Temx          OS/2  via  EMX  (including  EMX/RSX  extender)
         -Tfreebsd    FreeBSD
         -Tgo32v2     Version  2  of  DJ  Delorie  DOS  extender
         -Tlinux       Linux
         -Tnetbsd     NetBSD
         -Tnetware    Novell  Netware  Module  (clib)
         -Tnetwlibc  Novell  Netware  Module  (libc)
         -Topenbsd    OpenBSD
         -Tos2          OS/2  /  eComStation



                                                                 120

______________________CHAPTER_11.___ALPHABETICAL_LISTING_OF_COMMAND-LINE_OPTIONS___________________________________________________*
 *___
         -Tsunos       SunOS/Solaris
         -Twatcom     Watcom  compatible  DOS  extender
         -Twdosx       WDOSX  DOS  extender
         -Twin32       Windows  32  Bit
         -Twince       Windows  CE
   -u<x>    undefines  the  symbol  <x>
   -U        unit  options:
         -Un             don't  check  the  unit  name
         -Ur             generate  release  unit  files
         -Us             compile  a  system  unit
   -v<x>    Be  verbose.  <x>  is  a  combination  of  the  following  letters:
         e  :  Show  errors  (default)            0  :  Show  nothing  (except  errors)
         w  :  Show  warnings                         u  :  Show  unit  info
         n  :  Show  notes                              t  :  Show  tried/used  files
         h  :  Show  hints                              c  :  Show  conditionals
         i  :  Show  general  info                  d  :  Show  debug  info
         l  :  Show  linenumbers                    r  :  Rhide/GCC  compatibility  mode
         a  :  Show  everything                      x  :  Executable  info  (Win32  only)
         b  :  Write  file  names  messages  with  full  path
         v  :  write  fpcdebug.txt  with        p  :  Write  tree.log  with  parse  tree
                lots  of  debugging  info
   -W<x>    Win32-like  target  options
         -WB             Create  a  relocatable  image
         -WB<x>        Set  Image  base  to  Hexadecimal  <x>  value
         -WC             Specify  console  type  application
         -WD             Use  DEFFILE  to  export  functions  of  DLL  or  EXE
         -WF             Specify  full-screen  type  application  (OS/2  only)
         -WG             Specify  graphic  type  application
         -WN             Do  not  generate  relocation  code  (necessary  for  debugging)
         -WR             Generate  relocation  code
   -X        executable  options:
         -Xc             pass  --shared  to  the  linker  (Unix  only)
         -Xd             don't  use  standard  library  search  path  (needed  for  cross  compile)
         -Xe             use  external  linker
         -XD             try  to  link  units  dynamic                 (defines  FPC_LINK_DYNAMIC)
         -Xi             use  internal  linker
         -Xm             generate  link  map
         -XM<x>        set  the  name  of  the  'main'  program  routine  (default  is  'main')
         -XP<x>        prepend  the  binutils  names  with  the  prefix  <x>
         -Xr<x>        set  library  search  path  to  <x>  (needed  for  cross  compile)
         -Xs             strip  all  symbols  from  executable
         -XS             try  to  link  units  static  (default)  (defines  FPC_LINK_STATIC)
         -Xt             link  with  static  libraries  (-static  is  passed  to  linker)
         -XX             try  to  link  units  smart                    (defines  FPC_LINK_SMART)


   -?        shows  this  help
   -h        shows  this  help  without  waiting



                                                                 121


Chapter   12


Alphabetical   list   of   reserved



words
absolute                                    file                                       private
abstract                                    finally                                    procedure
and                                         for                                        program
array                                       forward                                    property
as                                          function                                   protected
asm                                         goto                                       public
assembler                                   if                                         raise
begin                                       implementation                             record
break                                       in                                         reintroduce
case                                        index                                      repeat
cdecl                                       inherited                                  self
class                                       initialization                             set
const                                       inline                                     shl
constructor                                 interface                                  shr
continue                                    interrupt                                  stdcall
cppclass                                    is                                         string
deprecated                                  label                                      then
destructor                                  library                                    to
div                                         mod                                        true
do                                          name                                       try
downto                                      near                                       type
else                                        nil                                        unimplemented
end                                         not                                        unit
except                                      object                                     until
exit                                        of                                         uses
export                                      on                                         var
exports                                     operator                                   virtual
external                                    or                                         while
fail                                        otherwise                                  with
false                                       packed                                     xor
far                                         popstack


                                                             122


Chapter   13


Compiler   messages



This appendix is meant to list all the compiler messages.  The list of messages is generated
from he compiler source itself, and should be faitly complete.  At this point, only assembler
errors are not in the list.
13.1          General  compiler  messages


This section gives the compiler messages which are not fatal, but which display useful infor-
mation.  The number of such messages can be controlled with the various verbosity level -v
switches.


Compiler:  arg1           When the -vt switch is used, this line tells you what compiler is used.

Compiler OS: arg1              When the -vd switch is used, this line tells you what the source op-
        erating system is.

Info:  Target OS: arg1              When the -vd switch is used,  this line tells you what the target
        operating system is.

Using executable path:  arg1                   When the -vt switch is used, this line tells you where the
        compiler looks for its binaries.

Using unit path:  arg1              When the -vt switch is used, this line tells you where the compiler
        looks for compiled units.  You can set this path with the -Fu

Using include path:  arg1                When  the  -vt  switch  is  used,  this  line  tells  you  where  the
        compiler looks for its include files (files used in {$I  xxx} statements).  You can set this
        path with the -I option.

Using library path:  arg1                When  the  -vt  switch  is  used,  this  line  tells  you  where  the
        compiler looks for the libraries.  You can set this path with the -Fl option.

Using object path:  arg1                When the -vt switch is used, this line tells you where the com-
        piler looks for object files you link in (files used in {$L  xxx} statements).  You can set
        this path with the -Fo option.

Info:  arg1 Lines compiled, arg2 sec                     When the -vi switch is used, the compiler reports
        the  number  of  lines  compiled,  and  the  time  it  took  to  compile  them  (real  time,  not
        program time).


                                                             123

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Fatal:  No memory left               The compiler doesn't have enough memory to compile your pro-
       gram.  There are several remedies for this:

           o  If you're using the build option of the compiler, try compiling the different units
              manually.

           o  If you're compiling a huge program, split it up in units, and compile these sepa-
              rately.

           o  If the previous two don't work, recompile the compiler with a bigger heap (you
              can use the -Ch option for this, -Ch (see page 5.1.4  ))

Info:  Writing Resource String Table file:  arg1                          This message is shown when the com-
       piler  writes  the  Resource  String  Table  file  containing  all  the  resource  strings  for  a
       program.

Error:  Writing Resource String Table file:  arg1                           This message is shown when the com-
       piler encountered an error when writing the Resource String Table file

Info:  Fatal:      Prefix for Fatal Errors

Info:  Error:       Prefix for Errors

Info:  Warning:         Prefix for Warnings

Info:  Note:       Prefix for Notes

Info:  Hint:      Prefix for Hints

Error:  Path  rg1" does not exist                     The specified path does not exist.

Fatal:  Compilation aborted                 Compilation was aborted.
13.2          Scanner  messages.


This section lists the messages that the scanner emits.  The scanner takes care of the lexical
structure of the pascal file, i.e.  it tries to find reserved words, strings, etc.  It also takes care
of directives and conditional compiling handling.


Fatal:  Unexpected end of file                  this typically happens in one of the following cases :

            o  The source file ends before the final end.  statement.  This happens mostly when
               the begin and end statements aren't balanced;

            o  An include file ends in the middle of a statement.

            o  A comment was not closed

Fatal:  String exceeds line               There is a missing closing ' in a string, so it occupies multiple
        lines.

Fatal:  illegal character  rg1" (arg2)                     An illegal character was encountered in the input
        file.

Fatal:  Syntax error,  rg1" expected but  rg2" found                                   This indicates that the com-
        piler expected a different token than the one you typed.  It can occur almost everywhere
        where you make a mistake against the pascal language.

Start reading includefile arg1                  When you provide the -vt switch, the compiler tells you
        when it starts reading an included file.
                                                                 124

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Warning:  Comment level arg1 found                         When the -vw switch is used, then the compiler
       warns  you  if  it  finds  nested  comments.   Nested  comments  are  not  allowed  in  Turbo
       Pascal and can be a possible source of errors.

Note:  Ignored compiler switch  rg1"                        With -vn on, the compiler warns if it ignores a
       switch

Warning:  Illegal compiler switch  rg1"                         You  included  a  compiler  switch  (i.e.  {$...
       }) which the compiler does not recognise

Warning:  Misplaced global compiler switch                            The  compiler  switch  is  misplaced,  and
       should be located at the start of the unit or program.

Error:  Illegal char constant               This happens when you specify a character with its ASCII
       code, as in #96, but the number is either illegal, or out of range.

Fatal:  Can't open file  rg1"                 Free  Pascal  cannot  find  the  program  or  unit  source  file
       you specified on the command line.

Fatal:  Can't open include file  rg1"                     Free Pascal cannot find the source file you spec-
       ified in a {$include  ..} statement.

Error:  Illegal record alignment specifier  rg1"                           You are specifying the {$PACKRECORDS
       n}   or {$ALIGN  n}   with an illegal value for n.  For $PACKRECORDS valid alignments
       are 1, 2, 4, 8, 16, 32, C, NORMAL, DEFAULT, and for $ALIGN valid alignment are
       1,  2,  4,  8,  16,  32,  ON, OFF. Under mode MacPas $ALIGN also supports MAC68K,
       POWER and RESET.

Error:  Illegal enum minimum-size specifier  rg1"                               You are specifying the {$PACKENUM
       n} with an illegal value for n.  Only 1,2,4, NORMAL or DEFAULT are valid here.

Error:  $ENDIF expected for arg1 arg2 defined in arg3 line arg4                                       Your conditional
       compilation statements are unbalanced.

Error:  Syntax error while parsing a conditional compiling expression                                         There is an
       error in the expression following the {$if  ..}, if corsetc compiler directives.

Error:  Evaluating a conditional compiling expression                                There  is  an  error  in  the  ex-
       pression following the {$if  ..}, if corsetc compiler directives.

Warning:  Macro contents are limited to 255 characters in length                                        The contents of
       macros cannot be longer than 255 characters.

Error:  ENDIF without IF(N)DEF                         Your {$IFDEF  ..} and {$ENDIF} statements aren't
       balanced.

Fatal:  User defined:  arg1              A user defined fatal error occurred.  see also the Programmers guide

Error:  User defined:  arg1               A user defined error occurred.  see also the Programmers guide

Warning:  User defined:  arg1                  A user defined warning occurred.  see also the Programmers guide

Note:  User defined:  arg1               A user defined note was encountered.  see also the Programmers guide

Hint:  User defined:  arg1              A user defined hint was encountered.  see also the Programmers guide

Info:  User defined:  arg1             User defined information was encountered.  see also the Programmers guide

Error:  Keyword redefined as macro has no effect                               You cannot redefine keywords with
       macros.
                                                                 125

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Fatal:  Macro buffer overflow while reading or expanding a macro                                        Your  macro  or
       its result was too long for the compiler.

Warning:  Expanding of macros exceeds a depth of 16.                                   When expanding a macro, macros
       have been nested to a level of 16.  The compiler will expand no further, since this may
       be a sign that recursion is used.

Warning:  compiler switches aren't supported in // styled comments                                           Compiler switches
       should be in normal pascal style comments.

Handling switch  rg1"                 When  you  set  debugging  info  on  (-vd)  the  compiler  tells  you
       when it is evaluating conditional compile statements.

ENDIF arg1 found               When you turn on conditional messages(-vc), the compiler tells you
       where it encounters conditional statements.

IFDEF arg1 found, arg2                 When you turn on conditional messages(-vc), the compiler tells
       you where it encounters conditional statements.

IFOPT arg1 found, arg2                  When you turn on conditional messages(-vc), the compiler tells
       you where it encounters conditional statements.

IF arg1 found, arg2             When you turn on conditional messages(-vc), the compiler tells you
       where it encounters conditional statements.

IFNDEF arg1 found, arg2                   When  you  turn  on  conditional  messages(-vc),  the  compiler
       tells you where it encounters conditional statements.

ELSE arg1 found, arg2                When you turn on conditional messages(-vc), the compiler tells
       you where it encounters conditional statements.

Skipping until...         When  you  turn  on  conditional  messages(-vc),  the  compiler  tells  you
       where  it  encounters  conditional  statements,  and  whether  it  is  skipping  or  compiling
       parts.

Info:  Press <return> to continue                  When the -vi switch is used, the compiler stops com-
       pilation  and  waits  for  the  Enter  key  to  be  pressed  when  it  encounters  a  {$STOP}
       directive.

Warning:  Unsupported switch  rg1"                          When  warnings  are  turned  on  (-vw)  the  com-
       piler  warns  you  about  unsupported  switches.  This  means  that  the  switch  is  used  in
       Delphi or Turbo Pascal, but not in Free Pascal

Warning:  Illegal compiler directive  rg1"                         When  warings  are  turned  on  (-vw)  the
       compiler  warns  you  about  unrecognised  switches.   For  a  list  of  recognised  switches,
       Programmers guide

Back in arg1         When you use (-vt) the compiler tells you when it has finished reading an
       include file.

Warning:  Unsupported application type:   rg1"                               You get this warning, if you specify
       an unknown application type with the directive {$APPTYPE}

Warning:  APPTYPE is not supported by the target OS                                       The {$APPTYPE} directive
       is supported by certain operating systems only.

Warning:  DESCRIPTION is not supported by the target OS                                           The {$DESCRIPTION}
       directive is not supported on this target OS


                                                                 126

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Note:  VERSION is not supported by target OS                                 The {$VERSION} directive is not sup-
       ported on this target OS

Note:  VERSION only for exes or DLLs                            The {$VERSION} directive is only used for ex-
       ecutable or DLL sources.

Warning:  Wrong format for VERSION directive  rg1"                                       The {$VERSION} directive
       format is majorversion.minorversion where majorversion and minorversion are words.

Error:  Illegal assembler style specified  rg1"                         When you specify an assembler mode
       with the {$ASMMODE  xxx} the compiler didn't recognize the mode you specified.

Warning:  ASM reader switch is not possible inside asm statement,  rg1" will be effective only for next
       It is not possible to switch from one assembler reader to another inside an assembler
       block.  The new reader will be used for next assembler statements only.

Error:  Wrong switch toggle, use ON/OFF or +/-                                 You need to use ON or OFF or a
       + or - to toggle the switch

Error:  Resource files are not supported for this target                               The  target  you  are  compil-
       ing for doesn't support resource files.

Warning:  Include environment  rg1" not found in environment                                          The included en-
       vironment variable can't be found in the environment, it will be replaced by an empty
       string instead.

Error:  Illegal value for FPU register limit                       Valid values for this directive are 0..8 and
       NORMAL/DEFAULT

Warning:  Only one resource file is supported for this target                                   The target you are com-
       piling for supports only one resource file.  The first resource file found is used, the others
       are discarded.

Warning:  Macro support has been turned off                              A  macro  declaration  has  been  found,
       but macro support is currently off, so the declaration will be ignored.  To turn macro
       support on compile with -Sm on the commandline or add {$MACRO ON} in the source

Error:  Illegal interface type specified.  Valids are COM, CORBA or DEFAULT.
       The interface type that was specified is not supported

Warning:  APPID is only supported for PalmOS                                 The {$APPID} directive is only sup-
       ported for the PalmOS target.

Warning:  APPNAME is only supported for PalmOS                                       The {$APPNAME} directive is only
       supported for the PalmOS target.

Error:  Constant strings can't be longer than 255 chars                                 A single string constant can
       contain at most 255 chars.  Try splitting up the string in multiple smaller parts and
       concatenate them with a + operator.

Fatal:  Including include files exceeds a depth of 16.                            When including include files the
       files have been nested to a level of 16.  The compiler will expand no further, since this
       may be a sign that recursion is used.

Fatal:  Too many levels of PUSH                     A maximum of 20 levels is allowed.  This error occurs
       only in mode MacPas.

Error:  A POP without a preceding PUSH                              This error occurs only in mode MacPas.


                                                                 127

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Error:  Macro or compile time variable  rg1" does not have any value                                            Thus the
       conditional compile time expression cannot be evaluated.

Error:  Wrong switch toggle, use ON/OFF/DEFAULT or +/-/*                                              You  need  to  use
       ON or OFF or DEFAULT or a + or - or * to toggle the switch

Error:  Mode switch  rg1" not allowed here                             A  mode  switch  has  already  been  en-
       countered, or, in case of option -Mmacpas, a mode switch occur after UNIT.

Error:  Compile time variable or macro  rg1" is not defined.                                     Thus the conditional
       compile time expression cannot be evaluated.  Only in mode MacPas.

Error:  UTF-8 code greater than 65535 found                             Free Pascal handles utf-8 strings inter-
       nally as widestrings e.g.  the char codes are limited to 65535

Error:  Malformed UTF-8 string                      The given string isn't a valid UTF-8 string

UTF-8 signature found, using UTF-8 encoding                                The compiler found an UTF-8 encod-
       ing signature ($ef, $bb, $bf) at the beginning of a file, so it interprets it as an UTF-8
       file

Error:  Compile time expression:  Wanted arg1 but got arg2 at arg3                                         Type check of
       a compile time expression failed.

Note:  APPTYPE is not supported by the target OS                                    The {$APPTYPE} directive is sup-
       ported by certain operating systems only.
13.3          Parser  messages


This section lists all parser messages.  The parser takes care of the semantics of you language,
i.e.  it determines if your pascal constructs are correct.


Error:  Parser - Syntax Error                   An error against the Turbo Pascal language was encoun-
        tered.  This happens typically when an illegal character is found in the sources file.

Error:  INTERRUPT procedure can't be nested                                   An  INTERRUPT  procedure  must  be
        global.

Warning:  Procedure type  rg1" ignored                            The specified procedure directive is ignored
        by FPC programs.

Error:  Not all declarations of  rg1  re declared with OVERLOAD                                              When you want
        to  use  overloading  using  the  OVERLOAD  directive,  then  all  declarations  need  to  have
        OVERLOAD specified.

Error:  Duplicate exported function name  rg1"                                Exported function names inside a
        specific DLL must all be different

Error:  Duplicate exported function index arg1                             Exported function names inside a spe-
        cific DLL must all be different

Error:  Invalid index for exported function                          DLL function index must be in the range
        1..$FFFF

Warning:  Relocatable DLL or executable arg1 debug info does not work, disabled.
                                                                 128

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Warning:  To allow debugging for win32 code you need to disable relocation with -WN option
       Stabs info is wrong for relocatable DLL or EXES use -WN if you want to debug win32
       executables.

Error:  Constructor name must be INIT                           You are declaring an object constructor with
       a name which is not init, and the -Ss switch is in effect.  See the -Ss switch (-Ss (see
       page 5.1.5  )).

Error:  Destructor name must be DONE                             You are declaring an object destructor with
       a name which is not done, and the -Ss switch is in effect.  See the -Ss switch (-Ss (see
       page 5.1.5  )).

Error:  Procedure type INLINE not supported                               You tried to compile a program with
       C++ style inlining, and forgot to specify the -Si option (-Si (see page 5.1.5  )).  The
       compiler doesn't support C++ styled inlining by default.

Warning:  Constructor should be public                          Constructors must be in the 'public' part of
       an object (class) declaration.

Warning:  Destructor should be public                         Destructors must be in the 'public' part of an
       object (class) declaration.

Note:  Class should have one destructor only                           You can declare only one destructor for
       a class.

Error:  Local class definitions are not allowed                         Classes must be defined globally.  They
       cannot be defined inside a procedure or function

Fatal:  Anonym class definitions are not allowed                            An invalid object (class) declaration
       was encountered, i.e.  an object or class without methods that isn't derived from another
       object or class.  For example:


         Type  o  =  object
                        a  :  longint;
                        end;
       will trigger this error.

Note:  The object  rg1" has no VMT                           This is a note indicating that the declared ob-
       ject has no virtual method table.

Error:  Illegal parameter list               You  are  calling  a  function  with  parameters  that  are  of  a
       different type than the declared parameters of the function.

Error:  Wrong number of parameters specified                              There is an error in the parameter list
       of the function or procedure, the number of parameters is not correct.

Error:  overloaded identifier  rg1" isn't a function                             The compiler encountered a sym-
       bol  with  the  same  name  as  an  overloaded  function,  but  it  is  not  a  function  it  can
       overload.

Error:  overloaded functions have the same parameter list                                   You're declaring overloaded
       functions, but with the same parameter list.  Overloaded function must have at least 1
       different parameter in their declaration.

Error:  function header doesn't match the forward declaration  rg1"                                           You declared
       a function with same parameters but different result type or function modifiers.
                                                                 129

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Error:  function header  rg1" doesn't match forward :  var name changes arg2 => arg3
       You declared the function in the interface part, or with the forward directive, but
       define it with a different parameter list.

Note:  Values in enumeration types have to be ascending                                    Free Pascal allows enumer-
       ation constructions as in C. Given the following declaration two declarations:


         type  a  =  (A_A,A_B,A_E:=6,A_UAS:=200);
         type  a  =  (A_A,A_B,A_E:=6,A_UAS:=4);
       The second declaration would produce an error.  A_UAS needs to have a value higher
       than A_E, i.e.  at least 7.

Error:  With can not be used for variables in a different segment                                      With stores a vari-
       able  locally  on  the  stack,  but  this  is  not  possible  if  the  variable  belongs  to  another
       segment.

Error:  function nesting > 31                 You can nest function definitions only 31 times.

Error:  range check error while evaluating constants                               The  constants  are  out  of  their
       allowed range.

Warning:  range check error while evaluating constants                                  The constants are out of their
       allowed range.

Error:  duplicate case label               You  are  specifying  the  same  label  2  times  in  a  case  state-
       ment.

Error:  Upper bound of case range is less than lower bound                                     The upper bound of a
       case label is less than the lower bound and this is useless

Error:  typed constants of classes are not allowed                            You  cannot  declare  a  constant  of
       type class or object.

Error:  functions variables of overloaded functions are not allowed                                      You  are  trying
       to assign an overloaded function to a procedural variable.  This is not allowed

Error:  string length must be a value from 1 to 255                              The  length  of  a  shortstring  in
       Pascal  is  limited  to  255  characters.   You  are  trying  to  declare  a  string  with  length
       lower than 1 or greater than 255

Warning:  use extended syntax of NEW and DISPOSE for instances of objects                                                    If
       you have a pointer a to a class type, then the statement new(a) will not initialize the
       class (i.e.  the constructor isn't called),  although space will be allocated.  you should
       issue the new(a,init) statement.  This will allocate space, and call the constructor of
       the object

Warning:  use of NEW or DISPOSE for untyped pointers is meaningless

Error:  use of NEW or DISPOSE is not possible for untyped pointers                                            You cannot
       use new(p) or dispose(p) if  p is an untyped pointer because no size is associated to
       an untyped pointer.  Accepted for compatibility in tp and delphi modes.

Error:  class identifier expected                 This happens when the compiler scans a procedure dec-
       laration that contains a dot, i.e., a object or class method, but the type in front of the
       dot is not a known type.

Error:  type identifier not allowed here                      You cannot use a type inside an expression.



                                                                 130

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Error:  method identifier expected                     This identifier is not a method.  This happens when
       the compiler scans a procedure declaration that contains a dot, i.e., a object or class
       method, but the procedure name is not a procedure of this type.

Error:  function header doesn't match any method of this class  rg1"                                           This iden-
       tifier is not a method.  This happens when the compiler scans a procedure declaration
       that  contains  a  dot,  i.e.,  a  object  or  class  method,  but  the  procedure  name  is  not  a
       procedure of this type.

procedure/function arg1                 When using the -vd switch, the compiler tells you when it starts
       processing a procedure or function implementation.

Error:  Illegal floating point constant                    The compiler expects a floating point expression,
       and gets something else.

Error:  FAIL can be used in constructors only                            You are using the fail keyword out-
       side a constructor method.

Error:  Destructors can't have parameters                          You are declaring a destructor with a pa-
       rameter list.  Destructor methods cannot have parameters.

Error:  Only class methods can be referred with class references                                      This error occurs
       in a situation like the following:


         Type  :
              Tclass  =  Class  of  Tobject;


         Var  C  :  TClass;


         begin
         ...
         C.free
       Free is not a class method and hence cannot be called with a class reference.

Error:  Only class methods can be accessed in class methods                                     This is related to the
       previous error.  You cannot call a method of an object from a inside a class method.
       The following code would produce this error:


         class  procedure  tobject.x;


         begin
            free
       Because free is a normal method of a class it cannot be called from a class method.

Error:  Constant and CASE types do not match                                One of the labels is not of the same
       type as the case variable.

Error:  The symbol can't be exported from a library                                You can only export procedures
       and functions when you write a library.  You cannot export variables or constants.

Warning:  An inherited method is hidden by  rg1"                                  A method that is declared virtual
       in a parent class, should be overridden in the descendent class with the override di-
       rective.  If you don't specify the override directive, you will hide the parent method;
       you will not override it.



                                                                 131

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Error:  There is no method in an ancestor class to be overridden:   rg1"                                           You are
       trying to override a virtual method of a parent class that does not exist.

Error:  No member is provided to access property                                You specified no read directive for
       a property.

Warning:  Stored property directive is not yet implemented                                     The  stored  directive
       is not yet implemented

Error:  Illegal symbol for property access                        There is an error in the read or write direc-
       tives for an array property.  When you declare an array property, you can only access
       it with procedures and functions.  The following code would cause such an error.


         tmyobject  =  class
            i  :  integer;
            property  x  [i  :  integer]:  integer  read  I  write  i;
Error:  Cannot access a protected field of an object here                                 Fields that are declared in
       a protected section of an object or class declaration cannot be accessed outside the
       module where the object is defined, or outside descendent object methods.

Error:  Cannot access a private field of an object here                               Fields that are declared in a
       private section of an object or class declaration cannot be accessed outside the module
       where the class is defined.

Error:  Overridden methods must have the same return type:   rg2" is overriden by  rg1" which has another return type
       If you declare overridden methods in a class definition, they must have the same return
       type.

Error:  EXPORT declared functions can't be nested                                  You  cannot  declare  a  function
       or procedure within a function or procedure that was declared as an export procedure.

Error:  Methods can't be EXPORTed                           You cannot declare a procedure that is a method
       for an object as exported.

Error:  Call by var parameters have to match exactly:  Got  rg1" expected  rg2"
       When calling a function declared with var parameters,  the variables in the function
       call must be of exactly the same type.  There is no automatic type conversion.

Error:  Class isn't a parent class of the current class                            When  calling  inherited  meth-
       ods,  you  are  trying  to  call  a  method  of  a  non-related  class.   You  can  only  call  an
       inherited method of a parent class.

Error:  SELF is only allowed in methods                         You  are  trying  to  use  the  self  parameter
       outside an object's method.  Only methods get passed the self parameters.

Error:  Methods can be only in other methods called direct with type identifier of the class
       A construction like sometype.somemethod is only allowed in a method.

Error:  Illegal use of ':'           You are using the format :  (colon) 2 times on an expression that
       is not a real expression.

Error:  range check error in set constructor or duplicate set element                                       The declara-
       tion of a set contains an error.  Either one of the elements is outside the range of the
       set type, either two of the elements are in fact the same.

Error:  Pointer to object expected                     You specified an illegal type in a new statement.  The
       extended syntax of  new needs an object as a parameter.



                                                                 132

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Error:  Expression must be constructor call                          When using the extended syntax of  new,
       you must specify the constructor method of the object you are trying to create.  The
       procedure you specified is not a constructor.

Error:  Expression must be destructor call                         When using the extended syntax of dispose,
       you must specify the destructor method of the object you are trying to dispose of.  The
       procedure you specified is not a destructor.

Error:  Illegal order of record elements                      When  declaring  a  constant  record,  you  speci-
       fied the fields in the wrong order.

Error:  Expression type must be class or record type                                A with statement needs an ar-
       gument that is of the type record or class.  You are using with on an expression that
       is not of this type.

Error:  Procedures can't return a value                        In Free Pascal, you can specify a return value
       for a function when using the exit statement.  This error occurs when you try to do
       this with a procedure.  Procedures cannot return a value.

Error:  constructors and destructors must be methods                                  You're declaring a procedure
       as destructor or constructor, when the procedure isn't a class method.

Error:  Operator is not overloaded                     You're trying to use an overloaded operator when it
       is not overloaded for this type.

Error:  Impossible to overload assignment for equal types                                  You can not overload as-
       signment for types that the compiler considers as equal.

Error:  Impossible operator overload                      The combination of operator, arguments and re-
       turn type are incompatible.

Error:  Re-raise isn't possible there                   You are trying to raise an exception where it is not
       allowed.  You can only raise exceptions in an except block.

Error:  The extended syntax of new or dispose isn't allowed for a class                                         You cannot
       generate an instance of a class with the extended syntax of new.  The constructor must
       be  used  for  that.   For  the  same  reason,  you  cannot  call  dispose  to  de-allocate  an
       instance of a class, the destructor must be used for that.

Error:  Procedure overloading is switched off                          When using the -So switch,  procedure
       overloading is switched off.  Turbo Pascal does not support function overloading.

Error:  It is not possible to overload this operator (overload = instead)                                        You are try-
       ing to overload an operator which cannot be overloaded.  The following operators can
       be overloaded :


              +,  -,  *,  /,  =,  >,  <,  <=,  >=,  is,  as,  in,  **,  :=
Error:  Comparative operator must return a boolean value                                     When overloading the =
       operator, the function must return a boolean value.

Error:  Only virtual methods can be abstract                            You are declaring a method as abstract,
       when it is not declared to be virtual.

Fatal:  Use of unsupported feature!                     You're trying to force the compiler into doing some-
       thing it cannot do yet.


                                                                 133

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Error:  The mix of different kind of objects (class, object, interface, etc) isn't allowed
       You cannot derive objects, classes, cppclasses and interfaces interttwined .  E.g.
       a class cannot have an object as parent and vice versa.

Warning:  Unknown procedure directive had to be ignored:   rg1"                                           The procedure
       directive you specified is unknown.

Error:  absolute can only be associated to one variable                                You cannot specify more than
       one variable before the absolute directive.  Thus, the following construct will provide
       this error:


         Var  Z  :  Longint;
                X,Y  :  Longint  absolute  Z;
 absolute can only be associated a var or const                             The address of a absolute directive
       can  only  point  to  a  variable  or  a  typed  constant.  Therefore,  the  following  code  will
       produce this error:


            Procedure  X;


           var  p  :  longint  absolute  x;
Error:  absolute can only be associated with a var or const                                  The address of a absolute
       directive can only point to a variable or constant.  Therefore, the following code will
       produce this error:


            Procedure  X;


           var  p  :  longint  absolute  x;
Error:  Only one variable can be initialized                        You cannot specify more than one variable
       with a initial value in Delphi mode.

Error:  Abstract methods shouldn't have any definition (with function body)                                               Abstract
       methods can only be declared, you cannot implement them.  They should be overridden
       by a descendant class.

Error:  This overloaded function can't be local (must be exported)                                        You are defin-
       ing a overloaded function in the implementation part of a unit, but there is no corre-
       sponding declaration in the interface part of the unit.

Warning:  Virtual methods are used without a constructor in  rg1"                                           If you declare
       objects  or  classes  that  contain  virtual  methods,  you  need  to  have  a  constructor  and
       destructor to initialize them.  The compiler encountered an object or class with virtual
       methods that doesn't have a constructor/destructor pair.

Macro defined:  arg1             When -vc is used, the compiler tells you when it defines macros.

Macro undefined:  arg1               When -vc is used, the compiler tells you when it undefines macros.

Macro arg1 set to arg2               When -vc is used, the compiler tells you what values macros get.

Info:  Compiling arg1             When you turn on information messages (-vi), the compiler tells
       you what units it is recompiling.



                                                                 134

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Parsing interface of unit arg1                  This  tells  you  that  the  reading  of  the  interface  of  the
       current unit starts

Parsing implementation of arg1                     This tells you that the code reading of the implemen-
       tation of the current unit, library or program starts

Compiling arg1 for the second time                       When you request debug messages (-vd) the com-
       piler tells you what units it recompiles for the second time.

Error:  No property found to override                       You  want  to  override  a  property  of  a  parent
       class, when there is, in fact, no such property in the parent class.

Error:  Only one default property is allowed                          You specified a property as Default, but
       the class already has a default property, and a class can have only one default property.

Error:  The default property must be an array property                                   Only array properties of classes
       can be made default properties.

Error:  Virtual constructors are only supported in class object model                                         You cannot
       have virtual constructors in objects.  You can only have them in classes.

Error:  No default property available                      You are trying to access a default property of a
       class, but this class (or one of its ancestors) doesn't have a default property.

Error:  The class can't have a published section, use the $M+ switch                                          If you want
       a published section in a class definition, you must use the {$M+} switch, whch turns
       on generation of type information.

Error:  Forward declaration of class  rg1" must be resolved here to use the class as ancestor
       To be able to use an object as an ancestor object, it must be defined first.  This error
       occurs in the following situation:


           Type  ParentClas  =  Class;
                   ChildClass  =  Class(ParentClass)
                      ...
                   end;
       Where ParentClass is declared but not defined.

Error:  Local operators not supported                       You  cannot  overload  locally,  i.e.  inside  proce-
       dures or function definitions.

Error:  Procedure directive  rg1" not allowed in interface section                                       This procedure
       directive is not allowed in the interface section of a unit.  You can only use it in the
       implementation section.

Error:  Procedure directive  rg1" not allowed in implementation section                                             This pro-
       cedure directive is not defined in the implementation section of a unit.  You can only
       use it in the interface section.

Error:  Procedure directive  rg1" not allowed in procvar declaration                                          This proce-
       dure directive cannot be part of a procedural or function type declaration.

Error:  Function is already declared Public/Forward  rg1"                                     You will get this error
       if a function is defined as forward twice.  Or it is once in the interface section, and
       once as a forward declaration in the implmentation section.

Error:  Can't use both EXPORT and EXTERNAL                                       These  two  procedure  directives
       are mutually exclusive



                                                                 135

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Warning:   rg1" not yet supported inside inline procedure/function                                          Inline proce-
       dures don't support this declaration.

Warning:  Inlining disabled                Inlining of procedures is disabled.

Info:  Writing Browser log arg1                   When information messages are on, the compiler warns
       you when it writes the browser log (generated with the {$Y+  } switch).

Hint:  may be pointer dereference is missing                           The compiler thinks that a pointer may
       need a dereference.

Fatal:  Selected assembler reader not supported                             The selected assembler reader (with
       {$ASMMODE  xxx}  is  not  supported.   The  compiler  can  be  compiled  with  or  without
       support for a particular assembler reader.

Error:  Procedure directive  rg1" has conflicts with other directives                                        You specified
       a  procedure  directive  that  conflicts  with  other  directives.   for  instance  cdecl  and
       pascal are mutually exclusive.

Error:  Calling convention doesn't match forward                              This  error  happens  when  you  de-
       clare a function or procedure with e.g.  cdecl;  but omit this directive in the imple-
       mentation,  or  vice  versa.  The  calling  convention  is  part  of  the  function  declaration,
       and must be repeated in the function definition.

Error:  Property can't have a default value                         Set properties or indexed properties can-
       not have a default value.

Error:  The default value of a property must be constant                                  The  value  of  a  default
       declared  property  must  be  known  at  compile  time.   The  value  you  specified  is  only
       known  at  run  time.   This  happens  .e.g.   if  you  specify  a  variable  name  as  a  default
       value.

Error:  Symbol can't be published, can be only a class                                Only class type variables can
       be in a published section of a class if they are not declared as a property.

Error:  This kind of property can't be published                             Properties  in  a  published  section
       cannot  be  array  properties.  they  must  be  moved  to  public  sections.  Properties  in  a
       published section must be an ordinal type, a real type, strings or sets.

Error:  An import name is required                       Some targets need a name for the imported proce-
       dure or a cdecl specifier

Error:  Division by zero              There is a division by zero encounted

Error:  Invalid floating point operation                      An operation on two real type values produced
       an overflow or a division by zero.

Error:  Upper bound of range is less than lower bound                                  The upper bound of a an ar-
       ray declaration is less than the lower bound and this is not possible

Warning:  string  rg1" is longer than  rg2"                            The size of the constant string is larger
       than the size you specified in string type definition

Error:  string length is larger than array of char length                               The size of the constant string
       is larger than the size you specified in the array[x..y] of char definition

Error:  Illegal expression after message directive                           Free Pascal supports only integer or
       string values as message constants


                                                                 136

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Error:  Message handlers can take only one call by ref.  parameter                                       A method declared
       with the message-directive as message handler can take only one parameter which must
       be declared as call by reference Parameters are declared as call by reference using the
       var-directive

Error:  Duplicate message label:   rg1"                       A  label  for  a  message  is  used  twice  in  one
       object/class

Error:  Self can only be an explicit parameter in methods which are message handlers
       The self parameter can only be passed explicitly to a method which is declared as mes-
       sage handler.

Error:  Threadvars can be only static or global                           Threadvars must be static or global,
       you can't declare a thread local to a procedure.  Local variables are always local to a
       thread,  because every thread has its own stack and local variables are stored on the
       stack

Fatal:  Direct assembler not supported for binary output format                                       You can't use di-
       rect  assembler  when  using  a  binary  writer,  choose  an  other  outputformat  or  use  an
       other assembler reader

Warning:  Don't load OBJPAS unit manually, use {modeobjf pc}or{mode delphi} instead
       You  are  trying  to  load  the  ObjPas  unit  manually  from  a  uses  clause.  This  is  not  a
       good idea.  Use the {$mode  objfpc} or {$mode  delphi} directives which load the unit
       automatically

Error:  OVERRIDE can't be used in objects                              Override  is  not  supported  for  objects,
       use virtual instead to override a method of a parent object

Error:  Data types which require initialization/finalization can't be used in variant records
       Some data type (e.g.  ansistring) needs initialization/finalization code which is im-
       plicitly generated by the compiler.  Such data types can't be used in the variant part
       of a record.

Error:  Resourcestrings can be only static or global                              Resourcestring can not be declared
       local, only global or using the static directive.

Error:  Exit with argument can't be used here                             an  exit  statement  with  an  argument
       for  the  return  value  can't  be  used  here,  this  can  happen  e.g.   in  try..except  or
       try..finally blocks

Error:  The type of the storage symbol must be boolean                                   If you specify a storage sym-
       bol in a property declaration, it must be of the type boolean

Error:  This symbol isn't allowed as storage symbol                               You can't use this type of sym-
       bol as storage specifier in property declaration.  You can use only methods with the
       result type boolean, boolean class fields or boolean constants

Error:  Only class which are compiled in $M+ mode can be published                                             In the pub-
       lished section of a class can be only class as fields used which are compiled in {$M+}
       or which are derived from such a class.  Normally such a class should be derived from
       TPersitent

Error:  Procedure directive expected                       This error is triggered when you have a {$Calling}
       directive without a calling convention specified.  It also happens when declaring a pro-
       cedure in a const block and you used a ; after a procedure declaration which must be
       followed by a procedure directive.  Correct declarations are:

                                                                 137

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
         const
            p  :  procedure;stdcall=nil;
            p  :  procedure  stdcall=nil;
Error:  The value for a property index must be of an ordinal type                                        The  value  you
       use  to  index  a  property  must  be  of  an  ordinal  type,  for  example  an  integer  or  enu-
       merated type.

Error:  Procedure name too short to be exported                                The length of the procedure/func-
       tion name must be at least 2 characters long.  This is because of a bug in dlltool which
       doesn't parse the .def file correct with a name of length 1.

Error:  No DEFFILE entry can be generated for unit global vars

Error:  Compile without -WD option                         You  need  to  compile  this  file  without  the  -WD
       switch on the commandline

Fatal:  You need ObjFpc (-S2) or Delphi (-Sd) mode to compile this module                                                You
       need to use {$mode objfpc} or {$mode delphi} to compile this file.  Or use the equiv-
       alent commandline switches -S2 or -Sd.

Error:  Can't export with index under arg1                           Exporting of functions or procedures with
       a specified index is not supported on this target.

Error:  Exporting of variables is not supported under arg1                                   Exporting of variables is
       not supported on this target.

Error:  Improper GUID syntax                      The GUID indication does not have the proper syntax.
       It should be of the form


         {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}
       Where each X represents a hexadecimal digit.

Warning:  Procedure named  rg1" not found that is suitable for implementing the arg2.arg3
       The compiler cannot find a suitable procedure which implements the given method of
       an  interface.  A  procedure  with  the  same  name  is  found,  but  the  arguments  do  not
       match.

Error:  interface identifier expected                   This happens when the compiler scans a class dec-
       laration that contains interface function name mapping code like this:


         type
            TMyObject  =  class(TObject,  IDispatch)
                function  IUnknown.QueryInterface=MyQueryInterface;
                ....
       and the interface before the dot not listed in the inheritance list.

Error:  Type  rg1" can't be used as array index type                                 Types  like  qword  or  int64
       aren't allowed as array index type

Error:  Con- and destructors aren't allowed in interfaces                                 Constructor  and  destruc-
       tor declarations aren't allowed in interface In the most cases the method QueryInterface
       of  IUnknown can be used to create a new interface.



                                                                 138

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Error:  Access specifiers can't be used in INTERFACES                                    The access specifiers public,
       private, protected and pusblished can't be used in interfaces because all methods
       of an interfaces must be public.

Error:  An interface can't contain fields                      Declarations  of  fields  aren't  allowed  in  inter-
       faces.  An interface can contain only methods

Error:  Can't declare local procedure as EXTERNAL                                    Declaring local procedures as
       external is not possible.  Local procedures get hidden parameters that will make the
       chance of errors very high

Warning:  Some fields coming before  rg1" weren't initialized                                      In Delphi mode, not
       all fields of a typed constant record have to be initialized, but the compiler warns you
       when it detects such situations.

Error:  Some fields coming before  rg1" weren't initialized                                   In all syntax modes but
       Delphi mode, you can't leave some fields uninitialized in the middle of a typed constant
       record

Warning:  Some fields coming after  rg1" weren't initialized                                    You  can  leave  some
       fields  at  the  end  of  a  type  constant  record  uninitialized  (the  compiler  will  initialize
       them to zero automatically).  This may be the cause of subtle problems.

Error:  VarArgs directive without CDecl and External                                  The varargs directive can only
       be used with procedures or functions that are declared with cdecl and external di-
       rectives.  The  varargs  directive  is  only  meant  to  provide  a  compatible  interface  to  C
       functions like printf.

Error:  Self must be a normal (call-by-value) parameter                                 You can't declare self as a
       const or var parameter, it must always be a call-by-value parameter

Error:  Interface  rg1" has no interface identification                              When you want to assign an
       interface to a constant, then the interface must have a GUID value set.

Error:  Unknown class field or method identifier  rg1"                                  Properties  must  refer  to  a
       field or method in the same class.

Warning:  Overriding calling convention  rg1" with  rg2"                                      There  are  two  direc-
       tives  in  the  procedure  declaration  that  specify  a  calling  convention.   Only  the  last
       directive will be used

Error:  Typed constants of the type "procedure of object" can only be initialized with NIL
       You can't assign the address of a method to a typed constant which has a 'procedure
       of  object'  type,  because  such  a  constant  requires  two  addresses:  that  of  the  method
       (which is known at compile time) and that of the object or class instance it operates
       on (which can not be known at compile time).

Error:  Default value can only be assigned to one parameter                                     It is not possible to spec-
       ify a default value for several parameters at once.  The following is invalid:


         Procedure  MyProcedure  (A,B  :  Integer  =  0);
       Instead, this should be declared as


         Procedure  MyProcedure  (A  :  Integer  =  0;  B  :  Integer  =  0);


                                                                 139

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Error:  Default parameter required for  rg1"                            The specified parameter requires a de-
       fault value.

Warning:  Use of unsupported feature!                         You're trying to force the compiler into doing
       something it cannot do yet.

Hint:  C arrays are passed by reference                       Any  array  passed  to  a  C  functions  is  passed
       by a pointer (i.e.  by reference).

Error:  C array of const must be the last argument                               You can not add any other argu-
       ment  after  an  array  of  const  for  cdecl  functions,  as  the  size  pushed  on  stack  for
       this argument is not known.

Hint:  Type  rg1" redefinition                   This is an indicator that a previously declared type is
       being redefined as something else.  This may, or may not be, a cause for errors.

Warning:  cdecl'ared functions have no high parameter                                  Functions declared with cdecl
       modifier do not pass an extra implicit parameter.

Warning:  cdecl'ared functions do not support open strings                                    Openstring is not sup-
       ported for cdecl'ared functions.

Error:  Cannot initialize variables declared as threadvar                                Variables declared as thread-
       var can not be initialized with a default value.  The variables will always be filled with
       zero at the start of a new thread.

Error:  Message directive is only allowed in Classes                             The message directive is only sup-
       ported for Class types.

Error:  Procedure or Function expected                         A class method can only be specified for pro-
       cedures and functions.

Warning:  Calling convention directive ignored:   rg1"                                 Some calling conventions are
       supported only by certain CPUs.  I.e.  most non-i386 ports support only the standard
       ABI calling convention of the CPU.

Error:  REINTRODUCE can't be used in objects                                   reintroduce is not supported for
       objects.

Error:  Each argument must have its own location                                If locations for arguments are spec-
       ified explicitly as it is required by some syscall conventions, each argument must have
       it's only location, things like procedure  p(i,j  :    longint  'r1'); aren't allowed

Error:  Each argument must have an explicit location                                 If  one  argument  has  an  ex-
       plicit argument location, all arguments of a procedure must have one.

Error:  Unknown argument location                        The  location  specified  for  an  argument  isn't  rec-
       ognized by the compiler

Error:  32 Bit-Integer or pointer variable expected                             The  libbase  for  MorphOS/Ami-
       gaOS can be give only as longint, dword or any pointer variable.

Error:  Goto statements aren't allowed between different procedures                                          It isn't allowed
       to use the goto statements referencing labels outside the current procedure.  The fol-
       lowing example shows the problem:


         ...
            procedure  p1;
            label



                                                                 140

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
                l1;


                procedure  p2;
                begin
                   goto  l1;  //  This  goto  ISN'T  allowed
                end;


            begin
                p2
            l1:
            end;
         ...

Fatal:  Procedure too complex, it requires too much registers                                    Your procedure body
       is too long for the compiler.  You should split the procedure into multiple smaller pro-
       cedures.

Error:  Illegal expression              This can occur under many circumstances.  Mostly when trying
       to evaluate constant expressions.

Error:  Invalid integer expression                   You made an expression which isn't an integer,  and
       the compiler expects the result to be an integer.

Error:  Illegal qualifier           One of the following is happening :

           o  You're trying to access a field of a variable that is not a record.

           o  You're indexing a variable that is not an array.

           o  You're dereferencing a variable that is not a pointer.

Error:  High range limit < low range limit                        You are declaring a subrange, and the lower
       limit is higher than the high limit of the range.

Error:  Exit's parameter must be the name of the procedure it is used in                                            Non lo-
       cal exit is not allowed.  This error occurs only in mode MacPas.

Error:  Illegal assignment to for-loop variable  rg1"                              The type of a for loop variable
       must be an ordinal type.  Loop variables cannot be reals or strings.  You can also not
       assign values to loop variables inside the loop (except in Delphi and TP modes).  Use a
       while or repeat loop instead if you need to do something like that, since those constructs
       were built for that.

Error:  Can't declare local variable as EXTERNAL                                  Declaring  local  variables  as  ex-
       ternal is not allowed.  Only global variables can reference to external variables.

Error:  Procedure is already declared EXTERNAL                                   The procedure is already declared
       with the EXTERNAL directive in an interface or forward declaration.

Warning:  Implicit uses of Variants unit                       The Variant type is used in the unit without
       any used unit using the Variants unit.  The compiler has implicitly added the Variants
       unit to the uses list.  To remove this warning the Variants unit needs to be added to
       the uses statement.

Error:  Class and static methods can't be used in INTERFACES                                           The specifier class
       and directive static can't be used in interfaces because all methods of an interfaces
       must be public.



                                                                 141

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Error:  Overflow in arithmetic operation                        An operation on two integers values produced
       an overflow

Error:  Protected or private expected                       strict can be only used together with protected
       or private.

Error:  SLICE can't be used outside of parameter list                                slice can be used only for ar-
       guments accepting an open array parameter

Error:  A DISPINTERFACE can't have a parent class                                     A  DISPINMTERFACE  is  a
       special type of interface which can't have a parent class

Error:  A DISPINTERFACE needs a guid                               A DISPINMTERFACE always needs an in-
       terface identification

Warning:  Overridden methods must have a related return type.  This code may crash, it depends on a Delphi parser bug ( rg2" is ov*
 *erridden by  rg1" which has another return type)
       If you declare overridden methods in a class definition, they must have the same return
       type.  Some versions of Delphi allow you to change the return type of interface meth-
       ods, and even to change procedures into functions, but the resulting code may crash
       depending on the types used and the way the methods are called.
13.4          Type  checking  errors


This section lists all errors that can occur when type checking is performed.


Error:  Type mismatch                This can happen in many cases:

            o  The variable you're assigning to is of a different type than the expression in the
               assignment.

            o  You  are  calling  a  function  or  procedure  with  parameters  that  are  incompatible
               with the parameters in the function or procedure definition.

Error:  Incompatible types:  got  rg1" expected  rg2"                                   There is no conversion pos-
        sible  between  the  two  types  Another  possiblity  is  that  they  are  declared  in  different
        declarations:


          Var
               A1  :  Array[1..10]  Of  Integer;
               A2  :  Array[1..10]  Of  Integer;


          Begin
               A1:=A2;  {  This  statement  gives  also  this  error,  it
                               is  due  the  strict  type  checking  of  pascal  }
          End.
Error:  Type mismatch between  rg1  nd  rg2"                                   The types are not equal

Error:  Type identifier expected                    The identifier is not a type, or you forgot to supply a
        type identifier.

Error:  Variable identifier expected                     This happens when you pass a constant to a routine
        (such as Inc var or Dec) when it expects a variable.  You can only pass variables as
        arguments to these functions.

                                                                 142

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Error:  Integer expression expected, but got  rg1"                               The compiler expects an expres-
       sion of type integer, but gets a different type.

Error:  Boolean expression expected, but got  rg1"                                 The expression must be a boolean
       type, it should be return true or false.

Error:  Ordinal expression expected                      The expression must be of ordinal type, i.e., max-
       imum a Longint.  This happens, for instance, when you specify a second argument to
       Inc or Dec that doesn't evaluate to an ordinal value.

Error:  pointer type expected, but got  rg1"                            The variable or expression isn't of the
       type pointer.  This happens when you pass a variable that isn't a pointer to New or
       Dispose.

Error:  class type expected, but got  rg1"                          The variable of expression isn't of the type
       class.  This happens typically when

           1.  The parent class in a class declaration isn't a class.

           2.  An exception handler (On) contains a type identifier that isn't a class.

Error:  Can't evaluate constant expression                          This  error  can  occur  when  the  bounds  of
        an array you declared does not evaluate to ordinal constants

Error:  Set elements are not compatible                         You are trying to make an operation on two
        sets, when the set element types are not the same.  The base type of a set must be the
        same when taking the union

Error:  Operation not implemented for sets                            several binary operations are not defined
        for sets like div mod ** (also >= <= for now)

Warning:  Automatic type conversion from floating type to COMP which is an integer type
        An implicit type conversion from a real type to a comp is encountered.  Since comp is a
        64 bit integer type, this may indicate an error.

Hint:  use DIV instead to get an integer result                            When  hints  are  on,  then  an  integer
        division with the '/' operator will procuce this message,  because the result will then
        be of type real

Error:  string types doesn't match, because of $V+ mode                                     When compiling in {$V+}
        mode, the string you pass as a parameter should be of the exact same type as the de-
        clared parameter of the procedure.

Error:  succ or pred on enums with assignments not possible                                      When you declared an
        enumeration type which has assignments in it, as in C, like in the following:


             Tenum  =  (a,b,e:=5);
        you cannot use the Succ or Pred functions on them.

Error:  Can't read or write variables of this type                            You are trying to read or write a
        variable from or to a file of type text, which doesn't support that.  Only integer types,
        reals, pchars and strings can be read from/written to a text file.  Booleans can only be
        written to text files.

Error:  Can't use readln or writeln on typed file                            readln and writeln are only allowed
        for text files.

                                                                 143

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Error:  Can't use read or write on untyped file.                           read and write are only allowed for
       text or typed files.

Error:  Type conflict between set elements                          There is at least one set element which is
       of the wrong type, i.e.  not of the set type.

Warning:  lo/hi(dword/qword) returns the upper/lower word/dword                                              Free  Pascal
       supports an overloaded version of  lo/hi for longint/dword/int64/qword which re-
       turns the lower/upper word/dword of the argument.  TP always uses a 16 bit lo/hi
       which  returns  always  bits  0..7  for  lo  and  the  bits  8..15  for  hi.  If  you  want  the  TP
       behavior you have to type cast the argument to word/integer

Error:  Integer or real expression expected                         The first argument to str must a real or
       integer type.

Error:  Wrong type  rg1" in array constructor                              You  are  trying  to  use  a  type  in  an
       array constructor which is not allowed.

Error:  Incompatible type for arg no.  arg1:  Got  rg2", expected  rg3"                                           You are
       trying to pass an invalid type for the specified parameter.

Error:  Method (variable) and Procedure (variable) are not compatible                                            You can't
       assign a method to a procedure variable or a procedure to a method pointer.

Error:  Illegal constant passed to internal math function                                The constant argument passed
       to a ln or sqrt function is out of the definition range of these functions.

Error:  Can't get the address of constants                        It  is  not  possible  to  get  the  address  of  a
       constant, because they aren't stored in memory, you can try making it a typed constant.

Error:  Argument can't be assigned to                        Only expressions which can be on the left side
       of an assignment can be passed as call by reference argument Remark:  Properties can
       be only used on the left side of an assignment, but they cannot be used as arguments

Error:  Can't assign local procedure/function to procedure variable                                        It's not allowed
       to assign a local procedure/function to a procedure variable, because the calling of lo-
       cal procedure/function is different.  You can only assign local procedure/function to a
       void pointer.

Error:  Can't assign values to an address                        It is not allowed to assign a value to an ad-
       dress of a variable,constant, procedure or function.  You can try compiling with -So if
       the identifier is a procedure variable.

Error:  Can't assign values to const variable                         It's  not  allowed  to  assign  a  value  to  a
       variable which is declared as a const.  This is normally a parameter declared as const,
       to allow changing the value make the parameter as a value parameter or a var.

Error:  Array type required                 If you are accessing a variable using an index '[<x>]' then the
       type must be an array.  In FPC mode also a pointer is allowed.

Error:  interface type expected, but got  rg1"                            The compiler expected to encounter
       an interface type name, but got something else.  The following code would provoke this
       error:


         Type
            TMyStream  =  Class(TStream,Integer)
                                                                 144

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Warning:  Mixing signed expressions and longwords gives a 64bit result                                            If you di-
       vide (or calculate the modulus of) a signed expression by a longword (or vice versa), or
       if you have overflow and/or range checking turned on and use an arithmetic expression
       (+, -, *, div, mod) in which both signed numbers and longwords appear, then every-
       thing has to be evaluated in 64bit which is slower than normal 32bit arithmetic.  You
       can avoid this by typecasting one operand so it matches the result type of the other
       one.

Warning:  Mixing signed expressions and cardinals here may cause a range check error
       If you use a binary operator (and, or, xor) and one of the operands is a longword while
       the other one is a signed expression, then, if range checking is turned on, you may get
       a range check error because in such a case both operands are converted to longword
       before the operation is carried out.  You can avoid this by typecasting one operand so
       it matches the result type of the other one.

Error:  Typecast has different size (arg1 -> arg2) in assignment                                    Type  casting  to  a
       type with a different size is not allowed when the variable is used for assigning.

Error:  enums with assignments can't be used as array index                                     When you declared an
       enumeration type which has assignments in it, as in C, like in the following:


            Tenum  =  (a,b,e:=5);
       you cannot use it as index of an array.

Error:  Class or Object types  rg1  nd  rg2  re not related                                       There  is  a  type-
       cast from one class or object to another while the class/object are not related.  This
       will probably lead to errors

Warning:  Class types  rg1  nd  rg2  re not related                                   There  is  a  typecast  from
       one class or object to another while the class/object are not related.  This will probably
       lead to errors

Error:  Class or interface type expected, but got  rg1"                                 The compiler expected a class
       or interface name, but got another type or identifier.

Error:  Type  rg1" is not completely defined                            This  error  occurs  when  a  type  is  not
       complete:  i.e.  a pointer type which points to an undefined type.

Warning:  String literal has more characters than short string length                                        The  size  of
       the  constant  string,  which  is  assigned  to  a  shortstring,  is  longer  than  the  maximum
       size of the shortstring

Warning:  Comparison is always false due to range of values                                    There is a comparison
       between an unsigned value and a signed constant which is less than zero.  Because of
       type  promotion,  the  statement  will  always  evaluate  to  false.   Exlicitly  typecast  the
       constant to the correct range to avoid this problem.

Warning:  Comparison is always true due to range of values                                     There is a comparison
       between  an  unsigned  value  and  a  signed  constant  which  is  less  than  zero.   Because
       of type promotion, the statement will always evaluate to true.  Exlicitly typecast the
       constant to the correct range to avoid this problem.

Warning:  Constructing a class  rg1" with abstract methods                                       An instance of a class
       is created which contains non-implemented abstract methods.  This will probably lead
       to a runtime error 211 in the code if that routine is ever called.  All abstract methods
       should be overriden.



                                                                 145

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Hint:  The left operand of the IN operator should be byte sized                                      The  left  operand
       of the in operator is not an ordinal or enumeration which fits within 8-bits, this may
       lead  to  range  check  errors.   The  in  operator  currently  only  supports  a  left  operand
       which  fits  within  a  byte.   In  the  case  of  enumerations,  the  size  of  an  element  of  an
       enumeration can be controlled with the {$PACKENUM} or {$Zn} switches.

Warning:  Type size mismatch, possible loss of data / range check error                                           There is
       an assignment to a smaller type than the source type.  This means that this may cause
       a range-check error, or may lead to possible loss of data.

Hint:  Type size mismatch, possible loss of data / range check error                                        There is an as-
       signment to a smaller type than the source type.  This means that this may cause a
       range-check error, or may lead to possible loss of data.

Error:  The address of an abstract method can't be taken                                    An abstract method has
       no body, so the address of an abstract method can't be taken.

Error:  The operator is not applicable for the operand type                                   You  are  trying  an  op-
       erator that is not available for the type of the operands

Error:  Constant Expression expected                        The  compiler  expects  an  constant  expression,
       but gets a variable expression.

Error:  Operation  rg1" not supported for types  rg2  nd  rg3"                                            The  opera-
       tion is not allowed for the supplied types

Error:  Illegal type conversion:   rg1" to  rg2"                           When doing a type-cast, you must
       take care that the sizes of the variable and the destination type are the same.

Hint:  Conversion between ordinals and pointers is not portable                                       If you typecast a
       pointer to a longint (or vice-versa), this code will not compile on a machine using 64-bit
       for pointer storage.

Warning:  Conversion between ordinals and pointers is not portable                                          If  you  type-
       cast a pointer to a ordinal type of a different size (or vice-versa), this can cause prob-
       lems.  This is a warning to help finding the 32bit specific code where cardinal/longint
       is used to typecast pointers to ordinals.  A solution is to use the ptrint/ptruint types
       instead.

Error:  Can't determine which overloaded function to call                                   You're calling overloaded
       functions with a parameter that doesn't correspond to any of the declared function pa-
       rameter  lists.   e.g.   when  you  have  declared  a  function  with  parameters  word  and
       longint, and then you call it with a parameter which is of type integer.

Error:  Illegal counter variable                 The type of a for loop variable must be an ordinal type.
       Loop variables cannot be reals or strings.

Warning:  Converting constant real value to double for C variable argument, add explicit typecast to prevent this.
       In C, constant real values are double by default.  For this reason, if you pass a constant
       real value to a variable argument part of a C function, FPC by default converts this
       constant to double as well.  If you want to prevent this from happening, add an explicit
       typecast around the constant.

Error:  Class or COM interface type expected, but got  rg1"                                       Some operators like
       the AS operator are only appliable to classes or COM interfaces.

                                                                 146

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
13.5          Symbol  handling


This  section  lists  all  the  messages  that  concern  the  handling  of  symbols.   This  means  all
things that have to do with procedure and variable names.


Error:  Identifier not found  rg1"                     The  compiler  doesn't  know  this  symbol.   Usually
        happens when you misspel the name of a variable or procedure, or when you forgot to
        declare a variable.

Fatal:  Internal Error in SymTableStack()                          An internal error occurred in the compiler;
        If  you  encounter  such  an  error,  please  contact  the  developers  and  try  to  provide  an
        exact description of the circumstances in which the error occurs.

Error:  Duplicate identifier  rg1"                    The  identifier  was  already  declared  in  the  current
        scope.

Hint:  Identifier already defined in arg1 at line arg2                             The  identifier  was  already  de-
        clared in a previous scope.

Error:  Unknown identifier  rg1"                      The identifier encountered has not been declared, or
        is used outside the scope where it is defined.

Error:  Forward declaration not solved  rg1"                             This can happen in two cases:

            o  This  happens  when  you  declare  a  function  (in  the  interface  part,  or  with  a
               forward directive, but do not implement it.

            o  You reference a type which isn't declared in the current type block.

Error:  Error in type definition                  There is an error in your definition of a new array type:

  One  of  the  range  delimiters  in  an  array  declaration  is  erroneous.   For  example,  Array
        [1..1.25] will trigger this error.

Error:  Forward type not resolved  rg1"                           A symbol was forward defined, but no dec-
        laration was encountered.

Error:  Only static variables can be used in static methods or outside methods                                                A
        static method of an object can only access static variables.

Fatal:  record or class type expected                      The variable or expression isn't of the type record
        or class.

Error:  Instances of classes or objects with an abstract method are not allowed
        You are trying to generate an instance of a class which has an abstract method that
        wasn't overridden.

Warning:  Label not defined  rg1"                       A label was declared, but not defined.

Error:  Label used but not defined  rg1"                          A label was declared and used, but not de-
        fined.

Error:  Illegal label declaration                 This  error  should  never  happen;  it  occurs  if  a  label  is
        defined outside a procedure or function.

Error:  GOTO and LABEL are not supported (use switch -Sg)                                           You  must  compile
        a  program  which  has  labels  and  goto  statements  with  the  -Sg  switch.  By  default,
        label and goto aren't supported.

Error:  Label not found               A goto  label was encountered, but the label isn't declared.



                                                                 147

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Error:  identifier isn't a label              The identifier specified after the goto isn't of type label.

Error:  label already defined                You are defining a label twice.  You can define a label only
       once.

Error:  illegal type declaration of set elements                         The  declaration  of  a  set  contains  an
       invalid type definition.

Error:  Forward class definition not resolved  rg1"                              You  declared  a  class,  but  you
       did not implement it.

Hint:  Unit  rg1" not used in arg2                      The unit referenced in the uses clause is not used.

Hint:  Parameter  rg1" not used                      The identifier was declared (locally or globally) but
       was not used (locally or globally).

Note:  Local variable  rg1" not used                       You have declared, but not used a variable in a
       procedure or function implementation.

Hint:  Value parameter  rg1" is assigned but never used                                    The identifier was declared
       (locally or globally) set but not used (locally or globally).

Note:  Local variable  rg1" is assigned but never used                                 The variable in a procedure
       or function implementation is declared, set but never used.

Hint:  Local arg1  rg2" is not used                      A local symbol is never used.

Note:  Private field  rg1.arg2" is never used                          The  indicated  private  field  is  defined,
       but is never used in the code.

Note:  Private field  rg1.arg2" is assigned but never used                                  The indicated private field
       is declared, assigned but never read.

Note:  Private method  rg1.arg2" never used                              The  indicated  private  method  is  de-
       clared but is never used in the code.

Error:  Set type expected                The variable or expression is not of type set.  This happens
       in an in statement.

Warning:  Function result does not seem to be set                               You  can  get  this  warning  if  the
       compiler thinks that a function return value is not set.  This will not be displayed for
       assembler procedures, or procedures that contain assembler blocks.

Warning:  Type  rg1" is not aligned correctly in current record for C                                          Arrays with
       sizes not multiples of 4 will be wrongly aligned for C structures.

Error:  Unknown record field identifier  rg1"                            The field doesn't exist in the record/ob-
       ject definition.

Warning:  Local variable  rg1" does not seem to be initialized                                      This message is dis-
       played if the compiler thinks that a variable will be used (i.e.  appears in the right-hand-
       side of an expression) when it was not initialized first (i.e.  appeared in the left-hand
       side of an assigment)

Warning:  Variable  rg1" does not seem to be initialized                                   This message is displayed
       if the compiler thinks that a variable will be used (i.e.  appears in the right-hand-side
       of an expression) when it was not initialized first (i.e.  appeared in the left-hand side
       of an assigment)

Error:  identifier idents no member  rg1"                          This error is generated when an identifier
       of a record, field, or method is accessed while it is not defined.



                                                                 148

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Hint:  Found declaration:  arg1                  You  get  this  when  you  use  the  -vh  switch.  In  case  an
       overloaded procedure is not found, then all candidate overloaded procedures are listed,
       with their parameter lists.

Error:  Data element too large                   You get this when you declare a data element whose size
       exceeds the prescribed limit (2 Gb on 80386+/68020+ processors)

Error:  No matching implementation for interface method  rg1" found                                              There was
       no matching method found which could implement the interface method.  Check argu-
       ment types and result type of the methods.

Warning:  Symbol  rg1" is deprecated                          This means that a symbol (a variable, routine,
       etc...)  which is declared as deprecated is used.  Deprecated symbols may no longer
       be  available  in  newer  versions  of  the  unit  /  library.  Usage  of  this  symbol  should  be
       avoided as much as possible.

Warning:  Symbol  rg1" is not portable                          This means that a symbol (a variable, rou-
       tine,  etc...)  which  is  declared  as  platform  is  used.  This  symbol's  value,  usage  and
       availability  is  platform  specific  and  should  not  be  used  if  the  source  code  must  be
       portable.

Warning:  Symbol  rg1" is not implemented                              This means that a symbol (a variable,
       routine,  etc...)  which is declared as unimplemented is used.  This symbol is defined,
       but is not yet implemented on this specific platform.

Error:  Can't create unique type from this type                             Only simple types like ordinal, float
       and  string  types  are  supported  when  redefining  a  type  with  type  newtype  =  type
       oldtype;.

Hint:  Local variable  rg1" does not seem to be initialized                                  This message is displayed
       if the compiler thinks that a variable will be used (i.e.  appears in the right-hand-side
       of an expression) when it was not initialized first (i.e.  appeared in the left-hand side
       of an assigment)

Hint:  Variable  rg1" does not seem to be initialized                               This  message  is  displayed  if
       the compiler thinks that a variable will be used (i.e.  appears in the right-hand-side of
       an expression) when it was not initialized first (i.e.  appeared in the left-hand side of
       an assigment)

Warning:  Function result variable does not seem to initialized                                    This message is dis-
       played if the compiler thinks that the function result variable will be used (i.e.  appears
       in  the  right-hand-side  of  an  expression)  before  it  is  initialized  (i.e.   appeared  in  the
       left-hand side of an assigment)

Hint:  Function result variable does not seem to be initialized                                   This message is dis-
       played if the compiler thinks that the function result variable will be used (i.e.  appears
       in  the  right-hand-side  of  an  expression)  before  it  is  initialized  (i.e.   appeared  in  the
       left-hand side of an assigment)

Warning:  Variable  rg1" read but nowhere assigned                                  You have read the value of a
       variable, but nowhere assigned a value to it.
13.6          Code  generator  messages


This section lists all messages that can be displayed if the code generator encounters an error
condition.
                                                                 149

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Error:  Parameter list size exceeds 65535 bytes                            The I386 processor limits the param-
       eter list to 65535 bytes (the RET instruction causes this)

Error:  File types must be var parameters                          You  cannot  specify  files  as  value  parame-
       ters, i.e.  they must always be declared var parameters.

Error:  The use of a far pointer isn't allowed there                            Free  Pascal  doesn't  support  far
       pointers, so you cannot take the address of an expression which has a far reference as
       a result.  The mem construct has a far reference as a result, so the following code will
       produce this error:


         var  p  :  pointer;
         ...
         p:=@mem[a000:000];
Error:  EXPORT declared functions can't be called                                 No longer in use.

Warning:  Possible illegal call of constructor or destructor                                The compiler detected that
       a  constructor  or  destructor  is  called  within  a  a  method.  This  will  probably  lead  to
       problems, since constructors / destructors require parameters on entry.

Note:  Inefficient code            Your statement seems dubious to the compiler.

Warning:  unreachable code                  You specified a construct which will never be executed.  Ex-
       ample:


         while  false  do
            begin
            {..  code  ...}
            end;
Error:  Abstract methods can't be called directly                             You cannot call an abstract method
       directy, instead you must call a overriding child method, because an abstract method
       isn't implemented.

Register arg1 weight arg2 arg3                    Debugging message.  Shown when the compiler consid-
       ers a variable for keeping in the registers.

Stack frame is omitted               Some procedure/functions do not need a complete stack-frame,
       so it is omitted.  This message will be displayed when the -vd switch is used.

Error:  Object or class methods can't be inline.                           You cannot have inlined object meth-
       ods.

Error:  Procvar calls cannot be inline.                     A procedure with a procedural variable call can-
       not be inlined.

Error:  No code for inline procedure stored                          The compiler couldn't store code for the
       inline procedure.

Error:  Element zero of an ansi/wide- or longstring can't be accessed, use (set)length instead
       You should use setlength to set the length of an ansi/wide/longstring and length to
       get the length of such a string types

Error:  Constructors or destructors can not be called inside a 'with' clause                                           Inside
       a with clause you cannot call a constructor or destructor for the object you have in
       the with clause.



                                                                 150

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Error:  Cannot call message handler methods directly                                 A message method handler method
       cannot be called directly if it contains an explicit self argument

Error:  Jump in or outside of an exception block                             It is not allowed to jump in or out-
       side of an exception block like try..finally..end;:


         label  1;


         ...


         try
              if  not(final)  then
                 goto  1;     //  this  line  will  cause  an  error
         finally
            ...
         end;
         1:
         ...
Error:  Control flow statements aren't allowed in a finally block                                    It isn't allowed to
       use the control flow statements break, continue and exit inside a finally statement.
       The following example shows the problem:


         ...
            try
                 p;
            finally
                 ...
                 exit;    //  This  exit  ISN'T  allowed
            end;
         ...

       If the procedure p raises an exception the finally block is executed.  If the execution
       reaches the exit, it's unclear what to do:  exiting the procedure or searching for another
       exception handler

Warning:  Parameters size exceeds limit for certain cpu's                                  This indicates that you are
       declaring more than 64K of parameters, which might not be supported on other pro-
       cessor targets.

Warning:  Local variable size exceed limit for certain cpu's                                 This indicates that you
       are declaring more than 32K of local variables, which might not be supported on other
       processor targets.

Error:  Local variables size exceeds supported limit                              This indicates that you are declar-
       ing more than 32K of local variables, which is not supported by this processor.

Error:  BREAK not allowed                    You're trying to use break outside a loop construction.

Error:  CONTINUE not allowed                        You're trying to use continue outside a loop construc-
       tion.


                                                                 151

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Fatal:  Unknown compilerproc  rg1".  Check if you use the correct run time library.
       The compiler expects that the runtime library contains some subrountines.  If you see
       this error and you didn't mess with the runtime library, it's very likely that the run-
       time library you're using doesn't match the used compiler.  If you changed the runtime
       library this error means that you removed a subroutine which the compiler needs for
       internal use.
13.7          Errors  of  assembling/linking  stage


This  section  lists  errors  that  occur  when  the  compiler  is  processing  the  command  line  or
handling the configuration files.


Warning:  Source operating system redefined                             The  source  operating  system  is  rede-
        fined.

Info:  Assembling (pipe) arg1                   Assembling using a pipe to an external assembler.

Error:  Can't create assembler file:  arg1                      The mentioned file can't be created.  Check if
        you have got access permissions to create this file

Error:  Can't create object file:  arg1                    The  mentioned  file  can't  be  created.   Check  if
        you've got access permissions to create this file

Error:  Can't create archive file:  arg1                    The  mentioned  file  can't  be  created.   Check  if
        you've access permissions to create this file

Error:  Assembler arg1 not found, switching to external assembling                                          The assembler
        program was not found.  The compiler will produce a script that can be used to assem-
        ble and link the program.

Using assembler:  arg1               Information message saying which assembler is being used.

Error:  Error while assembling exitcode arg1                            There was an error while assembling the
        file using an external assembler.  Consult the documentation of the assembler tool to
        find out more information on this error.

Error:  Can't call the assembler, error arg1 switching to external assembling                                             An
        error occurred when calling an external assembler, The compiler will produce a script
        that can be used to assemble and link the program.

Info:  Assembling arg1               An informational message stating which file is being assembled.

Info:  Assembling with smartlinking arg1                          An informational message stating which file
        is being assembled using smartlinking.

Warning:  Object arg1 not found, Linking may fail !                                One of the object file is missing,
        and linking will probably fail.  Check your paths.

Warning:  Library arg1 not found, Linking may fail !                                 One of the library file is miss-
        ing, and linking will probably fail.  Check your paths.

Error:  Error while linking                Generic error while linking.

Error:  Can't call the linker, switching to external linking                                An  error  occurred  when
        calling  an  external  linker,  The  compiler  will  produce  a  script  that  can  be  used  to
        assemble and link the program.

                                                                 152

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Info:  Linking arg1           An informational message, showing which program or library is being
       linked.

Error:  Util arg1 not found, switching to external linking                                 An external tool was not
       found,  the  compiler  will  produce  a  script  that  can  be  used  to  assemble  and  link  or
       postprocess the program.

Using util arg1          An  informational  message,  showing  which  external  program  (usually  a
       postprocessor) is being used.

Error:  Creation of Executables not supported                             Creating  executable  programs  is  not
       supported for this platform, because it was not yet implemented in the compiler.

Error:  Creation of Dynamic/Shared Libraries not supported                                       Creating dynamically
       loadable libraries is not supported for this platform, because it was not yet implemented
       in the compiler.

Info:  Closing script arg1              Informational message showing when the external assembling
       an linking script is finished.

Error:  resource compiler not found, switching to external mode                                       An external resource
       compiler was not found, the compiler will produce a script that can be used to assemble,
       compile resources and link or postprocess the program.

Info:  Compiling resource arg1                   An informational message, showing which resource is be-
       ing compiled.

unit arg1 can't be statically linked, switching to smart linking                                   Statical linking was
       requested, but a unit which is not statically linkable was used.

unit arg1 can't be smart linked, switching to static linking                                  Smart linking was requested,
       but a unit which is not smart-linkable was used.

unit arg1 can't be shared linked, switching to static linking                                  Shared linking was re-
       quested, but a unit which is not shared-linkable was used.

Error:  unit arg1 can't be smart or static linked                           Smart or static linking was requested,
       but a unit which cannot be used for either was used.

Error:  unit arg1 can't be shared or static linked                           Shared or static linking was requested,
       but a unit which cannot be used for either was used.

Calling resource compiler  rg1" with  rg2  s command line                                         An informational mes-
       sage showing which command-line is used for the resource compiler.
13.8          Executable  information  messages.


This section lists all messages that the compiler emits when an executable program is pro-
duced, and only when the internal linker is used.


Fatal:  Can't post process executable arg1                          Fatal error when the compiler is unable to
        post-process an executable.

Fatal:  Can't open executable arg1                      Fatal error when the compiler cannot open the file
        for the executable.

Size of Code:  arg1 bytes                Informational message showing the size of the produced code
        section.



                                                                 153

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Size of initialized data:  arg1 bytes                  Informational message showing the size of the ini-
       tialized data section.

Size of uninitialized data:  arg1 bytes                    Informational  message  showing  the  size  of  the
       uninitialized data section.

Stack space reserved:  arg1 bytes                    Informational message showing the stack size that the
       compiler reserved for the executable.

Stack space committed:  arg1 bytes                      Informational message showing the stack size that
       the compiler committed for the executable.
13.9          Unit  loading  messages.


This section lists all messages that can occur when the compiler is loading a unit from disk
into memory.  Many of these messages are informational messages.


Unitsearch:  arg1           When you use the -vt, the compiler tells you where it tries to find unit
        files.

PPU Loading arg1               When  the  -vt  switch  is  used,  the  compiler  tells  you  what  units  it
        loads.

PPU Name:  arg1              When you use the -vu flag, the unit name is shown.

PPU Flags:  arg1            When you use the -vu flag, the unit flags are shown.

PPU Crc:  arg1            When you use the -vu flag, the unit CRC check is shown.

PPU Time:  arg1             When you use the -vu flag, the time the unit was compiled is shown.

PPU File too short              The ppufile is too short, not all declarations are present.

PPU Invalid Header (no PPU at the begin)                               A  unit  file  contains  as  the  first  three
        bytes the ascii codes of  PPU

PPU Invalid Version arg1                   This  unit  file  was  compiled  with  a  different  version  of  the
        compiler, and cannot be read.

PPU is compiled for another processor                          This unit file was compiled for a different pro-
        cessor type, and cannot be read

PPU is compiled for an other target                        This unit file was compiled for a different target,
        and cannot be read

PPU Source:  arg1              When you use the -vu flag, the unit source file name is shown.

Writing arg1          When you specify the -vu switch, the compiler will tell you where it writes
        the unit file.

Fatal:  Can't Write PPU-File                   An error occurred when writing the unit file.

Fatal:  Error reading PPU-File                    This  means  that  the  unit  file  was  corrupted,  and  con-
        tains invalid information.  Recompilation will be necessary.

Fatal:  unexpected end of PPU-File                       Unexpected  end  of  file.  This  may  mean  that  the
        PPU file is corrupted.

Fatal:  Invalid PPU-File entry:  arg1                     The  unit  the  compiler  is  trying  to  read  is  cor-
        rupted, or generated with a newer version of the compiler.



                                                                 154

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Fatal:  PPU Dbx count problem                      There is an inconsistency in the debugging information
       of the unit.

Error:  Illegal unit name:  arg1                 The name of the unit does not match the file name.

Fatal:  Too much units              Free Pascal has a limit of 1024 units in a program.  You can change
       this behavior by changing the maxunits constant in the fmodule.pas file of the compiler,
       and recompiling the compiler.

Fatal:  Circular unit reference between arg1 and arg2                                Two units are using each other
       in the interface part.  This is only allowed in the implementation part.  At least one
       unit must contain the other one in the implementation section.

Fatal:  Can't compile unit arg1, no sources available                              A unit was found that needs to
       be recompiled, but no sources are available.

Fatal:  Can't find unit arg1               You tried to use a unit of which the PPU file isn't found by
       the compiler.  Check your configuration file for the unit paths

Warning:  Unit arg1 was not found but arg2 exists                                This  error  message  is  no  longer
       used.

Fatal:  Unit arg1 searched but arg2 found                         Dos  truncation  of  8  letters  for  unit  PPU
       files may lead to problems when unit name is longer than 8 letters.

Warning:  Compiling the system unit requires the -Us switch                                      When recompiling the
       system unit (it needs special treatment), the -Us must be specified.

Fatal:  There were arg1 errors compiling module, stopping                                    When  the  compiler  en-
       counters a fatal error or too many errors in a module then it stops with this message.

Load from arg1 (arg2) unit arg3                     When you use the -vu flag, which unit is loaded from
       which unit is shown.

Recompiling arg1, checksum changed for arg2                               The unit is recompiled because the check-
       sum of a unit it depends on has changed.

Recompiling arg1, source found only                        When  you  use  the  -vu  flag,  these  messages  tell
       you why the current unit is recompiled.

Recompiling unit, static lib is older than ppufile                           When you use the -vu flag, the com-
       piler warns if the static library of the unit are older than the unit file itself.

Recompiling unit, shared lib is older than ppufile                             When  you  use  the  -vu  flag,  the
       compiler warns if the shared library of the unit are older than the unit file itself.

Recompiling unit, obj and asm are older than ppufile                                  When  you  use  the  -vu  flag,
       the compiler warns if the assembler or object file of the unit are older than the unit
       file itself.

Recompiling unit, obj is older than asm                         When you use the -vu flag, the compiler warns
       if the assembler file of the unit is older than the object file of the unit.

Parsing interface of arg1               When you use the -vu flag, the compiler warns that it starts
       parsing the interface part of the unit

Parsing implementation of arg1                     When you use the -vu flag, the compiler warns that it
       starts parsing the implementation part of the unit

Second load for unit arg1                When you use the -vu flag, the compiler warns that it starts
       recompiling a unit for the second time.  This can happend with interdepend units.



                                                                 155

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
PPU Check file arg1 time arg2                     When you use the -vu flag, the compiler show the file-
       name and date and time of the file which a recompile depends on

Warning:  Can't recompile unit arg1, but found modifed include files                                          A  unit  was
       found to have modified include files, but some source files were not found, so recompi-
       lation is impossible.

Hint:  File arg1 is newer than Release PPU file arg2                               A modified source file for a unit
       was found that was compiled with the release flag (-Ur).  The unit will not implicitly
       be recompiled because this release flag is set.

Using a unit which was not compiled with correct FPU mode                                          Trying to compile code
       while using units which were not compiled with the same floating point format mode.
       Either all code should be compiled with FPU emulation on,  or with FPU emulation
       off.

Loading interface units from arg1                     When you use the -vu flag, the compiler warns that
       it starts loading the units defined in the interface part of the unit.

Loading implementation units from arg1                           When  you  use  the  -vu  flag,  the  compiler
       warns that it starts loading the units defined in the implementation part of the unit.

Interface CRC changed for unit arg1                        When you use the -vu flag, the compiler warns
       that it the CRC calculated for the interface has been changed after the implementation
       has been parsed.

Implementation CRC changed for unit arg1                              When you use the -vu flag, the compiler
       warns that it the CRC calculated has been changed after the implementation has been
       parsed.

Finished compiling unit arg1                   When you use the -vu flag, the compiler warns that it has
       finished compiling the unit.

Add dependency of arg1 to arg2                      When you use the -vu flag, the compiler warns that
       it has added a dependency between the two units.

No reload, is caller:  arg1             When you use the -vu flag, the compiler warns that it has will
       not reload the unit because it is the unit that wants to load this unit

No reload, already in second compile:  arg1                          When you use the -vu flag, the compiler
       warns that it has will not reload the unit because it is already in a second recompile

Flag for reload:  arg1            When you use the -vu flag, the compiler warns that it has to reload
       the unit

Forced reloading           When you use the -vu flag, the compiler warns that it has is reloading
       the unit because it was required

Previous state of arg1:  arg2                When you use the -vu flag, the compiler shows the previous
       state of the unit

Already compiling arg1, setting second compile                              When you use the -vu flag, the com-
       piler  warns  that  it  starts  recompiling  a  unit  for  the  second  time.  This  can  happend
       with interdepend units.

Loading unit arg1            When you use the -vu flag, the compiler warns that it starts loading
       the unit.

Finished loading unit arg1                 When you use the -vu flag,  the compiler warns that it fin-
       ished loading the unit.



                                                                 156

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Registering new unit arg1                 When  you  use  the  -vu  flag,  the  compiler  warns  that  it  has
       found a new unit and registers it in the internal lists.

Re-resolving unit arg1              When  you  use  the  -vu  flag,  the  compiler  warns  that  it  has  to
       recalculate the internal data of the unit

Skipping re-resolving unit arg1, still loading used units                               When you use the -vu flag,
       the  compiler  warns  that  it  skips  to  recalculate  the  internal  data  of  the  unit  because
       there is no data to recalculate
13.10            Command-line  handling  errors


This  section  lists  errors  that  occur  when  the  compiler  is  processing  the  command  line  or
handling the configuration files.


Warning:  Only one source file supported                          You can specify only one source file on the
        command line.  The first one will be compiled, others will be ignored.  This may indicate
        that you forgot a '-' sign.

Warning:  DEF file can be created only for OS/2                                This  option  can  only  be  specified
        when you're compiling for OS/2

Error:  nested response files are not supported                            you  cannot  nest  response  files  with
        the @file command-line option.

Fatal:  No source file name in command line                            The compiler expects a source file name
        on the command line.

Note:  No option inside arg1 config file                       The  compiler  didn't  find  any  option  in  that
        config file.

Error:  Illegal parameter:  arg1                  You specified an unknown option.

Hint:  -?  writes help pages               When an unknown option is given, this message is diplayed.

Fatal:  Too many config files nested                     You can only nest up to 16 config files.

Fatal:  Unable to open file arg1                   The option file cannot be found.

Reading further options from arg1                       Displayed when you have notes turned on, and the
        compiler switches to another options file.

Warning:  Target is already set to:  arg1                       Displayed if more than one -T option is spec-
        ified.

Warning:  Shared libs not supported on DOS platform, reverting to static                                              If you
        specify -CD for the dos platform, this message is displayed.  The compiler supports only
        static libraries under dos

Fatal:  too many IF(N)DEFs                     the #IF(N)DEF statements in the options file are not bal-
        anced with the #ENDIF statements.

Fatal:  too many ENDIFs                  the #IF(N)DEF statements in the options file are not balanced
        with the #ENDIF statements.

Fatal:  open conditional at the end of the file                         the  #IF(N)DEF  statements  in  the  op-
        tions file are not balanced with the #ENDIF statements.

                                                                 157

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Warning:  Debug information generation is not supported by this executable                                                It is
       possible to have a compiler executable that doesn't support the generation of debugging
       info.  If you use such an executable with the -g switch, this warning will be displayed.

Hint:  Try recompiling with -dGDB                        It  is  possible  to  have  a  compiler  executable  that
       doesn't support the generation of debugging info.  If you use such an executable with
       the -g switch, this warning will be displayed.

Error:  You are using the obsolete switch arg1                            this warns you when you use a switch
       that is not needed/supported anymore.  It is recommended that you remove the switch
       to overcome problems in the future, when the switch meaning may change.

Error:  You are using the obsolete switch arg1, please use arg2                                     this warns you when
       you use a switch that is not supported anymore.  You must now use the second switch
       instead.  It is recommended that you change the switch to overcome problems in the
       future, when the switch meaning may change.

Note:  Switching assembler to default source writing assembler                                      this notifies you that
       the assembler has been changed because you used the -a switch which can't be used
       with a binary assembler writer.

Warning:  Assembler output selected  rg1" is not compatible with  rg2"

Warning:   rg1  ssembler use forced                         The assembler output selected can not generate
       object files with the correct format.  Therefore, the default assembler for this target is
       used instead.

Reading options from file arg1                   Options are also read from this file

Reading options from environment arg1                           Options are also read from this environment
       string

Handling option  rg1"                 Debug info that an option is found and will be handled

*** press enter ***

Hint:  Start of reading config file arg1                    Starting of config file parsing.

Hint:  End of reading config file arg1                     End of config file parsing.

interpreting option  rg1"

interpreting firstpass option  rg1"

interpreting file option  rg1"

Reading config file  rg1"

found source file name  rg1"                    Additional infos about options, displayed when you have
       debug option turned on.

Error:  Unknown code page

Fatal:  Config file arg1 is a directory                   Directories can not be used as configuration files.
13.11            Assembler  reader  errors.


This section lists the errors that are generated by the inline assembler reader.  They are not
the messages of the assembler itself.



                                                                 158

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
13.11.1          General  assembler  errors

Divide by zero in asm evaluator                     This fatal error is reported when a constant assembler
        expressions does a division by zero.

Evaluator stack overflow, Evaluator stack underflow                                 These fatal errors are reported
        when  a  constant  assembler  expression  is  too  big  to  evaluate  by  the  constant  parser.
        Try reducing the number of terms.

Invalid numeric format in asm evaluator                           This fatal error is reported when a non-numeric
        value is detected by the constant parser.  Normally this error should never occur.

Invalid Operator in asm evaluator                       This  fatal  error  is  reported  when  a  mathematical
        operator is detected by the constant parser.  Normally this error should never occur.

Unknown error in asm evaluator                       This fatal error is reported when an internal error is
        detected by the constant parser.  Normally this error should never occur.

Invalid numeric value               This  warning  is  emitted  when  a  conversion  from  octal,binary  or
        hexadecimal to decimal is outside of the supported range.

Escape sequence ignored                  This error is emitted when a non ANSI C escape sequence is
        detected in a C string.

Asm syntax error - Prefix not found                        This occurs when trying to use a non-valid prefix
        instruction

Asm syntax error - Trying to add more than one prefix                                     This  occurs  when  you  try
        to add more than one prefix instruction

Asm syntax error - Opcode not found                           You  have  tried  to  use  an  unsupported  or  un-
        known opcode

Constant value out of bounds                     This  error  is  reported  when  the  constant  parser  deter-
        mines that the value you are using is out of bounds,  either with the opcode or with
        the constant declaration used.

Non-label pattern contains @                    This only applied to the m68k and Intel styled assembler,
        this is reported when you try to use a non-label identifier with a '@' prefix.

Internal error in Findtype()

Internal Error in ConcatOpcode()

Internal Errror converting binary

Internal Errror converting hexadecimal

Internal Errror converting octal

Internal Error in BuildScaling()

Internal Error in BuildConstant()

internal error in BuildReference()

internal error in HandleExtend()

Internal error in ConcatLabeledInstr()                         These  errors  should  never  occur,  if  they  do
        then  you  have  found  a  new  bug  in  the  assembler  parsers.  Please  contact  one  of  the
        developers.
                                                                 159

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Opcode not in table, operands not checked                            This warning only occurs when compiling
       the  system  unit,  or  related  files.   No  checking  is  performed  on  the  operands  of  the
       opcodes.

@CODE and @DATA not supported                              This Turbo Pascal construct is not supported.

SEG and OFFSET not supported                          This Turbo Pascal construct is not supported.

Modulo not supported                 Modulo constant operation is not supported.

Floating point binary representation ignored

Floating point hexadecimal representation ignored

Floating point octal representation ignored                          These warnings occur when a floating point
       constant are declared in a base other then decimal.  No conversion can be done on these
       formats.  You should use a decimal representation instead.

Identifier supposed external                 This  warning  occurs  when  a  symbol  is  not  found  in  the
       symolb table, it is therefore considered external.

Functions with void return value can't return any value in asm code                                          Only routines
       with a return value can have a return value set.

Error in binary constant

Error in octal constant

Error in hexadecimal constant

Error in integer constant                These errors are reported when you tried using an invalid con-
       stant expression, or that the value is out of range.

Invalid labeled opcode

Asm syntax error - error in reference

Invalid Opcode

Invalid combination of opcode and operands

Invalid size in reference

Invalid middle sized operand

Invalid three operand opcode

Assembler syntax error

Invalid operand type              You  tried  using  an  invalid  combination  of  opcode  and  operands,
       check the syntax and if you are sure it is correct, please contact one of the developers.

Unknown identifier             The identifier you are trying to access does not exist, or is not within
       the current scope.

Trying to define an index register more than once

Trying to define a segment register twice

Trying to define a base register twice                      You are trying to define an index/segment reg-
       ister more then once.

                                                                 160

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Invalid field specifier           The record or object field you are trying to access does not exist,
       or is incorrect.

Invalid scaling factor

Invalid scaling value

Scaling value only allowed with index                       Allowed scaling values are 1,2,4 or 8.

Cannot use SELF outside a method                          You  are  trying  to  access  the  SELF  identifier  for
       objects outside a method.

Invalid combination of prefix and opcode                          This opcode cannot be prefixed by this in-
       struction

Invalid combination of override and opcode                            This opcode cannot be overriden by this
       combination

Too many operands on line                   At most three operand instructions exist on the m68k, and
       i386, you are probably trying to use an invalid syntax for this opcode.

Duplicate local symbol               You are trying to redefine a local symbol, such as a local label.

Unknown label identifer

Undefined local symbol

local symbol not found inside asm statement                             This label does not seem to have been
       defined in the current scope

Assemble node syntax error

Not a directive or local symbol                   The assembler statement is invalid, or you are not using
       a recognized directive.
13.11.2          I386  specific  errors

repeat prefix and a segment override on <= i386 ...                               A problem with interrupts and a
        prefix instruction may occur and may cause false results on 386 and earlier computers.

Fwait can cause emulation problems with emu387                                   This warning is reported when us-
        ing the FWAIT instruction, it can cause emulation problems on systems which use the
        em387.dxe emulator.

You need GNU as version >= 2.81 to compile this MMX code                                            MMX assembler code
        can only be compiled using GAS v2.8.1 or later.

NEAR ignored

FAR ignored           NEAR and FAR are ignored in the intel assemblers, but are still accepted for
        compatiblity with the 16-bit code model.

Invalid size for MOVSX/MOVZX

16-bit base in 32-bit segment

16-bit index in 32-bit segment                    16-bit addressing is not supported, you must use 32-bit
        addressing.

Constant reference not allowed                     It is not allowed to try to address a constant memory
        address in protected mode.



                                                                 161

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
Segment overrides not supported                       Intel  style  (eg:  rep  ds  stosb)  segment  overrides  are
       not support by the assembler parser.

Expressions of the form [sreg:reg...                    are  currently  not  supported]  To  access  a  memory
       operand  in  a  different  segment,  you  should  use  the  sreg:[reg...]   snytax  instead  of
       [sreg:reg...]

Size suffix and destination register do not match                             In intel AT&T syntax, you are us-
       ing a register size which does not concord with the operand size specified.

Invalid assembler syntax.  No ref with brackets

 Trying to use a negative index register

 Local symbols not allowed as references

 Invalid operand in bracket expression

 Invalid symbol name:

 Invalid Reference syntax

 Invalid string as opcode operand:

 Null label references are not allowed

 Using a defined name as a local label

 Invalid constant symbol

 Invalid constant expression

 / at beginning of line not allowed

 NOR not supported

 Invalid floating point register name

 Invalid floating point constant:

 Asm syntax error - Should start with bracket

 Asm syntax error - register:

 Asm syntax error - in opcode operand

 Invalid String expression

 Constant expression out of bounds

 Invalid or missing opcode

 Invalid real constant expression

 Parenthesis are not allowed

 Invalid Reference

 Cannot use  ___SELF outside a method

 Cannot use  ___OLDEBP outside a nested procedure

 Invalid segment override expression
                                                                 162

___________________________________________________________________________CHAPTER_13.___COMPILER_MESSAGES_________________________*
 *___
 Strings not allowed as constants

 Switching sections is not allowed in an assembler block

 Invalid global definition

 Line separator expected

 Invalid local common definition

 Invalid global common definition

 assembler code not returned to text

 invalid opcode size

 Invalid character:  <

 Invalid character:  >

 Unsupported opcode

 Invalid suffix for intel assembler

 Extended not supported in this mode

 Comp not supported in this mode

 Invalid Operand:

 Override operator not supported
13.11.3          m68k  specific  errors.

Increment and Decrement mode not allowed together                                      You are trying to use dec/inc
        mode together.

Invalid Register list in movem/fmovem                           The  register  list  is  invalid,  normally  a  range
        of registers should be separated by - and individual registers should be separated by a
        slash.

Invalid Register list for opcode

68020+ mode required to assemble


                                                                 163


Chapter   14


Run-time   errors



Applications generated by Free Pascal might generate Run-time error when certain abnormal
conditions are detected in the application.  This appendix lists the possible run-time errors
and gives information on why they might be produced.


1 Invalid function number                  An invalid operating system call was attempted.

2 File not found           Reported when trying to erase, rename or open a non-existent file.

3 Path not found             Reported by the directory handling routines when a path does not exist
        or is invalid.  Also reported when trying to access a non-existent file.

4 Too many open files                The maximum number of currently opened files by your process
        has been reached.  Certain operating systems limit the number of files which can be
        opened concurrently, and this error can occur when this limit has been reached.

5 File access denied             Permission accessing the file is denied.  This error might be caused
        by several reasons:

            o  Trying to open for writing a file which is read only, or which is actually a directory.

            o  File is currently locked or used by another process.

            o  Trying to create a new file, or directory while a file or directory of the same name
               already exists.

            o  Trying to read from a file which was opened in write only mode.

            o  Trying to write from a file which was opened in read only mode.

            o  Trying to remove a directory or file while it is not possible.

            o  No permission to access the file or directory.

6 Invalid file handle            If this happens, the file variable you are using is trashed; it indicates
        that your memory is corrupted.

12 Invalid file access code               Reported  when  a  reset  or  rewrite  is  called  with  an  invalid
        FileMode value.

15 Invalid drive number                 The number given to the Getdir or ChDir function specifies a
        non-existent disk.

16 Cannot remove current directory                         Reported when trying to remove the currently ac-
        tive directory.

                                                             164

________________________________________________________________________________CHAPTER_14.___RUN-TIME_ERRORS______________________*
 *___
17 Cannot rename across drives                      You cannot rename a file such that it would end up on
       another disk or partition.

100 Disk read error             An error occurred when reading from disk.  Typically when you try
       to read past the end of a file.

101 Disk write error             Reported when the disk is full, and you're trying to write to it.

102 File not assigned             This is reported by Reset, Rewrite, Append, Rename and Erase, if
       you call them with an unassigned file as a parameter.

103 File not open            Reported  by  the  following  functions  :  Close,  Read,  Write,  Seek,
       EOf,  FilePos,  FileSize,  Flush,  BlockRead,  and  BlockWrite  if  the  file  is  not
       open.

104 File not open for input                 Reported  by  Read,  BlockRead,  Eof,  Eoln,  SeekEof  or
       SeekEoln if the file is not opened with Reset.

105 File not open for output                  Reported by write if a text file isn't opened with Rewrite.

106 Invalid numeric format                  Reported when a non-numeric value is read from a text file,
       when a numeric value was expected.

150 Disk is write-protected                 (Critical error)

151 Bad drive request struct length                       (Critical error)

152 Drive not ready              (Critical error)

154 CRC error in data                (Critical error)

156 Disk seek error             (Critical error)

157 Unknown media type                    (Critical error)

158 Sector Not Found                (Critical error)

159 Printer out of paper                (Critical error)

160 Device write fault              (Critical error)

161 Device read fault              (Critical error)

162 Hardware failure              (Critical error)

200 Division by zero             The application attempted to divide a number by zero.

201 Range check error                If you compiled your program with range checking on, then you
       can get this error in the following cases:

           1.  An array was accessed with an index outside its declared range.

           2.  Trying to assign a value to a variable outside its range (for instance an enumerated
               type).

202 Stack overflow error                The stack has grown beyond its maximum size (in which case
        the size of local variables should be reduced to avoid this error), or the stack has become
        corrupt.  This error is only reported when stack checking is enabled.


                                                                 165

________________________________________________________________________________CHAPTER_14.___RUN-TIME_ERRORS______________________*
 *___
203 Heap overflow error                The  heap  has  grown  beyond  its  boundaries.   This  is  caused
       when trying to allocate memory exlicitly with New, GetMem or ReallocMem, or when a
       class or object instance is created and no memory is left.  Please note that, by default,
       Free Pascal provides a growing heap, i.e.  the heap will try to allocate more memory if
       needed.  However, if the heap has reached the maximum size allowed by the operating
       system or hardware, then you will get this error.

204 Invalid pointer operation                  This you will get if you call Dispose or Freemem with an
       invalid pointer (notably, Nil)

205 Floating point overflow                 You are trying to use or produce too large real numbers.

206 Floating point underflow                   You are trying to use or produce too small real numbers.

207 Invalid floating point operation                     Can occur if you try to calculate the square root
       or logarithm of a negative number.

210 Object not initialized               When compiled with range checking on, a program will report
       this error if you call a virtual method without having called istr constructor.

211 Call to abstract method                   Your program tried to execute an abstract virtual method.
       Abstract methods should be overridden, and the overriding method should be called.

212 Stream registration error                   This occurs when an invalid type is registered in the ob-
       jects unit.

213 Collection index out of range                     You  are  trying  to  access  a  collection  item  with  an
       invalid index (objects unit).

214 Collection overflow error                  The collection has reached its maximal size, and you are
       trying to add another element (objects unit).

215 Arithmetic overflow error                   This error is reported when the result of an arithmetic
       operation  is  outside  of  its  supported  range.  Contrary  to  Turbo  Pascal,  this  error  is
       only  reported  for  32-bit  or  64-bit  arithmetic  overflows.  This  is  due  to  the  fact  that
       everything is converted to 32-bit or 64-bit before doing the actual arithmetic operation.

216 General Protection fault                  The application tried to access invalid memory space.  This
       can be caused by several problems:

           1.  Deferencing a nil pointer

           2.  Trying to access memory which is out of bounds (for example, calling move with
               an invalid length).

217 Unhandled exception occurred                         An exception occurred, and there was no exception
        handler present.  The sysutils unit installs a default exception handler which catches
        all excpetions and exits gracefully.

219 Invalid typecast              Thrown when an invalid typecast is attempted on a class using the
        as operator.  This error is also thrown when an object or class is typecast to an invalid
        class or object and a virtual method of that class or object is called.  This last error is
        only detected if the -CR compiler option is used.

227 Assertion failed error                An assertion failed, and no AssertErrorProc procedural vari-
        able was installed.

                                                                 166


Chapter   15


A   sample   gdb.ini   file



Here you have a sample gdb.ini file listing, which gives better results when using gdb.  Under
linux you should put this in a .gdbinit file in your home directory or the current directory..


set  print  demangle  off
set  gnutarget  auto
set  verbose  on
set  complaints  1000
dir  ./rtl/dosv2
set  language  c++
set  print  vtbl  on
set  print  object  on
set  print  sym  on
set  print  pretty  on
disp  /i  $eip


define  pst
set  $pos=&$arg0
set  $strlen  =  {byte}$pos
print  {char}&$arg0.st@($strlen+1)
end


document  pst
    Print  out  a  pascal  string
end



                                                             167


Chapter   16


Options   and   settings



In  table  (16.1  )  a  summary  of  available  boolean  compiler  directives  and  the  corresponding
command-line options are listed.  Other directives and the corresponding options are shown
in table (16.2  ).  For more information about the command-line options, chapter 5 , page 22 .
For more information about the directives, see the Programmers guide          .



                                  Table 16.1:  Boolean Options and directves


       __Short___________long_____________________________________Opt_______Explanation________________________________
         $A[+/-]        $ALIGN[ON/OFF]                                     Data alignment
         $B[+/-]        $BOOLEVAL[ON/OFF]                                  Boolean evaluation mode
         $C[+/-]        $ASSERTIONS[ON/OFF]                       -Sa      Include assertions
         $D[+/-]        $DEBUGINFO[ON/OFF]                        -g       Include debug info
         $E[+/-]                                                           Coprocessor emulation
         $F[+/-]                                                           Far or near function (ignored)
         $G[+/-]                                                           generate 80286 code (ignored)
                        $GOTO[ON/OFF]                             -Sg      Support GOTO and Label
                        $HINTS[ON/OFF]                            -vh      Show hints
         $H[+/-]        $LONGSTRINGS[ON/OFF]                      -Sh      Use ansistrings
         $I[+/-]        $IOCHECKS[ON/OFF]                         -Ci      Check I/O operation result
                        $INLINE[ON/OFF]                           -Si      Allow inline code
         $L[+/-]        $LOCALSYMBOLS[ON/OFF]                              Local symbol information
         $M[+/-]        $TYPEINFO[ON/OFF]                                  Generate RTTI for classes
                        $MMX[ON/OFF]                                       Intel MMX support
         $N[+/-]                                                           Floating point sypport
                        $NOTES[ON/OFF]                            -vn      Emit notes
         $O[+/-]                                                           Support overlays (ignored)
         $P[+/-]        $OPENSTRINGS[ON/OFF]                               Support open strings
         $Q[+/-]        $OVERFLOWCHECKS[ON/OFF]                   -Co      Overflow checking
         $R[+/-]        $RANGECHEKS[ON/OFF]                       -Cr      Range checks
         $S[+/-]                                                  -Ct      Stack checks
                        $SMARTLINK[ON/OFF]                        -CX      Use smartlinking
                        $STATIC[ON/OFF]                           -St      Allow use of  static
       __$T[+/-]________$TYPEDADDRESS[ON/OFF]______________________________Types_addresses_____________________________



                                                             168

______________________________________________________________________CHAPTER_16.___OPTIONS_AND_SETTINGS___________________________*
 *___


                                       Table 16.2:  Options and directives


            __Short________________long_____________________Opt______Explanation__________________________________
                                  $APPTYPE                  -W       Application type (Win32/OS2)
                                  $ASMMODE                  -R       Assembler reader modus
                                  $DEFINE                   -d       Define symbol
                                  $DESCRIPTION                       Set program description
                                  $ELSE                              Conditional compilation switch
                                  $ENDIF                             Conditional compilation end
                                  $FATAL                             report fatal error
                                  $HINT                              Emit hint message
              $I  file            $INCLUDE                           Include file or literal text
                                  $IF                                Conditional compilation start
                                  $IFDEF  NAME                       Conditional compilation start
                                  $IFNDEF                            Conditional compilation start
                                  $IFOPT                             Conditional compilation start
                                  $INCLUDEPATH              -Fi      set include path
                                  $INFO                              Emit information message
              $L  file            $LINK                              Link object file
                                  $LIBRARYPATH              -Fl      Set library path
                                  $LINKLIB  name                     link library
              $M  MIN,MAX         $MEMORY                            Set memory sizes
                                  $MACRO                    -Sm      Allow use of macros
                                  $MESSAGE                           Emit message
                                  $MODE                              Set compatibility mode
                                  $NOTE                              Emite note message
                                  $OBJECTPATH               -Fo      Set object path
                                  $OUTPUT                   -A       Set output format
                                  $PACKENUM                          Enumeration type size
                                  $PACKRECORDS                       Record element alignment
                                  $SATURATION                        Saturation (ignored)
                                  $STOP                              Stop compilation
            ______________________$UNDEF____________________-u_______Undefine_symbol______________________________


                                                                 169
