

Free  Pascal

Programmers'  manual

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

                                        Programmers' manual for Free Pascal, version 1.0.0

                                                                                                                       1.8

                                                                                                            July 2000


Micha"el Van Canneyt
______________________________________________________________________________________________________________________________



Contents
1   Compiler directives                                                                                       10

    1.1    Local directives  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    10

           1.1.1      $A or $ALIGN: Align Data   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    10

           1.1.2      $ASMMODE : Assembler mode  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    10

           1.1.3      $B or $BOOLEVAL: Complete boolean evaluation  .  .  .  .  .  .  .  .  .  .  .  .  .    11

           1.1.4      $C or $ASSERTIONS : Assertion support    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    11

           1.1.5      $DEFINE : Define a symbol .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    11

           1.1.6      $ELSE : Switch conditional compilation .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    12

           1.1.7      $ENDIF : End conditional compilation   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    12

           1.1.8      $ERROR : Generate error message   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    12

           1.1.9      $F : Far or near functions   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    12

           1.1.10     $FATAL : Generate fatal error message   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    13

           1.1.11     $GOTO : Support Goto and Label  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    13

           1.1.12     $H or $LONGSTRINGS : Use AnsiStrings  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    14

           1.1.13     $HINT : Generate hint message   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    14

           1.1.14     $HINTS : Emit hints   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    14

           1.1.15     $IF : Start conditional compilation  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    14

           1.1.16     $IFDEF  Name :  Start conditional compilation   .  .  .  .  .  .  .  .  .  .  .  .  .  .    14

           1.1.17     $IFNDEF : Start conditional compilation   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    14

           1.1.18     $IFOPT : Start conditional compilation  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    15

           1.1.19     $INFO : Generate info message   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    15

           1.1.20     $INLINE : Allow inline code. .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    15

           1.1.21     $I or $IOCHECKS : Input/Output checking  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    15

           1.1.22     $I or $INCLUDE : Include file   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    16

           1.1.23     $I or $INCLUDE : Include compiler info  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    16

           1.1.24     $I386_XXX : Specify assembler format   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    17

           1.1.25     $L or $LINK : Link object file   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    17

           1.1.26     $LINKLIB : Link to a library .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    18

           1.1.27     $M or $TYPEINFO : Generate type info   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    18

           1.1.28     $MACRO : Allow use of macros.  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    18

                                                              1

___________________________________________________________________________________________________________________CONTENTS________*
 *___
           1.1.29     $MAXFPUREGISTERS : Maximum number of FPU registers for variables     19

           1.1.30     $MESSAGE : Generate info message   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    19

           1.1.31     $MMX : Intel MMX support .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    19

           1.1.32     $NOTE : Generate note message   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    20

           1.1.33     $NOTES : Emit notes   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    20

           1.1.34     $OUTPUT_FORMAT : Specify the output format   .  .  .  .  .  .  .  .  .  .  .  .  .  .    20

           1.1.35     $P or $OPENSTRINGS : Use open strings .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    21

           1.1.36     $PACKENUM : Minimum enumeration type size   .  .  .  .  .  .  .  .  .  .  .  .  .  .    21

           1.1.37     $PACKRECORDS : Alignment of record elements  .  .  .  .  .  .  .  .  .  .  .  .  .  .    22

           1.1.38     $Q $OVERFLOWCHECKS: Overflow checking  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    22

           1.1.39     $R or $RANGECHECKS : Range checking   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    22

           1.1.40     $SATURATION : Saturation operations  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    22

           1.1.41     $SMARTLINK : Use smartlinking   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    23

           1.1.42     $STATIC : Allow use of  Static keyword.  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    23

           1.1.43     $STOP : Generate fatal error message  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    23

           1.1.44     $T or $TYPEDADDRESS : Typed address operator (@)   .  .  .  .  .  .  .  .  .  .    23

           1.1.45     $UNDEF : Undefine a symbol  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    23

           1.1.46     $V or $VARSTRINGCHECKS : Var-string checking   .  .  .  .  .  .  .  .  .  .  .  .  .    24

           1.1.47     $WAIT : Wait for enter key press   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    24

           1.1.48     $WARNING : Generate warning message  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    24

           1.1.49     $WARNINGS : Emit warnings  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    24

           1.1.50     $X or $EXTENDEDSYNTAX : Extended syntax   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    24

    1.2    Global directives   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    25

           1.2.1      $APPTYPE : Specify type of application (Win32 only)  .  .  .  .  .  .  .  .  .  .    25

           1.2.2      $D or $DEBUGINFO: Debugging symbols  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    25

           1.2.3      $DESCRIPTION   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 25

           1.2.4      $E : Emulation of coprocessor  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    26

           1.2.5      $G : Generate 80286 code   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    26

           1.2.6      $INCLUDEPATH : Specify include path.   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    26

           1.2.7      $L or $LOCALSYMBOLS: Local symbol information   .  .  .  .  .  .  .  .  .  .  .  .    27

           1.2.8      $LIBRARYPATH : Specify library path.  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    27

           1.2.9      $M or $MEMORY: Memory sizes   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    27

           1.2.10     $MODE : Set compiler compatibility mode .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    27

           1.2.11     $N : Numeric processing  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    28

           1.2.12     $O : Overlay code generation   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    28

           1.2.13     $OBJECTPATH : Specify object path. .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    28

           1.2.14     $S : Stack checking  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 28

           1.2.15     $UNITPATH : Specify unit path.   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    28

           1.2.16     $W or $STACKFRAMES : Generate stackframes  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    29

           1.2.17     $Y or $REFERENCEINFO : Insert Browser information   .  .  .  .  .  .  .  .  .  .    29



                                                                 2

___________________________________________________________________________________________________________________CONTENTS________*
 *___
2   Using conditionals, messages and macros                                                     30

    2.1    Conditionals .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    30

    2.2    Messages    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    34

    2.3    Macros .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .    35


3   Using Assembly language                                                                             37

    3.1    Intel syntax  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    37

    3.2    AT&T Syntax .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  40

    3.3    Calling mechanism  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    *
 *41

           3.3.1       Ix86 calling conventions    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    42

           3.3.2       M680x0 calling conventions    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    42

    3.4    Signalling changed registers   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    43

    3.5    Register Conventions  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    *
 *43

           3.5.1       Intel x86 version    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  43

           3.5.2       Motorola 680x0 version     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    43


4   Linking issues                                                                                                44

    4.1    Using external functions or procedures  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    44

    4.2    Using external variables   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    46

    4.3    Linking to an object file   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    *
 *47

    4.4    Linking to a library .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  48

    4.5    Making libraries    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    49

           4.5.1      Exporting functions   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    49

           4.5.2      Exporting variables .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    *
 *50

           4.5.3      Compiling libraries  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 51

           4.5.4      Moving units into a library   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    51

           4.5.5      Unit searching strategy   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    51

    4.6    Using smart linking .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 52


5   Objects                                                                                                          53

    5.1    Constructor and Destructor calls   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    53

    5.2    Memory storage of objects  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    53

    5.3    The Virtual Method Table  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    54


6   Generated code                                                                                             55

    6.1    Units .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .    55

    6.2    Programs   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    56


7   Intel MMX support                                                                                      57

    7.1    What is it about ?   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  57

    7.2    Saturation support  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 58

    7.3    Restrictions of MMX support  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    58



                                                                 3

___________________________________________________________________________________________________________________CONTENTS________*
 *___
    7.4    Supported MMX operations  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    59

    7.5    Optimizing MMX support  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    59


8   Memory issues                                                                                              60

    8.1    The 32-bit model. .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  60

    8.2    The stack   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .    61

           8.2.1       Intel x86 version    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  61

           8.2.2       Motorola 680x0 version     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    62

    8.3    The heap   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .    62

           8.3.1      The heap grows .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 62

           8.3.2      Using Blocks   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    63

           8.3.3      Using the split heap   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    *
 *63

           8.3.4      Debugging the heap   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    64

           8.3.5      Writing your own memory manager   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    65

    8.4    Using dos memory under the Go32 extender   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    68


9   Resource strings                                                                                            69

    9.1    Introduction .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    69

    9.2    The resource string file  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 69

    9.3    Updating the string tables  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    71

    9.4    GNU gettext   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    72

    9.5    Caveat  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .    73


10  Optimizations                                                                                                74

    10.1     Non processor specific    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    *
 *74

           10.1.1      Constant folding    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 74

           10.1.2      Constant merging   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    *
 *74

           10.1.3      Short cut evaluation    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    74

           10.1.4      Constant set inlining   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    74

           10.1.5      Small sets   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    75

           10.1.6      Range checking   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 75

           10.1.7      Shifts instead of multiply or divide    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    75

           10.1.8      Automatic alignment   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    75

           10.1.9     Smart linking  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    75

           10.1.10     Inline routines  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    76

           10.1.11     Case optimization     .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    *
 *76

           10.1.12     Stack frame omission   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    76

           10.1.13     Register variables   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  76

           10.1.14     Intel x86 specific    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   76

           10.1.15     Motorola 680x0 specific    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    78

    10.2   Optimization switches   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    78
                                                                 4

___________________________________________________________________________________________________________________CONTENTS________*
 *___
    10.3   Tips to get faster code  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    *
 *79

    10.4     Floating point   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    80

           10.4.1      Intel x86 specific    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   80

           10.4.2      Motorola 680x0 specific    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    80


11  Programming libraries                                                                                  81

    11.1   Introduction .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    81

    11.2   Creating a library    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   81

    11.3   Using a library in a pascal program .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    82

    11.4   Using a pascal library from a C program  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    84


12  Using Windows resources                                                                             86

    12.1   The resource directive $R   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    86

    12.2   Creating resources   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *  86

    12.3   Using string tables.  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 *   87

    12.4   Inserting version information   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    87

    12.5   Inserting an application icon    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    88

    12.6   Using a pascal preprocessor   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    88


A   Anatomy of a unit file                                                                                   90

    A.1    Basics   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .    90

    A.2    reading ppufiles  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    90

    A.3    The Header  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    91

    A.4    The sections .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    92

    A.5    Creating ppufiles   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    93


B   Compiler and RTL source tree structure                                                      95

    B.1    The compiler source tree  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    95

    B.2    The RTL source tree  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    95


C   Compiler limits                                                                                             97


D   Compiler modes                                                                                            98

    D.1    FPC mode .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    98

    D.2    TP mode   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .    98

    D.3    Delphi mode    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.    99

    D.4    GPC mode   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *    99

    D.5    OBJFPC mode  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    *
 *99


E   Using  fpcmake                                                                                              101

    E.1    Introduction .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  101

    E.2    Usage   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  101

                                                                 5

___________________________________________________________________________________________________________________CONTENTS________*
 *___
    E.3    Format of the configuration file  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  101

           E.3.1      Clean   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  102

           E.3.2      Defaults  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  102

           E.3.3      Dirs   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  102

           E.3.4      Info   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  103

           E.3.5      Install  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  103

           E.3.6      Libs   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  .  104

           E.3.7      Packages .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  104

           E.3.8      Postsettings  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  104

           E.3.9      Presettings   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  104

           E.3.10     Rules   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  104

           E.3.11     Sections  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  104

           E.3.12     Targets   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  .  105

           E.3.13     Tools    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  .  106

           E.3.14     Zip  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  .  .  106

    E.4    Programs needed to use the generated makefile   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  106

    E.5    Variables that affect the generated makefile   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  107

           E.5.1      Environment variables  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  107

           E.5.2      Directory variables  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *08

           E.5.3      Compiler command-line variables    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  108

    E.6    Variables set by fpcmake  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  108

           E.6.1      Directory variables  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *08

           E.6.2      Target variables    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 109

           E.6.3      Compiler command-line variables  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  110

           E.6.4      Program names  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  1*
 *10

           E.6.5      File extensions   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  111

           E.6.6      Target files   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  .  112

    E.7    Rules and targets created by fpcmake .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  112

           E.7.1      Pattern rules   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *.  112

           E.7.2      Build rules   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  112

           E.7.3      Cleaning rules    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  113

           E.7.4      archiving rules   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .*
 *  113

           E.7.5      Informative rules  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  *
 *113


F   Compiling the compiler yourself                                                                 114

    F.1    Introduction .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * .  114

    F.2    Before you begin   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  . *
 * 114

    F.3    Compiling using make   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  115

    F.4    Compiling by hand  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  116

           F.4.1      Compiling the RTL    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  116
                                                                 6

___________________________________________________________________________________________________________________CONTENTS________*
 *___
           F.4.2      Compiling the compiler   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  117



                                                                 7



List   of   Tables



    1.1    Formats generated by the x86 compiler .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    21


    2.1    Symbols defined by the compiler.  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    31

    2.2    Predefined macros   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .   *
 * 36


    3.1    Calling mechanisms in Free Pascal   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    42


    5.1    Object memory layout  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    54

    5.2    Virtual Method Table memory layout   .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    54


    8.1    Stack frame when calling a procedure    .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    61


    F.1    Possible defines when compiling FPC  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  118



                                                              8

___________________________________________________________________________________________________________LIST_OF_TABLES__________*
 *___
About  this  document


This is the programmer's manual for Free Pascal.

It describes some of the peculiarities of the Free Pascal compiler, and provides a glimpse of
how the compiler generates its code, and how you can change the generated code.  It will not,
however, provide you with a detailed account of the inner workings of the compiler, nor will
it tell you how to use the compiler (described in the Users' guide).  It also will not describe
the inner workings of the Run-Time Library (RTL). The best way to learn about the way
the RTL is implemented is from the sources themselves.

The things described here are useful if you want to do things which need greater flexibility
than the standard Pascal language constructs (described in the Reference guide).

Since the compiler is continuously under development, this document may get out of date.
Wherever possible, the information in this manual will be updated.  If you find something
which isn't correct, or you think something is missing, feel free to contact me1 .

___________________________________________________1
     at Michael.VanCanneyt@wisa.be



                                                                 9


Chapter   1


Compiler   directives



Free Pascal supports compiler directives in your source file.  They are not the same as Turbo
Pascal  directives,  although  some  are  supported  for  compatibility.   There  is  a  distinction
between  local  and  global  directives;  local  directives  take  effect  from  the  moment  they  are
encountered, global directives have an effect on all of the compiled code.

Many switches have a long form also.  If they do, then the name of the long form is given
also.  For long switches, the + or - character to switch the option on or off, may be replaced
by ON or OFF keywords.

Thus {$I+} is equivalent to {$IOCHECKS  ON} or {$IOCHECKS  +} and {$C-} is equivalent to
{$ASSERTIONS  OFF} or {$ASSERTIONS  -}

The long forms of the switches are the same as their Delphi counterparts.
1.1        Local  directives


Local directives can occur more than once in a unit or program, If they have a command-line
counterpart, the command-line artgument is restored as the default for each compiled file.
The local directives influence the compiler's behaviour from the moment they're encountered
until the moment another switch annihilates their behaviour, or the end of the current unit
or program is reached.
1.1.1       $A  or  $ALIGN:  Align  Data

This switch is recognized for Turbo Pascal Compatibility, but is not yet implemented.  The
alignment of data will be different in any case, since Free Pascal is a 32-bit compiler.
1.1.2       $ASMMODE  :  Assembler  mode

The {$ASMMODE  XXX} directive informs the compiler what kind of assembler it can expect in
an asm block.  The XXX should be replaced by one of the following:


att    Indicates that asm blocks contain AT&T syntax assembler.

intel    Indicates that asm blocks contain Intel syntax assembler.

direct     Tells the compiler that asm blocks should be copied directly to the assembler file.


                                                             10

______________________________________________________________________________________________1.1.___LOCAL_DIRECTIVES______________*
 *___
These  switches  are  local,  and  retain  their  value  to  the  end  of  the  unit  that  is  compiled,
unless they are replaced by another directive of the same type.  The command-line switch
that corresponds to this switch is -R.

The default assembler reader is the AT&T reader.
1.1.3       $B  or  $BOOLEVAL:  Complete  boolean  evaluation

This switch is understood by the Free Pascal compiler, but is ignored.  The compiler always
uses  shortcut  evaluation,  i.e.   the  evaluation  of  a  boolean  expression  is  stopped  once  the
result of the total exression is known with certainty.

So, in the following example, the function Bofu, which has a boolean result, will never get
called.


If  False  and  Bofu  then
   ...


This has as a consequence that any additional actions that are done by Bofu are not executed.
1.1.4       $C  or  $ASSERTIONS  :  Assertion  support

The {$ASSERTION} switch determines if assert statements are compiled into the binary or
not.  If the switch is on, the statement


Assert(BooleanExpression,AssertMessage);


Will be compiled in the binary.  If te BooleanExpression evaluates to False, the RTL will
check  if  the  AssertErrorProc  is  set.  If  it  is  set,  it  will  be  called  with  as  parameters  the
AssertMessage message, the name of the file, the LineNumber and the address.  If it is not
set, a runtime error 227 is generated.

The AssertErrorProc is defined as


Type
   TAssertErrorProc=procedure(const  msg,fname:string;lineno,erroraddr:longint);
Var
   AssertErrorProc  =  TAssertErrorProc;


This can be used mainly for debugging purposes.  The SYSTEM unit sets the AssertErrorProc
to a handler that displays a message on stderr and simply exits.  The SYSUTILS unit catches
the run-time error 227 and raises an EAssertionFailed exception.
1.1.5       $DEFINE  :  Define  a  symbol

The directive


{$DEFINE  name}


defines the symbol name.  This symbol remains defined until the end of the current module
(i.e.  unit or program), or until a $UNDEF  name directive is encountered.

If  name is already defined, this has no effect.  Name is case insensitive.

The symbols that are defined in a unit, are not saved in the unit file, so they are also not
exported from a unit.



                                                                 11

______________________________________________________________________________________________1.1.___LOCAL_DIRECTIVES______________*
 *___
1.1.6       $ELSE  :  Switch  conditional  compilation

The  {$ELSE  }  switches  between  compiling  and  ignoring  the  source  text  delimited  by  the
preceding  {$IFxxx} and following  {$ENDIF}.  Any text after the ELSE keyword but before
the brace is ignored:


{$ELSE  some  ignored  text}


is the same as


{$ELSE}


This is useful for indication what switch is meant.
1.1.7       $ENDIF  :  End  conditional  compilation

The  {$ENDIF}  directive  ends  the  conditional  compilation  initiated  by  the  last  {$IFxxx}
directive.  Any text after the ENDIF keyword but before the closing brace is ignored:


{$ENDIF  some  ignored  text}


is the same as


{$ENDIF}


This is useful for indication what switch is meant to be ended.
1.1.8       $ERROR  :  Generate  error  message

The following code


{$ERROR  This  code  is  erroneous  !}


will display an error message when the compiler encounters it, and increase the error count
of the compiler.  The compiler will continue to compile, but no code will be emitted.
1.1.9       $F  :  Far  or  near  functions

This directive is recognized for compatibility with Turbo Pascal.  Under the 32-bit program-
ming model, the concept of near and far calls have no meaning, hence the directive is ignored.
A warning is printed to the screen, telling you so.

As an example, the following piece of code :


{$F+}


Procedure  TestProc;


begin
 Writeln  ('Hello  From  TestProc');
end;


begin
 testProc
end.



                                                                 12

______________________________________________________________________________________________1.1.___LOCAL_DIRECTIVES______________*
 *___
Generates the following compiler output:


malpertuus:  >pp  -vw  testf
Compiler:  ppc386
Units  are  searched  in:  /home/michael;/usr/bin/;/usr/lib/ppc/0.9.1/linuxunits
Target  OS:  Linux
Compiling  testf.pp
testf.pp(1)  Warning:  illegal  compiler  switch
7739  kB  free
Calling  assembler...
Assembled...
Calling  linker...
12  lines  compiled,
 1.00000000000000E+0000


You can see that the verbosity level was set to display warnings.

If you declare a function as Far (this has the same effect as setting it between {$F+}...{$F-}
directives), the compiler also generates a warning :


testf.pp(3)  Warning:  FAR  ignored


The same story is true for procedures declared as Near.  The warning displayed in that case
is:


testf.pp(3)  Warning:  NEAR  ignored
1.1.10        $FATAL  :  Generate  fatal  error  message

The following code


{$FATAL  This  code  is  erroneous  !}


will display an error message when the compiler encounters it, and the compiler will imme-
diatly stop the compilation process.

This is mainly useful inc conjunction wih {$IFDEF  } or {$IFOPT  } statements.
1.1.11        $GOTO  :  Support  Goto  and  Label

If {$GOTO  ON} is specified, the compiler will support Goto statements and Label declarations.
By  default,  $GOTO  OFF  is  assumed.   This  directive  corresponds  to  the  -Sg  command-line
option.

As an example, the following code can be compiled:


{$GOTO  ON}


label  Theend;


begin
   If  ParamCount=0  then
      GoTo  TheEnd;
   Writeln  ('You  specified  command-line  options');
TheEnd:
end.



                                                                 13

               ______________________________________________________________________________________________1.1.___LOCAL_DIRECTIVE*
 *S_________________
Remark:         If you compile assembler code not in direct mode (using the intel or assembler readers) you
               must declare any labels you use in the assembler code and use {$GOTO  ON}.  If you compile
               in Direct mode then this is not necessary.
               1.1.12        $H  or  $LONGSTRINGS  :  Use  AnsiStrings

               If {$LONGSTRINGS  ON} is specified, the keyword String (no length specifier) will be treated
               as AnsiString, and the compiler will treat the corresponding varible as an ansistring, and
               will generate corresponding code.

               By default, the use of ansistrings is off, corresponding to {$H-}.  The system unit is compiled
               without ansistrings, all its functions accept shortstrng arguments.  The same is true for all
               RTL units, except the sysutils unit, which is compiled with ansistrings.
               1.1.13        $HINT  :  Generate  hint  message

               If the generation of hints is turned on, through the -vh command-line option or the {$HINTS
               ON} directive, then


               {$Hint  This  code  should  be  optimized  }


               will display a hint message when the compiler encounters it.

               By default, no hints are generated.
               1.1.14        $HINTS  :  Emit  hints

               {$HINTS  ON} switches the generation of hints on.  {$HINTS  OFF} switches the generation of
               hints off.  Contrary to the command-line option -vh this is a local switch, this is useful for
               checking parts of your code.
               1.1.15        $IF  :  Start  conditional  compilation

               The directive {$IF  expr} will continue the compilation if the boolean expression expr eval-
               uates to true.  If the compilation evaluates to false, then the source is skipped to the first
               {$ELSE} or {$ENDIF} directive.

               The compiler must be able to evaluate the expression at parse time.  This means that you
               cannot use variables or constants that are defined in the source.  Macros and symbols may
               be used, however.

               More information on this can be found in the section about conditionals.
               1.1.16        $IFDEF  Name  :  Start  conditional  compilation

               If the symbol Name is not defined then the {$IFDEF  name} will skip the compilation of the
               text  that  follows  it  to  the  first  {$ELSE}  or  {$ENDIF}  directive.   If  Name  is  defined,  then
               compilation continues as if the directive wasn't there.
               1.1.17        $IFNDEF  :  Start  conditional  compilation

               If  the  symbol  Name  is  defined  then  the  {$IFNDEF  name}  will  skip  the  compilation  of  the
               text  that  follows  it  to  the  first  {$ELSE}  or  {$ENDIF}  directive.   If  it  is  not  defined,  then
               compilation continues as if the directive wasn't there.



                                                                                14

               ______________________________________________________________________________________________1.1.___LOCAL_DIRECTIVE*
 *S_________________
               1.1.18        $IFOPT  :  Start  conditional  compilation

               The {$IFOPT  switch} will compile the text that follows it if the switch switch is currently
               in the specified state.  If it isn't in the specified state, then compilation continues after the
               corresponding {$ELSE} or {$ENDIF} directive.

               As an example:


               {$IFOPT  M+}
                  Writeln  ('Compiled  with  type  information');
               {$ENDIF}


               Will compile the writeln statement if generation of type information is on.

Remark:         The  {$IFOPT}  directive  accepts  only  short  options,  i.e.   {$IFOPT  TYPEINFO}  will  not  be
               accepted.
               1.1.19        $INFO  :  Generate  info  message

               If the generation of info is turned on, through the -vi command-line option, then

               {$INFO  This  was  coded  on  a  rainy  day  by  Bugs  Bunny  }


               will display an info message when the compiler encounters it.

               This is useful in conjunction with the {$IFDEF} directive, to show information about which
               part of the code is being compiled.
               1.1.20        $INLINE  :  Allow  inline  code.

               The {$INLINE  ON} directive tells the compiler that the Inline procedure modifier should be
               allowed.  Procedures that are declared inline are copied to the places where they are called.
               This has the effect that there is no actual procedure call, the code of the procedure is just
               copied to where the procedure is needed, this results in faster execution speed if the function
               or procedure is used a lot.

               By  default,  Inline  procedures  are  not  allowed.   You  need  to  specify  this  directive  if  you
               want to use inlined code.  This directive is equivalent to the command-line switch -Si.

Remark:


                  1.  Inline code is NOT exported from a unit.  This means that if you call an inline procedure
                      from another unit, a normal procedure call will be performed.  Only inside units, Inline
                      procedures are really inline.

                  2.  You cannot make recursive inline functions.  i.e.  an inline function that calls itself is
                      not allowed.
               1.1.21        $I  or  $IOCHECKS  :  Input/Output  checking

               The  {$I-}  or  {$IOCHECKS  OFF}  directive  tells  the  compiler  not  to  generate  input/output
               checking  code  in  your  program.   By  default,  the  compiler  generates  this  code1 ,  you  must
               switch it on using the -Ci command-line switch.

               If you compile using the -Ci compiler switch, the Free Pascal compiler inserts input/output
               checking  code  after  every  input/output  call  in  your  program.  If  an  error  occurred  during
               ___________________________________________________1
                    This behaviour changed in the 0.99.13 release of the compiler. Earlier versions by default did not generate
               this code.



                                                                                15

______________________________________________________________________________________________1.1.___LOCAL_DIRECTIVES______________*
 *___
input or output, then a run-time error will be generated.  Use this switch if you wish to avoid
this behavior.  If you still want to check if something went wrong, you can use the IOResult
function to see if everything went without problems.

Conversely,  {$I+}  will  turn  error-checking  back  on,  until  another  directive  is  encountered
which turns it off again.

The  most  common  use  for  this  switch  is  to  check  if  the  opening  of  a  file  went  without
problems, as in the following piece of code:


...
assign  (f,'file.txt');
{$I-}
rewrite  (f);
{$I+}
if  IOResult<>0  then
   begin
   Writeln  ('Error  opening  file  :  "file.txt"');
   exit
   end;
...


See the IOResult function explanantion in the referece manual for a detailed description of
the possible errors that can occur when using input/output checking.
1.1.22        $I  or  $INCLUDE  :  Include  file

The  {$I  filename}  or  {$INCLUDE  filename}  directive  tells  the  compiler  to  read  further
statements  from  the  file  filename.  The  statements  read  there  will  be  inserted  as  if  they
occurred in the current file.

The  compiler  will  append  the  .pp  extension  to  the  file  if  you  don't  specify  an  extension
yourself.  Do not put the filename between quotes,  as they will be regarded as part of the
file's name.

You can nest included files, but not infinitely deep.  The number of files is restricted to the
number of file descriptors available to the Free Pascal compiler.

Contrary to Turbo Pascal, include files can cross blocks.  I.e.  you can start a block in one
file (with a Begin keyword) and end it in another (with a End keyword).  The smallest entity
in an include file must be a token, i.e.  an identifier, keyword or operator.

The compiler will look for the file to include in the following places:


   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 directories to the include file search path with the -I command-line option.
1.1.23        $I  or  $INCLUDE  :  Include  compiler  info

In this form:


{$INCLUDE  %xxx%}



                                                                 16

               ______________________________________________________________________________________________1.1.___LOCAL_DIRECTIVE*
 *S_________________
               where xxx is one of  TIME, DATE, FPCVERSION or FPCTARGET, will generate a macro with the
               value  of  these  things.   If  xxx  is  none  of  the  above,  then  it  is  assumed  to  be  the  value  of
               an environment variable.  It's value will be fetched, and inserted in the code as if it were a
               string.

               For example, the following program


               Program  InfoDemo;


               Const  User  =  {$I  %USER%};


               begin
                  Write  ('This  program  was  compiled  at  ',{$I  %TIME%});
                  Writeln  ('  on  ',{$I  %DATE%});
                  Writeln  ('By  ',User);
                  Writeln  ('Compiler  version  :  ',{$I  %FPCVERSION%});
                  Writeln  ('Target  CPU  :  ',{$I  %FPCTARGET%});
               end.


               Creates the following output :


               This  program  was  compiled  at  17:40:18  on  1998/09/09
               By  michael
               Compiler  version  :  0.99.7
               Target  CPU  :  i386
               1.1.24        $I386__XXX  :  Specify  assembler  format

               This  switch  selects  the  assembler  reader.   {$I386_XXX}  has  the  same  effect  as  {$ASMMODE
               XXX}, section 1.1.2, page 10

               This switch is deprecated, the {$ASMMODE  XXX} directive should be used instead.
               1.1.25        $L  or  $LINK  :  Link  object  file

               The {$L  filename} or {$LINK  filename} directive tells the compiler that the file filename
               should  be  linked  to  your  program.   This  cannot  be  used  for  libraries,  see  section  section
               1.1.26, page 18 for that.

               The compiler will look for this file in the following way:


                  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 directories to the object file search path with the -Fo option.

               On linux systems, the name is case sensitive, and must be typed exactly as it appears on
               your system.

Remark:         Take care that the object file you're linking is in a format the linker understands.  Which
               format this is, depends on the platform you're on.  Typing ld on the command line gives a
               list of formats ld knows about.

               You can pass other files and options to the linker using the -k command-line option.  You
               can  specify  more  than  one  of  these  options,  and  they  will  be  passed  to  the  linker,  in  the



                                                                                17

               ______________________________________________________________________________________________1.1.___LOCAL_DIRECTIVE*
 *S_________________
               order that you specified them on the command line, just before the names of the object files
               that must be linked.
               1.1.26        $LINKLIB  :  Link  to  a  library

               The {$LINKLIB  name} will link to a library name.  This has the effect of passing -lname to
               the linker.

               As an example, consider the following unit:


               unit  getlen;


               interface
               {$LINKLIB  c}


               function  strlen  (P  :  pchar)  :  longint;cdecl;


               implementation


               function  strlen  (P  :  pchar)  :  longint;cdecl;external;


               end.


               If one would issue the command


               ppc386  foo.pp


               where foo.pp has the above unit in its uses clause, then the compiler would link your program
               to the c library, by passing the linker the -lc option.

               The same effect could be obtained by removing the linklib directive in the above unit, and
               specify -k-lc on the command-line:


               ppc386  -k-lc  foo.pp
               1.1.27        $M  or  $TYPEINFO  :  Generate  type  info

               For  classes  that  are  compiled  in  the  {$M+  }  or  {$TYPEINFO  ON}  state,  the  compiler  will
               generate Run-Time Type Information (RTTI). All descendent objects of an object that was
               compiled in the {$M+} state will get RTTI information too, as well as any published classes.
               By default, no Run-Time Type Information is generated.  The TPersistent object that is
               present in the FCL (Free Component Library) is generated in the {$M+} state.  The generation
               of RTTI allows programmers to stream objects, and to access published properties of objects,
               without knowing the actual class of the object.

               The run-time type information is accessible through the TypInfo unit, which is part of the
               Free Pascal Run-Time Library.

Remark:         that the streaming system implemented by Free Pascal requires that you make streamable
               components descendent from TPersistent.
               1.1.28        $MACRO  :  Allow  use  of  macros.

               In the {$MACRO  ON} state, the compiler allows you to use C-style (although not as elaborate)
               macros.  Macros provide a means for simple text substitution.  More information on using



                                                                                18

               ______________________________________________________________________________________________1.1.___LOCAL_DIRECTIVE*
 *S_________________
               macros can be found in the section 2.3, page 35 section.  This directive is equivalent to the
               command-line switch -Sm.

               By default, macros are not allowed.
               1.1.29        $MAXFPUREGISTERS  :  Maximum  number  of  FPU  registers  for  vari-

                             ables

               The {$MAXFPUREGISTERS  XXX} directive tells the compiler how much floating point variables
               can be kept in the floating point processor registers.  This switch is ignored unless the -Or
               (use register variables) optimization is used.

               Since version 0.99.14, the Free Pascal compiler supports floating point register variables; the
               content of these variables is not stored on the stack, but is kept in the floating point processor
               stack.

               This is quite tricky because the Intel FPU stack is limited to 8 entries.  The compiler uses
               a heuristic algorithm to determine how much variables should be put onto the stack:  in leaf
               procedures it is limited to 3 and in non leaf procedures to 1.  But in case of a deep call tree
               or, even worse, a recursive procedure this can still lead to a FPU stack overflow, so the user
               can tell the compiler how much (floating point) variables should be kept in registers.

               The directive accepts the following arguments:


               N   where N is the maximum number of FPU registers to use.  Currently this can be in the
                      range 0 to 7.

               Normal       restores the heuristic and standard behavior.

               Default      restores the heuristic and standard behaviour.


Remark:         The directive is valid untill the end of the current procedure.
               1.1.30        $MESSAGE  :  Generate  info  message

               If the generation of info is turned on, through the -vi command-line option, then


               {$MESSAGE  This  was  coded  on  a  rainy  day  by  Bugs  Bunny  }


               will display an info message when the compiler encounters it.  The effect is the same as the
               {$INFO} directive.
               1.1.31        $MMX  :  Intel  MMX  support

               As  of  version  0.9.8,  Free  Pascal  supports  optimization  for  the  MMX  Intel  processor  (see
               also 7).

               This  optimizes  certain  code  parts  for  the  MMX  Intel  processor,  thus  greatly  improving
               speed.  The speed is noticed mostly when moving large amounts of data.  Things that change
               are


                   o  Data  with  a  size  that  is  a  multiple  of  8  bytes  is  moved  using  the  movq  assembler
                      instruction, which moves 8 bytes at a time


Remark:         MMX support is NOT emulated on non-MMX systems, i.e.  if the processor doesn't have
               the MMX extensions, you cannot use the MMX optimizations.



                                                                                19

______________________________________________________________________________________________1.1.___LOCAL_DIRECTIVES______________*
 *___
When  MMX  support  is  on,  you  aren't  allowed  to  do  floating  point  arithmetic.   You  are
allowed  to  move  floating  point  data,  but  no  arithmetic  can  be  done.   If  you  wish  to  do
floating  point  math  anyway,  you  must  first  switch  of  MMX  support  and  clear  the  FPU
using the emms function of the cpu unit.

The following example will make this more clear:


Program  MMXDemo;


uses  cpu;


var
    d1  :  double;
    a  :  array[0..10000]  of  double;
    i  :  longint;


begin
    d1:=1.0;
{$mmx+}
    {  floating  point  data  is  used,  but  we  do  _no_  arithmetic  }
    for  i:=0  to  10000  do
        a[i]:=d2;    {  this  is  done  with  64  bit  moves  }
{$mmx-}
    emms;     {  clear  fpu  }
    {  now  we  can  do  floating  point  arithmetic  }
    ....
end.


See, however, the chapter on MMX (7) for more information on this topic.
1.1.32        $NOTE  :  Generate  note  message

If the generation of notes is turned on, through the -vn command-line option or the {$NOTES
ON} directive, then


{$NOTE  Ask  Santa  Claus  to  look  at  this  code  }


will display a note message when the compiler encounters it.
1.1.33        $NOTES  :  Emit  notes

{$NOTES  ON} switches the generation of notes on.  {$NOTES  OFF} switches the generation of
notes off.  Contrary to the command-line option -vn this is a local switch, this is useful for
checking parts of your code.

By default, {$NOTES  } is off.
1.1.34        $OUTPUT__FORMAT  :  Specify  the  output  format

{$OUTPUT_FORMAT  format} has the same functionality as the -A command-line option :  It
tells the compiler what kind of object file must be generated.  You can specify this switch
only before the Program or Unit clause in your source file.  The different kinds of formats are
shown in table (1.1).

The default output format depends on the platform the compiler was compiled on.



                                                                 20

               ______________________________________________________________________________________________1.1.___LOCAL_DIRECTIVE*
 *S_________________

                                           Table 1.1:  Formats generated by the x86 compiler
                                       _____________________________________________________________________________
                                       __Switch_value__________Generated_format_____________________________________
                                         AS                    AT&T assembler file.
                                         AS_AOUT               Go32v1 assembler file.
                                         ASW                   AT&T Win32 assembler file.
                                         COFF                  Go32v2 COFF object file.
                                         MASM                  Masm assembler file.
                                         NASM                  Nasm assembler file.
                                         NASMCOFF              Nasm assembler file (COFF format).
                                         NASMELF               Nasm assembler file (ELF format).
                                         PECOFF                PECOFF object file (Win32).
                                         TASM                  Tasm assembler file.

               1.1.35        $P  or  $OPENSTRINGS  :  Use  open  strings

               If this switch is on, all function or procedure parameters of type string are considered to be
               open string parameters; this parameter only has effect for short strings, not for ansistrings.

               When  using  openstrings,  the  declared  type  of  the  string  can  be  different  from  the  type  of
               string  that  is  actually  passed,  even  for  strings  that  are  passed  by  reference.  The  declared
               size of the string passed can be examined with the High(P) call.

               Default the use of openstrings is off.
               1.1.36        $PACKENUM  :  Minimum  enumeration  type  size

               This directive tells the compiler the minimum number of bytes it should use when storing
               enumerated types.  It is of the following form:


               {$PACKENUM  xxx}
               {$MINENUMSIZE  xxx}


               Where the form with $MINENUMSIZE is for Delphi compatibility.  xxx can be one of 1,2 or 4,
               or NORMAL or DEFAULT, corresponding to the default value of 4.

               As an alternative form one can use {$Z1}, {$Z2} {$Z4}.  Contrary to Delphi, the default size
               is 4 bytes ({$Z4}).

               So the following code


               {$PACKENUM  1}
               Type
                  Days  =  (monday,  tuesday,  wednesday,  thursday,  friday,
                               saturday,  sunday);


               will use 1 byte to store a variable of type Days, whereas it nomally would use 4 bytes.  The
               above code is equivalent to


               {$Z1}
               Type
                  Days  =  (monday,  tuesday,  wednesday,  thursday,  friday,
                               saturday,  sunday);


Remark:         Sets are always put in 32 bits or 32 bytes, this cannot be changed (yet).



                                                                                21

               ______________________________________________________________________________________________1.1.___LOCAL_DIRECTIVE*
 *S_________________
               1.1.37        $PACKRECORDS  :  Alignment  of  record  elements

               This directive controls the byte alignment of the elements in a record, object or class type
               definition.

               It is of the following form:


               {$PACKRECORDS  n}


               Where n is one of 1,2,4,16,C, NORMAL or DEFAULT. This means that the elements of a record
               that have size greater than n will be aligned on n byte boundaries.  Elements with size less
               than or equal to n will be aligned to a natural boundary, i.e.  to a power of two that is equal
               to or larger than the element's size.  The type C is used to specify alignment as by the GNU
               CC compiler.  It should be used only when making import units for C routines.

               The default alignment (which can be selected with DEFAULT) is 2, contrary to Turbo Pascal,
               where it is 1.

               More information on this and an example program can be found in the reference guide, in
               the section about record types.

Remark:         Sets are always put in 32 bit or 32 bytes, this cannot be changed
               1.1.38        $Q  $OVERFLOWCHECKS:  Overflow  checking

               The  {$Q+}  or  {$OVERFLOWCHECKS  ON}  directive  turns  on  integer  overflow  checking.   This
               means that the compiler inserts code to check for overflow when doing computations with
               integers.  When an overflow occurs, the run-time library will print a message Overflow  at
               xxx, and exit the program with exit code 215.

Remark:         Overflow checking behaviour is not the same as in Turbo Pascal since all arithmetic opera-
               tions are done via 32-bit values.  Furthermore, the Inc() and Dec standard system procedures
               are checked for overflow in Free Pascal, while in Turbo Pascal they are not.

               Using the {$Q-} switch switches off the overflow checking code generation.

               The generation of overflow checking code can also be controlled using the -Co command line
               compiler option (see Users' guide).
               1.1.39        $R  or  $RANGECHECKS  :  Range  checking

               By default, the compiler doesn't generate code to check the ranges of array indices, enumer-
               ation types, subrange types, etc.  Specifying the {$R+} switch tells the computer to generate
               code to check these indices.  If, at run-time, an index or enumeration type is specified that
               is out of the declared range of the compiler, then a run-time error is generated, and the pro-
               gram exits with exit code 201.  This can happen when doing a typecast (implicit or explicit)
               on an enumeration type or subrange type.

               The  {$RANGECHECKS  OFF}  switch  tells  the  compiler  not  to  generate  range  checking  code.
               This may result in faulty program behaviour, but no run-time errors will be generated.

Remark:         The standard functions val and Read will also check ranges when the call is compiled in
               {$R+} mode.
               1.1.40        $SATURATION  :  Saturation  operations

               This works only on the intel compiler,  and MMX support must be on ({$MMX  +}) for this
               to  have  any  effect.  See  the  section  on  saturation  support  (section  7.2,  page  58)  for  more
               information on the effect of this directive.



                                                                                22

______________________________________________________________________________________________1.1.___LOCAL_DIRECTIVES______________*
 *___
1.1.41        $SMARTLINK  :  Use  smartlinking

A unit that is compiled in the {$SMARTLINK  ON} state will be compiled in such a way that
it can be used for smartlinking.  This means that the unit is chopped in logical pieces:  each
procedure is put in it's own object file, and all object files are put together in a big archive.
When using such a unit, only the pieces of code that you really need or call, will be linked
in your program, thus reducing the size of your executable substantially.

Beware:  using  smartlinked  units  slows  down  the  compilation  process,  because  a  separate
object file must be created for each procedure.  If you have units with many functions and
procedures, this can be a time consuming process, even more so if you use an external assem-
bler (the assembler is called to assemble each procedure or function code block separately).

The smartlinking directive should be specified before the unit declaration part:


{$SMARTLINK  ON}


Unit  MyUnit;


Interface
 ...


This directive is equivalent to the -Cx command-line switch.
1.1.42        $STATIC  :  Allow  use  of  Static  keyword.

If  you  specify  the  {$STATIC  ON}  directive,  then  Static  methods  are  allowed  for  objects.
Static  objects  methods  do  not  require  a  Self  variable.   They  are  equivalent  to  Class
methods for classes.  By default, Static methods are not allowed.  Class methods are always
allowed.

By default, the address operator returns an untyped pointer.

This directive is equivalent to the -St command-line option.
1.1.43        $STOP  :  Generate  fatal  error  message

The following code


{$STOP  This  code  is  erroneous  !}


will display an error message when the compiler encounters it.  The compiler will immediatly
stop the compilation process.

It has the same effect as the {$FATAL} directive.
1.1.44        $T  or  $TYPEDADDRESS  :  Typed  address  operator  (@)

In  the  {$T+}  or  {$TYPEDADDRESS  ON}  state  the  @  operator,  when  applied  to  a  variable,
returns a result of type ^T, if the type of the variable is T. In the {$T-} state, the result is
always an untyped pointer, which is assignment compatible with all other pointer types.
1.1.45        $UNDEF  :  Undefine  a  symbol

The directive
                                                                 23

______________________________________________________________________________________________1.1.___LOCAL_DIRECTIVES______________*
 *___
{$UNDEF  name}


un-defines the symbol name if it was previously defined.  Name is case insensitive.
1.1.46        $V  or  $VARSTRINGCHECKS  :  Var-string  checking

When in the + or ON state, the compiler checks that strings passed as parameters are of the
same, identical, string type as the declared parameters of the procedure.
1.1.47        $WAIT  :  Wait  for  enter  key  press

If the compiler encounters a


{$WAIT  }


directive,  it  will  resume  compiling  only  after  the  user  has  pressed  the  enter  key.   If  the
generation of info messages is turned on, then the compiler will display the follwing message:


Press  <return>  to  continue


before  waiting  for  a  keypress.   Careful  !   This  may  interfere  with  automatic  compilation
processes.  It should be used for debugging purposes only.
1.1.48        $WARNING  :  Generate  warning  message

If  the  generation  of  warnings  is  turned  on,  through  the  -vw  command-line  option  or  the
{$WARNINGS  ON} directive, then


{$WARNING  This  is  dubious  code  }


will display a warning message when the compiler encounters it.
1.1.49        $WARNINGS  :  Emit  warnings

{$WARNINGS  ON}  switches  the  generation  of  warnings  on.   {$WARNINGS  OFF}  switches  the
generation of warnings off.  Contrary to the command-line option -vw this is a local switch,
this is useful for checking parts of your code.

By default, no warnings are emitted.
1.1.50        $X  or  $EXTENDEDSYNTAX  :  Extended  syntax

Extended syntax allows you to drop the result of a function.  This means that you can use
a function call as if it were a procedure.  Standard this feature is on.  You can switch it off
using the {$X-} or {$EXTENDEDSYNTAX  OFF}directive.

The following, for instance, will not compile :


function  Func  (var  Arg  :  sometype)  :  longint;
begin
...                 {  declaration  of  Func  }
end;

                                                                 24

___________________________________________________________________________________________1.2.___GLOBAL_DIRECTIVES________________*
 *___
...


{$X-}
Func  (A);


The reason this construct is supported is that you may wish to call a function for certain
side-effects  it  has,  but  you  don't  need  the  function  result.  In  this  case  you  don't  need  to
assign the function result, saving you an extra variable.

The command-line compiler switch -Sa1 has the same effect as the {$X+} directive.

By default, extended syntax is assumed.
1.2        Global  directives


Global directives affect the whole of the compilation process.  That is why they also have a
command-line counterpart.  The command-line counterpart is given for each of the directives.
1.2.1       $APPTYPE  :  Specify  type  of  application  (Win32  only)

The  {$APPTYPE  XXX}  accepts  one  argument  that  can  have  two  possible  values  :   GUI  or
CONSOLE.  It  is  used  to  tell  the  windows  Operating  system  if  an  application  is  a  console
application or a graphical application.  By default, a program compiled by Free Pascal is a
console  application.  Running  it  will  display  a  console  window.  Specifying  the  {$APPTYPE
GUI} directive will mark the application as a graphical application; no console window will
be opened when the application is run.  If run from the command-line, the command prompt
will be returned immediatly after the application was started.

Care should be taken when compiling GUI applications; the Input and Output files are not
available in a GUI application, and attempting to read from or write to them will result in
a run-time error.

It is possible to determine the application type of a windows application at runtime.  The
IsConsole constant, declared in the Win32 system unit as


Const
   IsConsole  :  Boolean


contains True if the application is a console application, False if the application is a GUI
application.
1.2.2       $D  or  $DEBUGINFO:  Debugging  symbols

When this switch is on ({$DEBUGINFO  ON}), the compiler inserts GNU debugging information
in the executable.  The effect of this switch is the same as the command-line switch -g.

By default, insertion of debugging information is off.
1.2.3       $DESCRIPTION

This switch is recognised for compatibility only, but is ignored completely by the compiler.
At a later stage, this switch may be activated.



                                                                 25

               ___________________________________________________________________________________________1.2.___GLOBAL_DIRECTIVES_*
 *__________________
               1.2.4       $E  :  Emulation  of  coprocessor

               This directive controls the emulation of the coprocessor.  There is no command-line counter-
               part for this directive.



                Intel x86 version


               When  this  switch  is  enabled,  all  floating  point  instructions  which  are  not  supported  by
               standard coprocessor emulators will give out a warning.

               The compiler itself doesn't do the emulation of the coprocessor.

               To  use  coprocessor  emulation  under  dos  go32v1  there  is  nothing  special  required,  as  it  is
               handled automatically.  (As of version 0.99.10, the go32v1 platform is no longer be supported)

               To use coprocessor emulation under dos go32v2 you must use the emu387 unit, which con-
               tains correct initialization code for the emulator.

               Under linux, the kernel takes care of the coprocessor support.



                Motorola 680x0 version


               When the switch is on, no floating point opcodes are emitted by the code generator.  Instead,
               internal run-time library routines are called to do the necessary calculations.  In this case all
               real types are mapped to the single IEEE floating point type.

Remark:         By  default,  emulation  is  on.  It  is  possible  to  intermix  emulation  code  with  real  floating
               point opcodes, as long as the only type used is single or real.
               1.2.5       $G  :  Generate  80286  code

               This option is recognised for Turbo Pascal compatibility, but is ignored, since the compiler
               works only on 386 or higher Intel processors.
               1.2.6       $INCLUDEPATH  :  Specify  include  path.

               This  option  serves  to  specify  the  include  path,  where  the  compiler  looks  for  include  files.
               {$INCLUDEPATH  XXX} will add XXX to the include path.  XXX can contain one or more paths,
               separated by semi-colons or colons.

               for example


               {$INCLUDEPATH  ../inc;../i386}


               {$I  strings.inc}


               Will add the directories ../inc and ../i386 to the include path of the compiler.  The compiler
               will look for the file strings.inc in both these directories, and will include the first found file.
               This directive is equivalent to the -Fi command-line switch.

               Caution is in order when using this directive:  If you distribute files, the places of the files
               may not be the same as on your machine; moreover, the directory structure may be different.
               In  general  it  would  be  fair  to  say  that  you  should  avoid  using  absolute  paths,  instead  use
               relative  paths,  as  in  the  example  above.   Only  use  this  directive  if  you  are  certain  of  the
               places where the files reside.  If you are not sure, it is better practice to use makefiles and
               makefile variables.

                                                                                26

___________________________________________________________________________________________1.2.___GLOBAL_DIRECTIVES________________*
 *___
1.2.7       $L  or  $LOCALSYMBOLS:  Local  symbol  information

This switch (not to be confused with the {$L  file} file linking directive) is recognised for
Turbo Pascal compatibility, but is ignored.  Generation of symbol information is controlled
by the $D switch.
1.2.8       $LIBRARYPATH  :  Specify  library  path.

This option serves to specify the library path, where the linker looks for static or dynamic
libraries.  {$LIBRARYPATH  XXX}  will  add  XXX  to  the  library  path.  XXX  can  contain  one  or
more paths, separated by semi-colons or colons.

for example


{$LIBRARYPATH  /usr/X11/lib;/usr/local/lib}


{$LINKLIB  X11}


Will add the directories /usr/X11/lib and /usr/local/lib to the linker library path.  The linker
will look for the library libX11.so in both these directories, and use the first found file.  This
directive is equivalent to the -Fl command-line switch.

Caution is in order when using this directive:  If you distribute files, the places of the libraries
may not be the same as on your machine; moreover, the directory structure may be different.
In general it would be fair to say that you should avoid using this directive.  If you are not
sure, it is better practice to use makefiles and makefile variables.
1.2.9       $M  or  $MEMORY:  Memory  sizes

This switch can be used to set the heap and stacksize.  It's format is as follows:


{$M  StackSize,HeapSize}


where StackSize and HeapSize should be two integer values, greater than 1024.  The first
number  sets  the  size  of  the  stack,  and  the  second  the  size  of  the  heap.   (Stack  setting  is
ignored under linux).  The two numbers can be set on the command line using the -Ch and
-Cs switches.
1.2.10        $MODE  :  Set  compiler  compatibility  mode

The {$MODE} sets the compatibility mode of the compiler.  This is equivalent to setting one
of the command-line options -So, -Sd, -Sp or -S2.  it has the following arguments:


Default      Default mode.  This reverts back to the mode that was set on the command-line.

Delphi      Delphi  compatibility  mode.  All  object-pascal  extensions  are  enabled.  This  is  the
       same as the command-line option -Sd.

TP    Turbo  pascal  compatibility  mode.   Object  pascal  extensions  are  disabled,  except  an-
       sistrings, which remain valid.  This is the same as the command-line option -So.

FPC     FPC mode.  This is the default, if no command-line switch is supplied.

OBJFPC          Object pascal mode.  This is the same as the -S2 command-line option.

GPC      GNU pascal mode.  This is the same as the -Sp command-line option.


For an exact description of each of these modes, see appendix D, on page 98.



                                                                 27

___________________________________________________________________________________________1.2.___GLOBAL_DIRECTIVES________________*
 *___
1.2.11        $N  :  Numeric  processing

This switch is recognised for Turbo Pascal compatibility, but is otherwise ignored, since the
compiler always uses the coprocessor for floating point mathematics.
1.2.12        $O  :  Overlay  code  generation

This switch is recognised for Turbo Pascal compatibility, but is otherwise ignored.
1.2.13        $OBJECTPATH  :  Specify  object  path.

This  option  serves  to  specify  the  object  path,  where  the  compiler  looks  for  object  files.
{$OBJECTPATH  XXX} will add XXX to the object path.  XXX can contain one or more paths,
separated by semi-colons or colons.

for example


{$OBJECTPATH  ../inc;../i386}


{$L  strings.o}


Will add the directories ../inc and ../i386 to the object path of the compiler.  The compiler
will look for the file strings.o in both these directories, and will link the first found file in the
program.  This directive is equivalent to the -Fo command-line switch.

Caution is in order when using this directive:  If you distribute files, the places of the files
may not be the same as on your machine; moreover, the directory structure may be different.
In  general  it  would  be  fair  to  say  that  you  should  avoid  using  absolute  paths,  instead  use
relative  paths,  as  in  the  example  above.   Only  use  this  directive  if  you  are  certain  of  the
places where the files reside.  If you are not sure, it is better practice to use makefiles and
makefile variables.
1.2.14        $S  :  Stack  checking

The {$S+} directive tells the compiler to generate stack checking code.  This generates code
to  check  if  a  stack  overflow  occurred,  i.e.  to  see  whether  the  stack  has  grown  beyond  its
maximally allowed size.  If the stack grows beyond the maximum size, then a run-time error
is generated, and the program will exit with exit code 202.

Specifying {$S-} will turn generation of stack-checking code off.

The command-line compiler switch -Ct has the same effect as the {$S+} directive.

By default, no stack checking is performed.
1.2.15        $UNITPATH  :  Specify  unit  path.

This option serves to specify the unit path, where the compiler looks for unit files.  {$UNITPATH
XXX} will add XXX to the unit path.  XXX can contain one or more paths, separated by semi-
colons or colons.

for example


{$UNITPATH  ../units;../i386/units}


Uses  strings;
                                                                 28

___________________________________________________________________________________________1.2.___GLOBAL_DIRECTIVES________________*
 *___
Will  add  the  directories  ../units  and  ../i386/units  to  the  unit  path  of  the  compiler.   The
compiler  will  look  for  the  file  strings.ppu  in  both  these  directories,  and  will  link  the  first
found file in the program.  This directive is equivalent to the -Fu command-line switch.

Caution is in order when using this directive:  If you distribute files, the places of the files
may not be the same as on your machine; moreover, the directory structure may be different.
In  general  it  would  be  fair  to  say  that  you  should  avoid  using  absolute  paths,  instead  use
relative  paths,  as  in  the  example  above.   Only  use  this  directive  if  you  are  certain  of  the
places where the files reside.  If you are not sure, it is better practice to use makefiles and
makefile variables.
1.2.16        $W  or  $STACKFRAMES  :  Generate  stackframes

The {$W} switch directove controls the generation of stackframes.  In the on state ({$STACKFRAMES
ON}), the compiler will generate a stackframe for every procedure or function.

In the off state, the compiler will omit the generation of a stackframe if the following condi-
tions are satisfied:


    o  The procedure has no parameters.

    o  The procedure has no local variables.

    o  If the procedure is not an assembler procedure,  it must not have a asm  ...    end;
       block.

    o  it is not a constuctor or desctructor.


If these conditions are satisfied, the stack frame will be omitted.
1.2.17        $Y  or  $REFERENCEINFO  :  Insert  Browser  information

This  switch  controls  the  generation  of  browser  inforation.  It  is  recognized  for  compatibil-
ity with Turbo Pascal and Delphi only,  as Browser information generation is not yet fully
supported.


                                                                 29


Chapter   2


Using   conditionals,   messages



and   macros



The Free Pascal compiler supports conditionals as in normal Turbo Pascal.  It does, however,
more than that.  It allows you to make macros which can be used in your code, and it allows
you to define messages or errors which will be displayed when compiling.
2.1        Conditionals


The  rules  for  using  conditional  symbols  are  the  same  as  under  Turbo  Pascal.   Defining  a
symbol goes as follows:


{$Define  Symbol  }


From this point on in your code, the compiler knows the symbol Symbol.  Symbols are, like
the Pascal language, case insensitive.

You can also define a symbol on the command line.  the -dSymbol option defines the symbol
Symbol.  You can specify as many symbols on the command line as you want.

Undefining an existing symbol is done in a similar way:


{$Undef  Symbol  }


If  the  symbol  didn't  exist  yet,  this  doesn't  do  anything.  If  the  symbol  existed  previously,
the  symbol  will  be  erased,  and  will  not  be  recognized  any  more  in  the  code  following  the
{$Undef  ...} statement.

You can also undefine symbols from the command line with the -u command-line switch..

To  compile  code  conditionally,  depending  on  whether  a  symbol  is  defined  or  not,  you  can
enclose the code in a {$ifdef  Symbol} ..  {$endif} pair.  For instance the following code
will never be compiled :


{$Undef  MySymbol}
{$ifdef  Mysymbol}
   DoSomething;
   ...
{$endif}

                                                             30

               _____________________________________________________________________________________________________2.1.___CONDITIO*
 *NALS______________

                                               Table 2.1:  Symbols defined by the compiler.
                                                                     __________________
                                                                           FPC
                                                                          VERv
                                                                         VERv_r
                                                                       VERv_r_p
                                                                     _______OS_________

               Similarly, you can enclose your code in a {$Ifndef  Symbol} ..  {$endif} pair.  Then the code
               between the pair will only be compiled when the used symbol doesn't exist.  For example, in
               the following example, the call to the DoSomething will always be compiled:


               {$Undef  MySymbol}
               {$ifndef  Mysymbol}
                  DoSomething;
                  ...
               {$endif}


               You can combine the two alternatives in one structure, namely as follows


               {$ifdef  Mysymbol}
                  DoSomething;
               {$else}
                  DoSomethingElse
               {$endif}


               In  this  example,  if  MySymbol  exists,  then  the  call  to  DoSomething  will  be  compiled.  If  it
               doesn't exist, the call to DoSomethingElse is compiled.

               The Free Pascal compiler defines some symbols before starting to compile your program or
               unit.  You can use these symbols to differentiate between different versions of the compiler,
               and between different compilers.  In table (2.1),  a list of pre-defined symbols is given1 .  In
               that table, you should change v with the version number of the compiler you're using, r with
               the release number and p with the patch-number of the compiler.  'OS' needs to be changed
               by  the  type  of  operating  system.  Currently  this  can  be  one  of  DOS,  GO32V2,  LINUX,  OS2,
               WIN32, MACOS, AMIGA or ATARI.

               The OS symbol is undefined if you specify a target that is different from the platform you're
               compiling  on.  The  -TSomeOS  option  on  the  command  line  will  define  the  SomeOS  symbol,
               and will undefine the existing platform symbol2 .

               As  an  example  :   Version  0.9.1  of  the  compiler,  running  on  a  Linux  system,  defines  the
               following symbols before reading the command line arguments:  FPC, VER0, VER0_9, VER0_9_1
               and LINUX. Specifying -TOS2 on the command-line will undefine the LINUX symbol, and will
               define the OS2 symbol.

Remark:        Symbols, even when they're defined in the interface part of a unit, are not available outside
               that unit.

               Except  for  the  Turbo  Pascal  constructs,  from  version  0.9.8  and  higher,  the  Free  Pascal
               compiler also supports a stronger conditional compile mechanism:  The {$If  } construct.

               The prototype of this construct is as follows :
               ___________________________________________________1
                   2Remark: The FPK symbol is still defined for compatibility with older versions.
                    In versions prior to 0.9.4, this didn't happen, thus making Cross-compiling impossible.
                                                                                31

_____________________________________________________________________________________________________2.1.___CONDITIONALS___________*
 *___
{$If  expr}
   CompileTheseLines;
{$else}
   BetterCompileTheseLines;
{$endif}


In  this  directive  expr  is  a  Pascal  expression  which  is  evaluated  using  strings,  unless  both
parts of a comparision can be evaluated as numbers, in which case they are evaluated using
numbers3 .  If the complete expression evaluates to '0', then it is considered false and rejected.
Otherwise it is considered true and accepted.  This may have unexpected consequences :


{$If  0}


Will evaluate to False and be rejected, while


{$If  00}


Will evaluate to True.

You  can  use  any  Pascal  operator  to  construct  your  expression  :  =,  <>,  >,  <,  >=,  <=,
AND,  NOT,  OR and you can use round brackets to change the precedence of the operators.

The following example shows you many of the possibilities:


{$ifdef  fpc}


var
    y  :  longint;
{$else  fpc}


var
    z  :  longint;
{$endif  fpc}


var
    x  :  longint;


begin


{$if  (fpc_version=0)  and  (fpc_release>6)  and  (fpc_patch>4)}
{$info  At  least  this  is  version  0.9.5}
{$else}
{$fatal  Problem  with  version  check}
{$endif}


{$define  x:=1234}
{$if  x=1234}
{$info  x=1234}
{$else}
{$fatal  x  should  be  1234}
{$endif}


{$if  12asdf  and  12asdf}
{$info  $if  12asdf  and  12asdf  is  ok}
___________________________________________________3
     Otherwise {$If  8>54} would evaluate to True



                                                                 32

_____________________________________________________________________________________________________2.1.___CONDITIONALS___________*
 *___
{$else}
{$fatal  $if  12asdf  and  12asdf  rejected}
{$endif}


{$if  0  or  1}
{$info  $if  0  or  1  is  ok}
{$else}
{$fatal  $if  0  or  1  rejected}
{$endif}


{$if  0}
{$fatal  $if  0  accepted}
{$else}
{$info  $if  0  is  ok}
{$endif}


{$if  12=12}
{$info  $if  12=12  is  ok}
{$else}
{$fatal  $if  12=12  rejected}
{$endif}


{$if  12<>312}
{$info  $if  12<>312  is  ok}
{$else}
{$fatal  $if  12<>312  rejected}
{$endif}
{$if  12<=312}
{$info  $if  12<=312  is  ok}
{$else}
{$fatal  $if  12<=312  rejected}
{$endif}


{$if  12<312}
{$info  $if  12<312  is  ok}
{$else}
{$fatal  $if  12<312  rejected}
{$endif}


{$if  a12=a12}
{$info  $if  a12=a12  is  ok}
{$else}
{$fatal  $if  a12=a12  rejected}
{$endif}


{$if  a12<=z312}
{$info  $if  a12<=z312  is  ok}
{$else}
{$fatal  $if  a12<=z312  rejected}
{$endif}


                                                                 33

____________________________________________________________________________________________________________2.2.___MESSAGES________*
 *___
{$if  a12<z312}
{$info  $if  a12<z312  is  ok}
{$else}
{$fatal  $if  a12<z312  rejected}
{$endif}


{$if  not(0)}
{$info  $if  not(0)  is  OK}
{$else}
{$fatal  $if  not(0)  rejected}
{$endif}


{$info  *************************************************}
{$info  *  Now  have  to  follow  at  least  2  error  messages:  *}
{$info  *************************************************}


{$if  not(0}
{$endif}


{$if  not(<}
{$endif}


end.


As you can see from the example, this construct isn't useful when used with normal symbols,
only if you use macros, which are explained in section 2.3, page 35, they can be very useful.
When trying this example, you must switch on macro support, with the -Sm command-line
switch.
2.2        Messages


Free Pascal lets you define normal, warning and error messages in your code.  Messages can
be used to display useful information, such as copyright notices, a list of symbols that your
code reacts on etc.

Warnings can be used if you think some part of your code is still buggy, or if you think that a
certain combination of symbols isn't useful.  In general anything which may cause problems
when compiling.

Error  messages  can  be  useful  if  you  need  a  certain  symbol  to  be  defined  to  warn  that  a
certain variable isn't defined or so, or when the compiler version isn't suitable for your code.

The compiler treats these messages as if they were generated by the compiler.  This means
that if you haven't turned on warning messages, the warning will not be displayed.  Errors
are always displayed, and the compiler stops if 50 errors have occurred.  After a fatal error,
the compiler stops at once.

For messages, the syntax is as follows :


{$Message  Message  text  }


Or


{$Info  Message  text  }


For notes:



                                                                 34

               ________________________________________________________________________________________________________________2.3.*
 *___MACROS_________
               {$Note  Message  text  }


               For warnings:


               {$Warning  Warning  Message  text  }


               For errors :


               {$Error    Error  Message  text  }


               Lastly, for fatal errors :


               {$Fatal    Error  Message  text  }


               or


               {$Stop    Error  Message  text  }


               The difference between $Error and $FatalError or $Stop messages is that when the com-
               piler  encounters  an  error,  it  still  continues  to  compile.   With  a  fatal  error,  the  compiler
               stops.

Remark:         You cannot use the '}' character in your message, since this will be treated as the closing
               brace of the message.

               As an example, the following piece of code will generate an error when the symbol RequiredVar
               isn't defined:


               {$ifndef  RequiredVar}
               {$Error  Requiredvar  isn't  defined  !}
               {$endif}


               But  the  compiler  will  continue  to  compile.  It  will  not,  however,  generate  a  unit  file  or  a
               program (since an error occurred).
               2.3        Macros


               Macros are very much like symbols in their syntax, the difference is that macros have a value
               whereas a symbol simply is defined or is not defined.  If you want macro support, you need
               to specify the -Sm command-line switch, otherwise your macro will be regarded as a symbol.

               Defining a macro in your program is done in the same way as defining a symbol; in a {$define
               } preprocessor statement4 :


               {$define  ident:=expr}


               If the compiler encounters ident in the rest of the source file, it will be replaced immediately
               by expr.  This replacement works recursive, meaning that when the compiler expanded one
               of your macros, it will look at the resulting expression again to see if another replacement
               can be made.  You need to be careful with this,  because an infinite loop can occur in this
               manner.

               Here are two examples which illustrate the use of macros:
               ___________________________________________________4
                    In compiler versions older than 0.9.8, the assignment operator for a macros wasn't :=, but =
                                                                                35

               ________________________________________________________________________________________________________________2.3.*
 *___MACROS_________

                                                         Table 2.2:  Predefined macros
                                        ____________________________________________________________________________
                                        __Symbol________________Contains____________________________________________
                                          FPC_VERSION           The version number of the compiler.
                                          FPC_RELEASE           The release number of the compiler.
                                        __FPC_PATCH_____________The_patch_number_of_the_compiler.___________________

               {$define  sum:=a:=a+b;}
               ...
               sum                 {  will  be  expanded  to  'a:=a+b;'
                                       remark  the  absence  of  the  semicolon}
               ...
               {$define  b:=100}
               sum                 {  Will  be  expanded  recursively  to  a:=a+100;  }
               ...


               The previous example could go wrong :


               {$define  sum:=a:=a+b;}
               ...
               sum                 {  will  be  expanded  to  'a:=a+b;'
                                       remark  the  absence  of  the  semicolon}
               ...
               {$define  b=sum}  {  DON'T  do  this  !!!}
               sum                 {  Will  be  infinitely  recursively  expanded...  }
               ...


               On my system, the last example results in a heap error, causing the compiler to exit with a
               run-time error 203.

Remark:        Macros defined in the interface part of a unit are not available outside that unit !  They can
               just be used as a notational convenience, or in conditional compiles.

               By  default,  from  version  0.9.8  of  the  compiler  on,  the  compiler  predefines  three  macros,
               containing the version number, the release number and the patch number.  They are listed
               in table (2.2).

Remark:         Don't forget that macros support isn't on by default.  You need to compile with the -Sm
               command-line switch.

                                                                                36


Chapter   3


Using   Assembly   language



Free Pascal supports inserting of assembler instructions in your code.  The mechanism for
this is the same as under Turbo Pascal.  There are, however some substantial differences, as
will be explained in the following.
3.1        Intel  syntax


As of version 0.9.7, Free Pascal supports Intel syntax for the Intel family of Ix86 processors
in it's asm blocks.

The Intel syntax in your asm block is converted to AT&T syntax by the compiler, after which
it is inserted in the compiled source.  The supported assembler constructs are a subset of the
normal assembly syntax.  In what follows we specify what constructs are not supported in
Free Pascal, but which exist in Turbo Pascal:


    o  The TBYTE qualifier is not supported.

    o  The & identifier override is not supported.

    o  The HIGH operator is not supported.

    o  The LOW operator is not supported.

    o  The  OFFSET  and  SEG  operators  are  not  supported.  use  LEA  and  the  various  Lxx  in-
       structions instead.

    o  Expressions with constant strings are not allowed.

    o  Access to record fields via parenthesis is not allowed

    o  Typecasts with normal pascal types are not allowed, only recognized assembler type-
       casts are allowed.
       Example:


       mov  al,  byte  ptr  MyWord            --  allowed,
       mov  al,  byte(MyWord)                 --  allowed,
       mov  al,  shortint(MyWord)          --  not  allowed.


    o  Pascal type typecasts on constants are not allowed.
       Example:
                                                             37

_____________________________________________________________________________________________________3.1.___INTEL_SYNTAX___________*
 *___
       const  s=  10;  const  t  =  32767;


       in Turbo Pascal:


       mov  al,  byte(s)                    --  useless  typecast.
       mov  al,  byte(t)                    --  syntax  error!


       In this parser, either of those cases will give out a syntax error.

    o  Constant references expressions with constants only are not allowed (in all cases they
       do not work in protected mode, under linux i386).
       Examples:


       mov  al,byte  ptr  ['c']          --  not  allowed.
       mov    al,byte  ptr  [100h]       --  not  allowed.


       (This is due to the limitation of Turbo Assembler).

    o  Brackets within brackets are not allowed

    o  Expressions with segment overrides fully in brackets are presently not supported, but
       they can easily be implemented in BuildReference if requested.
       Example:


       mov  al,[ds:bx]        --  not  allowed


       use instead:


       mov  al,ds:[bx]


    o  Possible allowed indexing are as follows:

           -  Sreg:[REG+REG*SCALING+/-disp]

           -  SReg:[REG+/-disp]

           -  SReg:[REG]

           -  SReg:[REG+REG+/-disp]

           -  SReg:[REG+REG*SCALING]

       Where Sreg is optional and specifies the segment override.  Notes:

          1.  The order of terms is important contrary to Turbo Pascal.

          2.  The Scaling value must be a value, and not an identifier to a symbol.
              Examples:

              const  myscale  =  1;
              ...
              mov  al,byte  ptr  [esi+ebx*myscale]  --  not  allowed.

              use:

              mov  al,  byte  ptr  [esi+ebx*1]

    o  Possible variable identifier syntax is as follows:  (Id = Variable or typed constant iden-
       tifier.)

          1.  ID

          2.  [ID]



                                                                 38

_____________________________________________________________________________________________________3.1.___INTEL_SYNTAX___________*
 *___
          3.  [ID+expr]

          4.  ID[expr]

       Possible fields are as follow:

          1.  ID.subfield.subfield  ...

          2.  [ref].ID.subfield.subfield  ...

          3.  [ref].typename.subfield  ...

    o  Local Labels:  Contrary to Turbo Pascal, local labels, must at least contain one char-
       acter after the local symbol indicator.
       Example:


       @:                         --  not  allowed


       use instead, for example:


       @1:                      --  allowed


    o  Contrary  to  Turbo  Pascal  local  references  cannot  be  used  as  references,  only  as  dis-
       placements.
       example:


       lds  si,@mylabel     --  not  allowed


    o  Contrary  to  Turbo  Pascal,  SEGCS,  SEGDS,  SEGES  and  SEGSS  segment  overrides  are
       presently not supported.  (This is a planned addition though).

    o  Contrary to Turbo Pascal where memory sizes specifiers can be practically anywhere,
       the Free Pascal Intel inline assembler requires memory size specifiers to be outside the
       brackets.
       example:


       mov  al,[byte  ptr  myvar]       --  not  allowed.


       use:


       mov  al,byte  ptr  [myvar]       --  allowed.


    o  Base and Index registers must be 32-bit registers.  (limitation of the GNU Assembler).

    o  XLAT is equivalent to XLATB.

    o  Only Single and Double FPU opcodes are supported.

    o  Floating point opcodes are currently not supported (except those which involve only
       floating point registers).


The Intel inline assembler supports the following macros :


@Result       represents the function result return value.

Self   represents the object method pointer in methods.



                                                                 39

______________________________________________________________________________________________________3.2.___AT&T_SYNTAX___________*
 *___
3.2        AT&T  Syntax


Free Pascal uses the gnu as assembler to generate its object files for the Intel Ix86 processors
.  Since the gnu assembler uses AT&T assembly syntax, the code you write should use the
same syntax.  The differences between AT&T and Intel syntax as used in Turbo Pascal are
summarized in the following:


    o  The opcode names include the size of the operand.  In general,  one can say that the
       AT&T opcode name is the Intel opcode name, suffixed with a 'l', 'w' or 'b' for, respec-
       tively, longint (32 bit), word (16 bit) and byte (8 bit) memory or register references.
       As an example, the Intel construct 'mov  al  bl     is equivalent to the AT&T style 'movb
       %bl,%al' instruction.

    o  AT&T immediate operands are designated with '$',  while Intel syntax doesn't use a
       prefix for immediate operands.  Thus the Intel construct 'mov  ax,  2' becomes 'movb
       $2,  %al' in AT&T syntax.

    o  AT&T register names are preceded by a '%' sign.  They are undelimited in Intel syntax.

    o  AT&T  indicates  absolute  jump/call  operands  with  '*',  Intel  syntax  doesn't  delimit
       these addresses.

    o  The  order  of  the  source  and  destination  operands  are  switched.  AT&T  syntax  uses
       'Source,  Dest', while Intel syntax features 'Dest,  Source'.  Thus the Intel construct
       'add  eax,  4' transforms to 'addl  $4,  %eax' in the AT&T dialect.

    o  Immediate  long  jumps  are  prefixed  with  the  'l'  prefix.   Thus  the  Intel  'call/jmp
       section:offset' is transformed to 'lcall/ljmp  $section,$offset'.  Similarly the
       far return is 'lret', instead of the Intel 'ret  far'.

    o  Memory  references  are  specified  differently  in  AT&T  and  Intel  assembly.   The  Intel
       indirect memory reference

              Section:[Base  +  Index*Scale  +  Offs]

       is written in AT&T syntax as :

              Section:Offs(Base,Index,Scale)

       Where Base and Index are optional 32-bit base and index registers, and Scale is used
       to multiply Index.  It can take the values 1,2,4 and 8.  The Section is used to specify
       an optional section register for the memory operand.


More  information  about  the  AT&T  syntax  can  be  found  in  the  as  manual,  although  the
following differences with normal AT&T assembly must be taken into account :


    o  Only the following directives are presently supported:

       .byte

       .word

       .long

       .ascii

       .asciz

       .globl

    o  The following directives are recognized but are not supported:



                                                                 40

__________________________________________________________________________________________3.3.___CALLING_MECHANISM_________________*
 *___
       .align

       .lcomm

       Eventually they will be supported.

    o  Directives are case sensitive, other identifiers are not case sensitive.

    o  Contrary to GAS local labels/symbols must start with .L

    o  The not operator '!'  is not supported.

    o  String expressions in operands are not supported.

    o  CBTW,CWTL,CWTD and CLTD are not supported, use the normal intel equivalents
       instead.

    o  Constant expressions which represent memory references are not allowed even though
       constant immediate value expressions are supported.
       examples:


       const  myid  =  10;
       ...
       movl  $myid,%eax            --  allowed
       movl  myid(%esi),%eax    --  not  allowed.


    o  When  the  .globl  directive  is  found,  the  symbol  following  it  is  made  public  and  is
       immediately emitted.  Therefore label names with this name will be ignored.

    o  Only Single and Double FPU opcodes are supported.


The AT&T inline assembler supports the following macros :


___RESULT         represents the function result return value.

___SELF      represents the object method pointer in methods.

___OLDEBP          represents the old base pointer in recusrive routines.
3.3        Calling  mechanism


Procedures and Functions are called with their parameters on the stack.  Contrary to Turbo
Pascal,  all  parameters  are  pushed  on  the  stack,  and  they  are  pushed  right  to  left,  instead
of  left  to  right  for  Turbo  Pascal.  This  is  especially  important  if  you  have  some  assembly
subroutines in Turbo Pascal which you would like to translate to Free Pascal.

Function results are returned in the accumulator, if they fit in the register.

The  registers  are  not  saved  when  calling  a  function  or  procedure.   If  you  want  to  call  a
procedure  or  function  from  assembly  language,  you  must  save  any  registers  you  wish  to
preserve.

When you call an object method from assembler, you must load the ESI register with the
self pointer of the object or class.

The first thing a procedure does is saving the base pointer, and setting the base pointer equal
to the stack pointer.  References to the pushed parameters and local variables are constructed
using the base pointer.

When the procedure or function exits, it clears the stack.



                                                                 41

__________________________________________________________________________________________3.3.___CALLING_MECHANISM_________________*
 *___

                               Table 3.1:  Calling mechanisms in Free Pascal
            ______________________________________________________________________________________________________
            __Modifier________Pushing_order__________Stack_cleaned_by___________Parameters_in_registers___________
              (none)          Right-to-left          Function                   No
              cdecl           Right-to-left          Caller                     No
              export          Right-to-left          Caller                     No
              stdcall         Right-to-left          Function                   No
            __popstack________Right-to-left__________Caller_____________________No________________________________

When you want your code to be called by a C library or used in a C program, you will run
into trouble because of this calling mechanism.  In C, the calling procedure is expected to
clear  the  stack,  not  the  called  procedure.   In  other  words,  the  arguments  still  are  on  the
stack  when  the  procedure  exits.  To  avoid  this  problem,  Free  Pascal  supports  the  export
modifier.  Procedures that are defined using the export modifier, use a C-compatible calling
mechanism.  This means that they can be called from a C program or library, or that you
can use them as a callback function.

This  also  means  that  you  cannot  call  this  procedure  or  function  from  your  own  program,
since your program uses the Pascal calling convention.  However, in the exported function,
you can of course call other Pascal routines.

As of version 0.9.8, the Free Pascal compiler supports also the cdecl and stdcall modifiers,
as found in Delphi.  The cdecl modifier does the same as the export modifier, and stdcall
does  nothing,  since  Free  Pascal  pushes  the  paramaters  from  right  to  left  by  default.   In
addition to the Delphi cdecl construct, Free Pascal also supports the popstack directive; it
is nearly the same a the cdecl directive, only it still mangles the name, i.e.  makes it into a
name such as the compiler uses internally.

All  this  is  summarized  in  table  (3.1).   The  first  column  lists  the  modifier  you  specify  for
a procedure declaration.  The second one lists the order the paramaters are pushed on the
stack.  The third column specifies who is responsible for cleaning the stack:  the caller or the
called function.  Finally, the last column specifies if registers are used to pass parameters to
the function.

More about this can be found in chapter 4, page 44 on linking.
3.3.1         Ix86  calling  conventions

Standard entry code for procedures and functions is as follows on the x86 architecture:


    pushl     %ebp
    movl       %esp,%ebp


The generated exit sequence for procedure and functions looks as follows:


   leave
   ret    $xx


Where xx is the total size of the pushed parameters.

To have more information on function return values take a look at section 3.5, page 43.
3.3.2         M680x0  calling  conventions

Standard entry code for procedures and functions is as follows on the 680x0 architecture:



                                                                 42

_____________________________________________________________________3.4.___SIGNALLING_CHANGED_REGISTERS___________________________*
 *___
    move.l    a6,-(sp)
    move.l    sp,a6


The generated exit sequence for procedure and functions looks as follows:


   unlk     a6
   move.l  (sp)+,a0        ;  Get  return  address
   add.l    #xx,sp            ;  Remove  allocated  stack
   move.l  a0,-(sp)        ;  Put  back  return  address  on  top  of  the  stack


Where xx is the total size of the pushed parameters.

To have more information on function return values take a look at section 3.5, page 43.
3.4        Signalling  changed  registers


When the compiler uses variables, it sometimes stores them, or the result of some calculations,
in the processor registers.  If you insert assembler code in your program that modifies the
processor registers, then this may interfere with the compiler's idea about the registers.  To
avoid this problem, Free Pascal allows you to tell the compiler which registers have changed.
The compiler will then avoid using these registers.  Telling the compiler which registers have
changed, is done by specifying a set of register names behind an assembly block, as follows:


asm
   ...
end  ['R1',...,'Rn'];


Here R1 to Rn are the names of the 32-bit registers you modify in your assembly code.

As an example :


    asm
    movl  BP,%eax
    movl  4(%eax),%eax
    movl  %eax,__RESULT
    end  ['EAX'];


This example tells the compiler that the EAX register was modified.
3.5        Register  Conventions


The compiler has different register conventions, depending on the target processor used.
3.5.1         Intel  x86  version

When optimizations are on, no register can be freely modified, without first being saved and
then restored.  Otherwise, EDI is usually used as a scratch register and can be freely used in
assembler blocks.
3.5.2         Motorola  680x0  version

Registers which can be freely modified without saving are registers D0, D1, D6, A0, A1, and
floating point registers FP2 to FP7.  All other registers are to be considered reserved and
should be saved and then restored when used in assembler blocks.



                                                                 43


Chapter   4


Linking   issues



When you only use Pascal code,  and Pascal units,  then you will not see much of the part
that the linker plays in creating your executable.  The linker is only called when you compile
a program.  When compiling units, the linker isn't invoked.

However,  there  are  times  that  you  want  to  link  to  C  libraries,  or  to  external  object  files
that are generated using a C compiler (or even another pascal compiler).  The Free Pascal
compiler can generate calls to a C function, and can generate functions that can be called
from C (exported functions).  More on these calling conventions can be found in section 3.3,
page 41.

In general, there are 2 things you must do to use a function that resides in an external library
or object file:


   1.  You must make a pascal declaration of the function or procedure you want to use.

   2.  You must tell the compiler where the function resides, i.e.  in what object file or what
       library, so the compiler can link the necessary code in.


The same holds for variables.  To access a variable that resides in an external object file, you
must  declare  it,  and  tell  the  compiler  where  to  find  it.  The  following  sections  attempt  to
explain how to do this.
4.1        Using  external  functions  or  procedures


The first step in using external code blocks is declaring the function you want to use.  Free
Pascal  supports  Delphi  syntax,  i.e.  you  must  use  the  external  directive.  The  external
directive replaces, in effect, the code block of the function.

The external directive doesn't specify a calling convention; it just tells the compiler that the
code for a procedure or function resides in an external code block.

There exist four variants of the external directive :


   1.  A simple external declaration:


       Procedure  ProcName  (Args  :  TPRocArgs);  external;


       The external directive tells the compiler that the function resides in an external block
       of code.  You can use this together with the {$L  } or {$LinkLib  } directives to link to
       a function or procedure in a library or external object file.  Object files are looked for



                                                             44

        ________________________________________________4.1.___USING_EXTERNAL_FUNCTIONS_OR_PROCEDURES______________________________*
 *___________
               in the object search path (set by -Fo) and libraries are searched for in the linker path
               (set by -Fl).

           2.  You can give the external directive a library name as an argument:


               Procedure  ProcName  (Args  :  TPRocArgs);  external  'Name';


               This tells the compiler that the procedure resides in a library with name 'Name'.  This
               method is equivalent to the following:


               Procedure  ProcName  (Args  :  TPRocArgs);external;
               {$LinkLib  'Name'}


           3.  The external can also be used with two arguments:


               Procedure  ProcName  (Args  :  TPRocArgs);  external  'Name'
                                                                                name  'OtherProcName';


               This has the same meaning as the previous declaration, only the compiler will use the
               name 'OtherProcName' when linking to the library.  This can be used to give different
               names to procedures and functions in an external library.

               This method is equivalent to the following code:


               Procedure  OtherProcName  (Args  :  TProcArgs);  external;
               {$LinkLib  'Name'}


               Procedure  ProcName  (Args  :  TPRocArgs);


               begin
                   OtherProcName  (Args);
               end;


           4.  Lastly,  onder Windows  32-bit and os/2,  there is a fourth possibility to specify an
               external function:  In .DLL files, functions also have a unique number (their index).  It
               is possible to refer to these fuctions using their index:


               Procedure  ProcName  (Args  :  TPRocArgs);  external  'Name'  Index  SomeIndex;


               This tells the compiler that the procedure ProcName resides in a dynamic link library,
               with index SomeIndex.

Remark:         Note that this is ONLY available under Windows 32-bit and os/2.


        In earlier versions of the Free Pascal compiler, the following construct was also possible :


        Procedure  ProcName  (Args  :  TPRocArgs);  [  C  ];


        This method is equivalent to the following statement:


        Procedure  ProcName  (Args  :  TPRocArgs);  cdecl;  external;


        However,  the  [  C  ]  directive  is  no  longer  supported  as  of  version  0.99.5  of  Free  Pascal,
        therefore you should use the external directive, with the cdecl directive, if needed.


                                                                         45

_____________________________________________________________________________4.2.___USING_EXTERNAL_VARIABLES_______________________*
 *___
4.2        Using  external  variables


Some libaries or code blocks have variables which they export.  You can access these variables
much in the same way as external functions.  To access an external variable, you declare it
as follows:


Var
   MyVar  :  MyType;  external  name  'varname';


The effect of this declaration is twofold:


   1.  No space is allocated for this variable.

   2.  The name of the variable used in the assembler code is varname.  This is a case sensitive
       name, so you must be careful.


The variable will be accessible with it's declared name, i.e.  MyVar in this case.

A second possibility is the declaration:


Var
   varname  :  MyType;  cvar;  external;


The effect of this declaration is twofold as in the previous case:


   1.  The external modifier ensures that no space is allocated for this variable.

   2.  The cvar modifier tells the compiler that the name of the variable used in the assembler
       code is exactly as specified in the declaration.  This is a case sensitive name,  so you
       must be careful.


In this case, you access the variable with it's C name, but case insensitive.  The first possibility
allows you to change the name of the external variable for internal use.

In order to be able to compile such statements, the compiler switch -Sv must be used.

As an example, let's look at the following C file (in extvar.c):


/*
Declare  a  variable,  allocate  storage
*/
int  extvar  =  12;


And the following program (in extdemo.pp):


Program  ExtDemo;


{$L  extvar.o}


Var  {  Case  sensitive  declaration  !!  }
      extvar  :  longint;  cvar;external;
      I  :  longint;  external  name  'extvar';
begin
   {  Extvar  can  be  used  case  insensitive  !!  }
   Writeln  ('Variable  ''extvar''  has  value  :  ',ExtVar);
   Writeln  ('Variable  ''I''          has  value  :  ',i);
end.



                                                                 46

______________________________________________________________________________4.3.___LINKING_TO_AN_OBJECT_FILE_____________________*
 *___
Compiling the C file, and the pascal program:


gcc  -c  -o  extvar.o  extvar.c
ppc386  -Sv  extdemo


Will produce a program extdemo which will print


Variable  'extvar'  has  value  :  12
Variable  'I'          has  value  :  12


on your screen.
4.3        Linking  to  an  ob ject  file


Having declared the external function or variable that resides in an object file, you can use
it as if it was defined in your own program or unit.  To produce an executable, you must still
link the object file in.  This can be done with the {$L  file.o} directive.

This will cause the linker to link in the object file file.o.  On linux systems, this filename is
case sensitive.  Under dos, case isn't important.  Note that file.o must be in the current
directory if you don't specify a path.  The linker will not search for file.o if it isn't found.

You cannot specify libraries in this way, it is for object files only.

Here we present an example.  Consider that you have some assembly routine that calculates
the nth Fibonacci number :


.text
             .align  4
.globl  Fibonacci
             .type  Fibonacci,@function
Fibonacci:
             pushl  %ebp
             movl  %esp,%ebp
             movl  8(%ebp),%edx
             xorl  %ecx,%ecx
             xorl  %eax,%eax
             movl  $1,%ebx
             incl  %edx
loop:
             decl  %edx
             je  endloop
             movl  %ecx,%eax
             addl  %ebx,%eax
             movl  %ebx,%ecx
             movl  %eax,%ebx
             jmp  loop
endloop:
             movl  %ebp,%esp
             popl  %ebp
             ret


Then you can call this function with the following Pascal Program:


Program  FibonacciDemo;



                                                                 47

_______________________________________________________________________________________4.4.___LINKING_TO_A_LIBRARY_________________*
 *___


var  i  :  longint;


Function  Fibonacci  (L  :  longint):longint;cdecl;external;


{$L  fib.o}


begin
   For  I:=1  to  40  do
      writeln  ('Fib(',i,')  :  ',Fibonacci  (i));
end.


With just two commands, this can be made into a program :


as  -o  fib.o  fib.s
ppc386  fibo.pp


This example supposes that you have your assembler routine in fib.s, and your Pascal program
in fibo.pp.
4.4        Linking  to  a  library


To link your program to a library, the procedure depends on how you declared the external
procedure.

In case you used the follwing syntax to declare your procedure:


Procedure  ProcName  (Args  :  TPRocArgs);  external  'Name';


You don't need to take additional steps to link your file in, the compiler will do all that is
needed for you.  On Windows  NT it will link to Name.dll, on linux your program will be
linked to library libname, which can be a static or dynamic library.

In case you used


Procedure  ProcName  (Args  :  TPRocArgs);  external;


You still need to explicity link to the library.  This can be done in 2 ways:


   1.  You can tell the compiler in the source file what library to link to using the {$LinkLib
       'Name'} directive:


       {$LinkLib  'gpm'}


       This will link to the gpm library.  On linux systems, you needn't specify the extension
       or 'lib' prefix of the library.  The compiler takes care of that.  On dos or Windows
       32-bit systems, you need to specify the full name.

   2.  You can also tell the compiler on the command-line to link in a library:  The -k option
       can be used for that.  For example


       ppc386  -k'-lgpm'  myprog.pp


       Is equivalent to the above method, and tells the linker to link to the gpm library.



                                                                 48

______________________________________________________________________________________________4.5.___MAKING_LIBRARIES______________*
 *___
As an example; consider the following program :


program  printlength;


{$linklib  c}  {  Case  sensitive  }


{  Declaration  for  the  standard  C  function  strlen  }
Function  strlen  (P  :  pchar)  :  longint;  cdecl;external;


begin
   Writeln  (strlen('Programming  is  easy  !'));
end.


This program can be compiled with :


ppc386    prlen.pp


Supposing, of course, that the program source resides in prlen.pp.

To use functions in C that have a variable number of arguments, you must compile your unit
or program in objfpc mode or Delphi mode, and use the Array  of  const argument, as in
the following example:


program  testaocc;


{$mode  objfpc}


Const
   P  :  Pchar
      =  'example';
   F  :  Pchar
      =  'This  %s  uses  printf  to  print  numbers  (%d)  and  strings.'#10;


procedure  printf(fm:  pchar;args:  array  of  const);cdecl;external  'c';


begin
 printf(F,[P,123]);
end.


The output of this program looks like this:


This  example  uses  printf  to  print  numbers  (123)  and  strings.
4.5        Making  libraries


Free Pascal supports making shared or static libraries in a straightforward and easy manner.
If you want to make libraries for other Free Pascal programmers, you just need to provide a
command line switch.  If you want C programmers to be able to use your code as well, you
will need to adapt your code a little.  This process is described first.
4.5.1       Exporting  functions

When exporting functions from a library, there are 2 things you must take in account:



                                                                 49

               ______________________________________________________________________________________________4.5.___MAKING_LIBRARIE*
 *S_________________
                  1.  Calling conventions.

                  2.  Naming scheme.


               The calling conventions are controlled by the modifiers cdecl, popstack, pascal, stdcall.
               See section 3.3, page 41 for more information on the different kinds of calling scheme.

               The naming conventions can be controlled by 3 modifiers:


               cdecl:     A function that has a cdecl modifier, will be used with C calling conventions, that
                      is, the caller clears the stack.  Also the mangled name will be the name exactly as in
                      the declaration.  cdecl is part of the function declaration, and hence must be present
                      both in the interface and implementation section of a unit.

               export:       A function that has an export modifier, uses also the exact declaration name as its
                      mangled name.  Under Windows NT and os/2, this modifier signals a function that
                      is exported from a DLL. The calling conventions used by a export procedure depend
                      on the OS. This keyword can be used only in the implementation section.

               Alias:      The alias modifier can be used to give a second assembler name to your function.
                      This doesn't modify the calling conventions of the function.


               If you want to make your procedures and functions available to C programmers, you can do
               this very easily.  All you need to do is declare the functions and procedures that you want to
               make available as export, as follows:


               Procedure  ExportedProcedure;  export;


Remark:         You can only declare a function as exported in the Implementation section of a unit.  This
               function may not appear in the interface part of a unit.  This is logical, since a Pascal routine
               cannot call an exported function, anyway.

               However, the generated object file will not contain the name of the function as you declared
               it.  The Free Pascal compiler "mangles" the name you give your function.  It makes the name
               all-uppercase,  and adds the types of all parameters to it.  There are cases when you want
               to provide a mangled name without changing the calling convention.  In such cases, you can
               use the Alias modifier.

               The Alias modifier allows you to specify another name (a nickname) for your function or
               procedure.

               The prototype for an aliased function or procedure is as follows :


               Procedure  AliasedProc;  [  Alias  :  'AliasName'];


               The  procedure  AliasedProc  will  also  be  known  as  AliasName.  Take  care,  the  name  you
               specify is case sensitive (as C is).

Remark:         If you use in your unit functions that are in other units,  or system functions,  then the C
               program will need to link in the object files from the units too.
               4.5.2       Exporting  variables

               Similarly as when you export functions, you can export variables.  When exportig variables,
               one should only consider the names of the variables.  To declare a variable that should be
               used by a C program, one declares it with the cvar modifier:


               Var  MyVar  :  MyTpe;  cvar;



                                                                                50

______________________________________________________________________________________________4.5.___MAKING_LIBRARIES______________*
 *___
This will tell the compiler that the assembler name of the variable (the one which is used by
C programs) should be exactly as specified in the declaration, i.e., case sensitive.

It is not allowed to declare multiple variables as cvar in one statement,  i.e.  the following
code will produce an error:


var  Z1,Z2  :  longint;cvar;
4.5.3       Compiling  libraries

Once you have your (adapted) code, with exported and other functions, you can compile your
unit, and tell the compiler to make it into a library.  The compiler will simply compile your
unit, and perform the necessary steps to transform it into a static or shared (dynamical)
library.

You can do this as follows, for a dynamical library:


ppc386  -CD  myunit


On linux this will leave you with a file libmyunit.so.  On Windows  32-bit and os/2, this
will leave you with myunit.dll.

If you want a static library, you can do


ppc386  -CS  myunit


This  will  leave  you  with  libmyunit.a  and  a  file  myunit.ppu.  The  myunit.ppu  is  the  unit  file
needed by the Free Pascal compiler.

The  resulting  files  are  then  libraries.   To  make  static  libraries,  you  need  the  ranlib  or  ar
program on your system.  It is standard on any linux system, and is provided with the GCC
compiler under dos.  For the dos distribution, a copy of ar is included in the file gnuutils.zip.

BEWARE: This command doesn't include anything but the current unit in the library.  Other
units are left out, so if you use code from other units, you must deploy them together with
your library.
4.5.4       Moving  units  into  a  library

You can put multiple units into a library with the ppumove command, as follows:


ppumove  -e  ppl  -o  name  unit1  unit2  unit3


This will move 3 units in 1 library (called libname.so on linux, name.dll on Windows 32-bit)
and it will create 3 files unit1.ppl, unit2.ppl and unit3.ppl, which are unit files, but which tell
the compiler to look in library name when linking your executable.

The ppumove program has options to create statical or dynamical libraries.  It is provided
with the compiler.
4.5.5       Unit  searching  strategy

When you compile a program or unit, the compiler will by default always look for .ppl files.
If it doesn't find one, it will look for a .ppu file.

To  be  able  to  differentiate  between  units  that  have  been  compiled  as  static  or  dynamic
libraries, there are 2 switches:



                                                                 51

________________________________________________________________________________________4.6.___USING_SMART_LINKING_________________*
 *___
-XD:      This will define the symbol FPC_LINK_DYNAMIC

-XS:     This will define the symbol FPC_LINK_STATIC


Definition of one symbol will automatically undefine the other.

These two switches can be used in conjunction with the configuration file ppc386.cfg.  The
existence of one of these symbols can be used to decide which unit search path to set.  For
example:


#  Set  unit  paths


#IFDEF  FPC_LINK_STATIC
-Up/usr/lib/fpc/linuxunits/staticunits
#ENDIF
#IFDEF  FPC_LINK_DYNAMIC
-Up/usr/lib/fpc/linuxunits/sharedunits
#ENDIF


With  such  a  configuration  file,  the  compiler  will  look  for  it's  units  in  different  directories,
depending on whether -XD or -XS is used.
4.6        Using  smart  linking


You can compile your units using smart linking.  When you use smartlinking, the compiler
creates a series of code blocks that are as small as possible,  i.e.  a code block will contain
only the code for one procedure or function.

When you compile a program that uses a smart-linked unit, the compiler will only link in the
code that you actually need, and will leave out all other code.  This will result in a smaller
binary, which is loaded in memory faster, thus speeding up execution.

To enable smartlinking,  one can give the smartlink option on the command line :  -Cx,  or
one can put the {$SMARTLINK  ON} directive in the unit file:


Unit  Testunit


{SMARTLINK  ON}
Interface
...


Smartlinking will slow down the compilation process, especially for large units.

When a unit foo.pp is smartlinked, the name of the codefile is changed to libfoo.a.

Technically speaking, the compiler makes small assembler files for each procedure and func-
tion in the unit, as well as for all global defined variables (whether they're in the interface
section or not).  It then assembles all these small files,  and uses ar  to collect the resulting
object files in one archive.

Smartlinking and the creation of shared (or dynamic) libraries are mutually exclusive, that
is, if you turn on smartlinking, then the creation of shared libraries is turned of.  The creation
of  static  libraries  is  still  possible.  The  reason  for  this  is  that  it  has  little  sense  in  making
a  smarlinked  dynamical  library.  The  whole  shared  library  is  loaded  into  memory  anyway
by the dynamic linker (or Windows  NT), so there would be no gain in size by making it
smartlinked.
                                                                 52


               Chapter   5


               Ob jects



               In this short chapter we give some technical things about objects.  For instructions on how
               to use and declare objects, see the Reference guide.
               5.1        Constructor  and  Destructor  calls


               When using objects that need virtual methods, the compiler uses two help procedures that
               are in the run-time library.  They are called Help_Destructor and Help_Constructor, and
               they  are  written  in  assembly  language.   They  are  used  to  allocate  the  necessary  memory
               if  needed,  and  to  insert  the  Virtual  Method  Table  (VMT)  pointer  in  the  newly  allocated
               object.

               When the compiler encounters a call to an object's constructor, it sets up the stack frame for
               the call, and inserts a call to the Help_Constructor procedure before issuing the call to the
               real constructor.  The helper procedure allocates the needed memory (if needed) and inserts
               the VMT pointer in the object.  After that, the real constructor is called.

               A  call  to  Help_Destructor  is  inserted  in  every  destructor  declaration,  just  before  the  de-
               structor's exit sequence.
               5.2        Memory  storage  of  ob jects


               Objects are stored in memory just as ordinary records with an extra field :  a pointer to the
               Virtual Method Table (VMT). This field is stored first, and all fields in the object are stored
               in the order they are declared.  This field is initialized by the call to the object's Constructor
               method.

Remark:         In earlier versions of Free Pascal, if the object you defined has no virtual methods, then a
               nil is stored in the VMT pointer.  This ensured that the size of objects was equal, whether
               they  have  virtual  methods  or  not.  However,  in  the  0.99  versions  of  free  pascal,  this  was
               changed for compatibility reasons.  If an object doesn't have virtual methods, no pointer to
               a VMT is inserted.

               The memory allocated looks as in table (5.1).
                                                                            53

____________________________________________________________________________5.3.___THE_VIRTUAL_METHOD_TABLE________________________*
 *___

                                       Table 5.1:  Object memory layout
                    _____________________________________________________________________________________
                    __Offset______What___________________________________________________________________
                      +0          Pointer to VMT.
                      +4          Data.  All fields in the order the've been declared.
                    __...________________________________________________________________________________

                             Table 5.2:  Virtual Method Table memory layout


______________________________________________________________________________________________________________________________
__Offset______What____________________________________________________________________________________________________________
  +0          Size of object type data
  +4          Minus the size of object type data.  Enables determining of valid VMT pointers.
  +8          Pointer to ancestor VMT, Nil if no ancestor available.
  +12         Pointers to the virtual methods.
__..._________________________________________________________________________________________________________________________

5.3        The  Virtual  Method  Table


The Virtual Method Table (VMT) for each object type consists of 2 check fields (containing
the size of the data), a pointer to the object's ancestor's VMT (Nil if there is no ancestor),
and then the pointers to all virtual methods.  The VMT layout is illustrated in table (5.2).

The VMT is constructed by the compiler.  Every instance of an object receives a pointer to
its VMT.

                                                                 54


Chapter   6


Generated   code



The Free Pascal compiler relies on the assembler to make object files.  It generates just the
assembly language file.  In the following two sections, we discuss what is generated when you
compile a unit or a program.
6.1        Units


When you compile a unit, the Free Pascal compiler generates 2 files :


   1.  A unit description file (with extension .ppu, or .ppw on Windows NT ).

   2.  An assembly language file (with extension .s).


The assembly language file contains the actual source code for the statements in your unit,
and  the  necessary  memory  allocations  for  any  variables  you  use  in  your  unit.  This  file  is
converted by the assembler to an object file (with extension .o) which can then be linked to
other units and your program, to form an executable.

By  default  (compiler  version  0.9.4  and  up),  the  assembly  file  is  removed  after  it  has  been
compiled.  Only in the case of the -s command-line option, the assembly file must be left on
disk, so the assembler can be called later.  You can disable the erasing of the assembler file
with the -a switch.

The unit file contains all the information the compiler needs to use the unit:


   1.  Other used units, both in interface and implementation.

   2.  Types and variables from the interface section of the unit.

   3.  Function declarations from the interface section of the unit.

   4.  Some debugging information, when compiled with debugging.

   5.  A date and time stamp.


Macros, symbols and compiler directives are not saved to the unit description file.  Aliases
for functions are also not written to this file, which is logical, since they cannot appear in
the interface section of a unit.

The detailed contents and structure of this file are described in the first appendix.  You can
examine a unit description file using the ppudump program, which shows the contents of the
file.



                                                             55

___________________________________________________________________________________________________________6.2.___PROGRAMS_________*
 *___
If  you  want  to  distribute  a  unit  without  source  code,  you  must  provide  both  the  unit  de-
scription file and the object file.

You can also provide a C header file to go with the object file.  In that case, your unit can
be used by someone who wishes to write his programs in C. However, you must make this
header file yourself since the Free Pascal compiler doesn't make one for you.
6.2        Programs


When you compile a program, the compiler produces again 2 files :


   1.  An  assembly  language  file  containing  the  statements  of  your  program,  and  memory
       allocations for all used variables.

   2.  A  linker  response  file.   This  file  contains  a  list  of  object  files  the  linker  must  link
       together.


The  link  response  file  is,  by  default,  removed  from  the  disk.   Only  when  you  specify  the
-s command-line option or when linking fails, then the file is left on the disk.  It is named
link.res.

The assembly language file is converted to an object file by the assembler, and then linked
together with the rest of the units and a program header, to form your final program.

The program header file is a small assembly program which provides the entry point for the
program.  This is where the execution of your program starts, so it depends on the operating
system, because operating systems pass parameters to executables in wildly different ways.

It's  name  is  prt0.o,  and  the  source  file  resides  in  prt0.s  or  some  variant  of  this  name.   It
usually resided where the system unit source for your system resides.  It's main function is
to save the environment and command-line arguments and set up the stack.  Then it calls
the main program.
                                                                 56


Chapter   7


Intel   MMX   support
7.1        What  is  it  about  ?


Free Pascal supports the new MMX (Multi-Media extensions) instructions of Intel processors.
The idea of MMX is to process multiple data with one instruction, for example the processor
can add simultaneously 4 words.  To implement this efficiently, the Pascal language needs to
be extended.  So Free Pascal allows to add for example two array[0..3]  of  word, if MMX
support is switched on.  The operation is done by the MMX unit and allows people without
assembler knowledge to take advantage of the MMX extensions.

Here is an example:


uses
    MMX;     {  include  some  predefined  data  types  }


const
    {  tmmxword  =  array[0..3]  of  word;,  declared  by  unit  MMX  }
    w1  :  tmmxword  =  (111,123,432,4356);
    w2  :  tmmxword  =  (4213,63456,756,4);


var
    w3  :  tmmxword;
    l  :  longint;


begin
    if  is_mmx_cpu  then    {  is_mmx_cpu  is  exported  from  unit  mmx  }
        begin
{$mmx+}     {  turn  mmx  on  }
             w3:=w1+w2;
{$mmx-}
        end
    else
        begin
             for  i:=0  to  3  do
                w3[i]:=w1[i]+w2[i];
        end;
end.



                                                             57

________________________________________________________________________________________7.2.___SATURATION_SUPPORT__________________*
 *___
7.2        Saturation  support


One important point of MMX is the support of saturated operations.  If a operation would
cause an overflow, the value stays at the highest or lowest possible value for the data type:
If you use byte values you get normally 250+12=6.  This is very annoying when doing color
manipulations  or  changing  audio  samples,  when  you  have  to  do  a  word  add  and  check  if
the  value  is  greater  than  255.   The  solution  is  saturation:  250+12  gives  255.   Saturated
operations are supported by the MMX unit.  If you want to use them,  you have simple turn
the switch saturation on:  $saturation+

Here is an example:


Program  SaturationDemo;
{
   example  for  saturation,  scales  data  (for  example  audio)
   with  1.5  with  rounding  to  negative  infinity
}


var
    audio1  :  tmmxword;


const
    helpdata1  :  tmmxword  =  ($c000,$c000,$c000,$c000);
    helpdata2  :  tmmxword  =  ($8000,$8000,$8000,$8000);


begin
    {  audio1  contains  four  16  bit  audio  samples  }
{$mmx+}
    {  convert  it  to  $8000  is  defined  as  zero,  multiply  data  with  0.75  }
    audio1:=tmmxfixed16(audio1+helpdata2)*tmmxfixed(helpdata1);
{$saturation+}
    {  avoid  overflows  (all  values>$7fff  becomes  $ffff)  }
    audio1:=(audio1+helpdata2)-helpdata2;
{$saturation-}
    {  now  mupltily  with  2  and  change  to  integer  }
    audio1:=(audio1  shl  1)-helpdata2;
{$mmx-}
end.
7.3        Restrictions  of  MMX  support


In the beginning of 1997 the MMX instructions were introduced in the Pentium processors,
so multitasking systems wouldn't save the newly introduced MMX registers.  To work around
that problem, Intel mapped the MMX registers to the FPU register.

The  consequence  is  that  you  can't  mix  MMX  and  floating  point  operations.   After  using
MMX  operations  and  before  using  floating  point  operations,  you  have  to  call  the  routine
EMMS of the MMX unit.  This routine restores the FPU registers.

Careful:  The compiler doesn't warn if you mix floating point and MMX operations,  so be
careful.

The  MMX  instructions  are  optimized  for  multi  media  (what  else?).   So  it  isn't  possible
to  perform  each  operation,  some  opertions  give  a  type  mismatch,  see  section  7.4  for  the
supported MMX operations



                                                                 58

___________________________________________________________________________7.4.___SUPPORTED_MMX_OPERATIONS_________________________*
 *___
An important restriction is that MMX operations aren't range or overflow checked, even when
you turn range and overflow checking on.  This is due to the nature of MMX operations.

The MMX unit must always be used when doing MMX operations because the exit code of this
unit clears the MMX unit.  If it wouldn't do that, other program will crash.  A consequence
of  this  is  that  you  can't  use  MMX  operations  in  the  exit  code  of  your  units  or  programs,
since they would interfere with the exit code of the MMX unit.  The compiler can't check this,
so you are responsible for this !
7.4        Supported  MMX  operations


Still to be written...
7.5        Optimizing  MMX  support


Here are some helpful hints to get optimal performance:


    o  The EMMS call takes a lot of time, so try to seperate floating point and MMX operations.

    o  Use MMX only in low level routines because the compiler saves all used MMX registers
       when calling a subroutine.

    o  The NOT-operator isn't supported natively by MMX, so the compiler has to generate
       a workaround and this operation is inefficient.

    o  Simple assignements of floating point numbers don't access floating point registers, so
       you need no call to the EMMS procedure.  Only when doing arithmetic, you need to call
       the EMMS procedure.



                                                                 59


Chapter   8


Memory   issues
8.1        The  32-bit  model.


The Free Pascal compiler issues 32-bit code.  This has several consequences:


    o  You  need  a  386  processor  to  run  the  generated  code.   The  compiler  functions  on  a
       286 when you compile it using Turbo Pascal,  but the generated programs cannot be
       assembled or executed.

    o  You don't need to bother with segment selectors.  Memory can be addressed using a
       single 32-bit pointer.  The amount of memory is limited only by the available amount
       of (virtual) memory on your machine.

    o  The structures you define are unlimited in size.  Arrays can be as long as you want.
       You can request memory blocks from any size.


The fact that 32-bit code is used, means that some of the older Turbo Pascal constructs and
functions are obsolete.  The following is a list of functions which shouldn't be used anymore:


Seg()    :  Returned the segment of a memory address.  Since segments have no more meaning,
       zero is returned in the Free Pascal run-time library implementation of  Seg.

Ofs()    :  Returned the offset of a memory address.  Since segments have no more meaning,
       the complete address is returned in the Free Pascal implementation of this function.
       This has as a consequence that the return type is Longint instead of  Word.

Cseg(), Dseg()          :  Returned,  respectively,  the  code  and  data  segments  of  your  program.
       This  returns  zero  in  the  Free  Pascal  implementation  of  the  system  unit,  since  both
       code and data are in the same memory space.

Ptr:   Accepted  a  segment  and  offset  from  an  address,  and  would  return  a  pointer  to  this
       address.   This  has  been  changed  in  the  run-time  library.   Standard  it  returns  now
       simply  the  offset.  If  you  want  to  retain  the  old  functionality,  you  can  recompile  the
       run-time library with the DoMapping symbol defined.  This will restore the Turbo Pascal
       behaviour.

memw and mem               These arrays gave access to the dos memory.  Free Pascal supports them
       on the go32v2 platform, they are mapped into dos memory space.  You need the GO32
       unit for this.  On other platforms, they are not supported

                                                             60

___________________________________________________________________________________________________________8.2.___THE_STACK________*
 *___

                             Table 8.1:  Stack frame when calling a procedure
                      __________________________________________________________________________________
                      __Offset______What_is_stored_____________________________________Optional_?_______
                        +x          parameters                                              Yes
                        +12         function result                                         Yes
                        +8          self                                                    Yes
                        +4          Return address                                           No
                      __+0__________Frame_pointer_of_parent_procedure_______________________Yes_________

You shouldn't use these functions, since they are very non-portable, they're specific to dos
and the ix86 processor.  The Free Pascal compiler is designed to be portable to other plat-
forms, so you should keep your code as portable as possible, and not system specific.  That
is, unless you're writing some driver units, of course.
8.2        The  stack


The stack is used to pass parameters to procedures or functions, to store local variables, and,
in some cases, to return function results.

When a function or procedure is called, then the following is done by the compiler :


   1.  If there are any parameters to be passed to the procedure, they are pushed from right
       to left on the stack.

   2.  If a function is called that returns a variable of type String, Set, Record, Object or
       Array, then an address to store the function result in, is pushed on the stack.

   3.  If  the  called  procedure  or  function  is  an  object  method,  then  the  pointer  to  self  is
       pushed on the stack.

   4.  If the procedure or function is nested in another function or procedure, then the frame
       pointer of the parent procedure is pushed on the stack.

   5.  The return address is pushed on the stack (This is done automatically by the instruction
       which calls the subroutine).


The resulting stack frame upon entering looks as in table (8.1).
8.2.1         Intel  x86  version

The  stack  is  cleared  with  the  ret  I386  instruction,  meaning  that  the  size  of  all  pushed
parameters is limited to 64K.



 DOS


Under the DOS targets,  the default stack is set to 256Kb.  This value cannot be modified
for the GO32V1 target.  But this can be modified with the GO32V2 target using a special
DJGPP utility stubedit.  It is to note that the stack size may be changed with some compiler
switches, this stack size, if greater  then the default stack size will be used instead, otherwise
the default stack size is used.


                                                                 61

_____________________________________________________________________________________________________________8.3.___THE_HEAP_______*
 *___
 Linux


Under linux, stack size is only limited by the available memory of the system.



 Windows


Under Windows 32-bit, stack size is only limited by the available memory of the system.



 OS/2


Under  os/2,  stack  size  is  determined  by  one  of  the  runtime  environment  variables  set  for
EMX. Therefore, the stack size is user defined.
8.2.2         Motorola  680x0  version

All depending on the processor target, the stack can be cleared in two manners, if the target
processor is a MC68020 or higher, the stack will be cleared with a simple rtd instruction,
meaning that the size of all pushed parameters is limited to 32K.

Otherwise  on  MC68000/68010  processors,  the  stack  clearing  mechanism  is  sligthly  more
complicated, the exit code will look like this:


{
   move.l    (sp)+,a0
   add.l     paramsize,a0
   move.l    a0,-(sp)
   rts
}



 Amiga


Under AmigaOS, stack size is determined by the user, which sets this value using the stack
program.  Typical sizes range from 4K to 40K.



 Atari


Under Atari TOS, stack size is currently limited to 8K, and it cannot be modified.  This may
change in a future release of the compiler.
8.3        The  heap


The heap is used to store all dynamic variables, and to store class instances.  The interface
to the heap is the same as in Turbo Pascal,  although the effects are maybe not the same.
On top of that, the Free Pascal run-time library has some extra possibilities, not available
in Turbo Pascal.  These extra possibilities are explained in the next subsections.
8.3.1       The  heap  grows

Free Pascal supports the HeapError procedural variable.  If this variable is non-nil, then it
is  called  in  case  you  try  to  allocate  memory,  and  the  heap  is  full.  By  default,  HeapError
points to the GrowHeap function, which tries to increase the heap.



                                                                 62

               _____________________________________________________________________________________________________________8.3.___*
 *THE_HEAP__________
               The growheap function issues a system call to try to increase the size of the memory available
               to your program.  It first tries to increase memory in a 1 Mb.  chunk.  If this fails, it tries to
               increase the heap by the amount you requested from the heap.

               If  the  call  to  GrowHeap  has  failed,  then  a  run-time  error  is  generated,  or  nil  is  returned,
               depending on the GrowHeap result.

               If the call to GrowHeap was successful, then the needed memory will be allocated.
               8.3.2       Using  Blocks

               If you need to allocate a lot of small blocks for a small period, then you may want to recompile
               the run-time library with the USEBLOCKS symbol defined.  If it is recompiled, then the heap
               management is done in a different way.

               The run-time library keeps a linked list of allocated blocks with size up to 256 bytes1 .  By
               default, it keeps 32 of these lists2 .

               When a piece of memory in a block is deallocated, the heap manager doesn't really deallocate
               the occupied memory.  The block is simply put in the linked list corresponding to its size.

               When you then again request a block of memory, the manager checks in the list if there is
               a non-allocated block which fits the size you need (rounded to 8 bytes).  If so, the block is
               used to allocate the memory you requested.

               This method of allocating works faster if the heap is very fragmented, and you allocate a lot
               of small memory chunks.

               Since it is invisible to the program, this provides an easy way of improving the performance
               of the heap manager.
               8.3.3       Using  the  split  heap

Remark:         The split heap is still somewhat buggy.  Use at your own risk for the moment.

               The split heap can be used to quickly release a lot of blocks you allocated previously.

               Suppose that in a part of your program, you allocate a lot of memory chunks on the heap.
               Suppose that you know that you'll release all this memory when this particular part of your
               program is finished.

               In Turbo Pascal, you could foresee this, and mark the position of the heap (using the Mark
               function) when entering this particular part of your program, and release the occupied mem-
               ory in one call with the Release call.

               For most purposes, this works very good.  But sometimes, you may need to allocate something
               on the heap that you don't want deallocated when you release the allocated memory.  That
               is where the split heap comes in.

               When you split the heap, the heap manager keeps 2 heaps:  the base heap (the normal heap),
               and  the  temporary  heap.   After  the  call  to  split  the  heap,  memory  is  allocated  from  the
               temporary heap.  When you're finished using all this memory,  you unsplit the heap.  This
               clears all the memory on the split heap with one call.  After that, memory will be allocated
               from the base heap again.

               So far, nothing special, nothing that can't be done with calls to mark and release.  Suppose
               now that you have split the heap, and that you've come to a point where you need to allocate
               memory that is to stay allocated after you unsplit the heap again.  At this point, mark and
               release  are  of  no  use.  But  when  using  the  split  heap,  you  can  tell  the  heap  manager  to  -
               ___________________________________________________1
                   2The size can be set using the max_size constant in the heap.inc source file.
                    The actual size is max_size  div  8.



                                                                                63

_____________________________________________________________________________________________________________8.3.___THE_HEAP_______*
 *___
temporarily- use the base heap again to allocate memory.  When you've allocated the needed
memory, you can tell the heap manager that it should start using the temporary heap again.
When you're finished using the temporary heap, you release it, and the memory you allocated
on the base heap will still be allocated.

To use the split-heap, you must recompile the run-time library with the TempHeap symbol
defined.  This means that the following functions are available :


   procedure  Split_Heap;
   procedure  Switch_To_Base_Heap;
   procedure  Switch_To_Temp_Heap;
   procedure  Switch_Heap;
   procedure  ReleaseTempHeap;
   procedure  GetTempMem(var  p  :  pointer;size  :  longint);


Split_Heap  is  used  to  split  the  heap.    It  cannot  be  called  two  times  in  a  row,  with-
out  a  call  to  releasetempheap.   Releasetempheap  completely  releases  the  memory  used
by  the  temporary  heap.   Switching  temporarily  back  to  the  base  heap  can  be  done  us-
ing the Switch_To_Base_Heap call,  and returning to the temporary heap is done using the
Switch_To_Temp_Heap call.  Switching from one to the other without knowing on which one
your are right now, can be done using the Switch_Heap call, which will split the heap first if
needed.

A  call  to  GetTempMem  will  allocate  a  memory  block  on  the  temporary  heap,  whatever  the
current heap is.  The current heap after this call will be the temporary heap.

Typically, what will appear in your code is the following sequence :


Split_Heap
...
{  Memory  allocation  }
...
{  !!  non-volatile  memory  needed  !!}
Switch_To_Base_Heap;
getmem  (P,size);
Switch_To_Temp_Heap;
...
{Memory  allocation}
...
ReleaseTempHeap;
{All  allocated  memory  is  now  freed,  except  for  the  memory  pointed  to  by  'P'  }
...
8.3.4       Debugging  the  heap

Free  Pascal  provides  a  unit  that  allows  you  to  trace  allocation  and  deallocation  of  heap
memory:  heaptrc.

If  you  specify  the  -gh  switch  on  the  command-line,  or  if  you  include  heaptrc  as  the  first
unit in your uses clause, the memory manager will trace what is allocated and deallocated,
and on exit of your program, a summary will be sent to standard output.

More  information  on  using  the  heaptrc  mechanism  can  be  found  in  the  Users'  guide  and
Unit reference.
                                                                 64

_____________________________________________________________________________________________________________8.3.___THE_HEAP_______*
 *___
8.3.5       Writing  your  own  memory  manager

Free Pascal allows you to write and use your own memory manager.  The standard functions
GetMem, FreeMem, ReallocMem and Maxavail use a special record in the system unit to do the
actual memory management.  The system unit initializes this record with the system unit's
own memory manager,  but you can read and set this record using the GetMemoryManager
and SetMemoryManager calls:


procedure  GetMemoryManager(var  MemMgr:  TMemoryManager);
procedure  SetMemoryManager(const  MemMgr:  TMemoryManager);


the TMemoryManager record is defined as follows:


   TMemoryManager  =  record
      Getmem          :  Function(Size:Longint):Pointer;
      Freemem        :  Function(var  p:pointer):Longint;
      FreememSize  :  Function(var  p:pointer;Size:Longint):Longint;
      AllocMem       :  Function(Size:longint):Pointer;
      ReAllocMem    :  Function(var  p:pointer;Size:longint):Pointer;
      MemSize        :  function(p:pointer):Longint;
      MemAvail       :  Function:Longint;
      MaxAvail       :  Function:Longint;
      HeapSize       :  Function:Longint;
   end;


As you can see, the elements of this record are procedural variables.  The system unit does
nothing but call these various variables when you allocate or deallocate memory.

Each  of  these  functions  corresponds  to  the  corresponding  call  in  the  system  unit.   We'll
describe each one of them:


Getmem         This function allocates a new block on the heap.  The block should be Size bytes
       long.  The return value is a pointer to the newly allocated block.

Freemem         should release a previously allocated block.  The pointer P points to a previously
       allocated block.  The Memory manager should implement a mechanism to determine
       what the size of the memory block is 3  The return value is optional, and can be used
       to return the size of the freed memory.

FreememSize           This function should release the memory pointed to by P. The argument Size
       is the expected size of the memory block pointed to by P. This should be disregarded,
       but can be used to check the behaviour of the program.

AllocMem         Is the same as getmem, only the allocated memory should be filled with zeroes
       before the call returns.

ReAllocMem            Should  allocate  a  memory  block  Size  bytes  large,  and  should  fill  it  with
       the contents of the memory block pointed to by P, truncating this to the new size of
       needed.  After that, the memory pointed to by P may be deallocated.  The return value
       is a pointer to the new memory block.

MemSize        should return the total amount of memory available for allocation.  This function
       may return zero if the memory manager does not allow to determine this information.

MaxAvail        should return the size of the largest block of memory that is still available for
       allocation.  This function may return zero if the memory manager does not allow to
_______determine_this_information._________________
    3By storing it's size at a negative offset for instance.



                                                                 65

_____________________________________________________________________________________________________________8.3.___THE_HEAP_______*
 *___
HeapSize        should return the total size of the heap.  This may be zero is the memory manager
       does not allow to determine this information.


To implement your own memory manager, it is sufficient to construct such a record and to
issue a call to SetMemoryManager.

To avoid conflicts with the system memory manager,  setting the memory manager should
happen as soon as possible in the initialization of your program, i.e.  before any call to getmem
is processed.

This means in practice that the unit implementing the memory manager should be the first
in the uses clause of your program or library, since it will then be initialized before all other
units (except of the system unit)

This also means that it is not possible to use the heaptrc unit in combination with a custom
memory  manager,  since  the  heaptrc  unit  uses  the  system  memory  manager  to  do  all  it's
allocation.  Putting the heaptrc unit after the unit implementing the memory manager would
overwrite the memory manager record installed by the custom memory manager, and vice
versa.

The  following  unit  shows  a  straightforward  implementation  of  a  custom  memory  manager
using the memory manager of the C library.  It is distributed as a package with Free Pascal.


unit  cmem;


{$mode  objfpc}


interface


Function  Malloc  (Size  :  Longint)  :  Pointer;cdecl;
   external  'c'  name  'malloc';
Procedure  Free  (P  :  pointer);  cdecl;  external  'c'  name  'free';
Procedure  FreeMem  (P  :  Pointer);  cdecl;  external  'c'  name  'free';
function  ReAlloc  (P  :  Pointer;  Size  :  longint)  :  pointer;  cdecl;
   external  'c'  name  'realloc';
Function  CAlloc  (unitSize,UnitCount  :  Longint)  :  pointer;cdecl;
   external  'c'  name  'calloc';


implementation


Function  CGetMem    (Size  :  Longint)  :  Pointer;


begin
   result:=Malloc(Size);
end;


Function  CFreeMem  (Var  P  :  pointer)  :  Longint;


begin
   Free(P);
   Result:=0;
end;


Function  CFreeMemSize(var  p:pointer;Size:Longint):Longint;


begin
   Result:=CFreeMem(P);



                                                                 66

_____________________________________________________________________________________________________________8.3.___THE_HEAP_______*
 *___
end;


Function  CAllocMem(Size  :  Longint)  :  Pointer;


begin
   Result:=calloc(Size,1);
end;


Function  CReAllocMem  (var  p:pointer;Size:longint):Pointer;


begin
   Result:=realloc(p,size);
end;


Function  CMemSize  (p:pointer):  Longint;


begin
   Result:=0;
end;


Function  CMemAvail  :  Longint;


begin
   Result:=0;
end;


Function  CMaxAvail:  Longint;


begin
   Result:=0;
end;


Function  CHeapSize  :  Longint;


begin
   Result:=0;
end;
Const
 CMemoryManager  :  TMemoryManager  =
      (
         GetMem  :  CGetmem;
         FreeMem  :  CFreeMem;
         FreememSize  :  CFreememSize;
         AllocMem  :  CAllocMem;
         ReallocMem  :  CReAllocMem;
         MemSize  :  CMemSize;
         MemAvail  :  CMemAvail;
         MaxAvail  :  MaxAvail;
         HeapSize  :  CHeapSize;
      );


Var



                                                                 67

___________________________________________8.4.___USING_DOS_MEMORY_UNDER_THE_GO32_EXTENDER_________________________________________*
 *___
   OldMemoryManager  :  TMemoryManager;


Initialization
   GetMemoryManager  (OldMemoryManager);
   SetMemoryManager  (CmemoryManager);


Finalization
   SetMemoryManager  (OldMemoryManager);
end.
8.4        Using  dos  memory  under  the  Go32  extender


Because Free Pascal is a 32 bit compiler, and uses a dos extender, accessing DOS memory
isn't trivial.  What follows is an attempt to an explanation of how to access and use dos or
real mode memory4 .

In  Proteced  Mode,  memory  is  accessed  through  Selectors  and  Offsets.   You  can  think  of
Selectors as the protected mode equivalents of segments.

In Free Pascal, a pointer is an offset into the DS selector, which points to the Data of your
program.

To access the (real mode) dos memory, somehow you need a selector that points to the dos
memory.  The GO32 unit provides you with such a selector:  The DosMemSelector variable,
as it is conveniently called.

You can also allocate memory in dos's memory space, using the global_dos_alloc function
of the GO32 unit.  This function will allocate memory in a place where dos sees it.

As  an  example,  here  is  a  function  that  returns  memory  in  real  mode  dos  and  returns  a
selector:offset pair for it.


procedure  dosalloc(var  selector  :  word;
                               var  segment  :  word;
                               size  :  longint);


var  result  :  longint;


begin
        result  :=  global_dos_alloc(size);
        selector  :=  word(result);
        segment  :=  word(result  shr  16);
end;


(You need to free this memory using the global_dos_free function.)

You  can  access  any  place  in  memory  using  a  selector.   You  can  get  a  selector  using  the
allocate_ldt_descriptor function, and then let this selector point to the physical memory
you want using the set_segment_base_address function, and set its length using set_segment_limit
function.  You can manipulate the memory pointed to by the selector using the functions of
the GO32 unit.  For instance with the seg_fillchar function.  After using the selector, you
must free it again using the free_ldt_selector function.

More information on all this can be found in the Unit reference, the chapter on the GO32
unit.

___________________________________________________4
     Thanks to an explanation of Thomas schatzl (E-mail:tom_at_work@geocities.com).



                                                                 68


Chapter   9


Resource   strings
9.1        Introduction


Resource strings primarily exist to make internationalization of applications easier, by intro-
ducing a language construct that provides a uniform way of handling constant strings.

Most applications communicate with the user through some messages on the graphical screen
or  console.  Storing  these  messages  in  special  constants  allows  to  store  them  in  a  uniform
way in separate files, which can be used for translation.  A programmers interface exists to
manipulate the actual values of the constant strings at runtime, and a utility tool comes with
the Free Pascal compiler to convert the resource string files to whatever format is wanted by
the programmer.  Both these things are discussed in the following sections.
9.2        The  resource  string  file


When a unit is compiled that contains a resourcestring section, the compiler does 2 things:


   1.  It generates a table that contains the value of the strings as it is declared in the sources.

   2.  It generates a resource string file that contains the names of all strings, together with
       their declared values.


This approach has 2 advantages:  first of all, the value of the string is always present in the
program.   If  the  programmer  doesn't  care  to  translate  the  strings,  the  default  values  are
always present in the binary.  This also avoids having to provide a file containing the strings.
Secondly, having all strings together in a compiler generated file ensures that all strings are
together  (you  can  have  multiple  resourcestring  sections  in  1  unit  or  program)  and  having
this file in a fixed format, allows the programmer to choose his way of internationalization.

For  each  unit  that  is  compiled  and  that  contains  a  resourcestring  section,  the  compiler
generates a file that has the name of the unit, and an extension .rst.  The format of this file
is as follows:


   1.  An empty line.

   2.  A line starting with a hash sign (#) and the hash value of the string, preceded by the
       text hash  value  =.

   3.  A third line, containing the name of the resource string in the format unitname.constantname,
       all lowercase, followed by an equal sign, and the string value, in a format equal to the



                                                             69

______________________________________________________________________________9.2.___THE_RESOURCE_STRING_FILE______________________*
 *___
       pascal  representation  of  this  string.  The  line  may  be  continued  on  the  next  line,  in
       that case it reads as a pascal string expression with a plus sign in it.

   4.  Another empty line.


If the unit contains no resourcestring section, no file is generated.

For example, the following unit:


unit  rsdemo;


{$mode  delphi}
{$H+}


interface


resourcestring


   First  =  'First';
   Second  =  'A  Second  very  long  string  that  should  cover  more  than  1  line';
implementation


end.


Will result in the following resource string file:
#  hash  value  =  5048740
rsdemo.first='First'
#  hash  value  =  171989989
rsdemo.second='A  Second  very  long  string  that  should  cover  more  than  1  li'+
'ne'
The hash value is calculated with the function Hash.  It is present in the objpas unit.  The
value is the same value that the GNU gettext mechanism uses.  It is in no way unique, and
can only be used to speed up searches.

The  rstconv  utility  that  comes  with  the  Free  Pascal  compiler  allows  to  manipulate  these
resource string files.  At the moment, it can only be used to make a .po file that can be fed to
the GNU msgfmt program.  If someone wishes to have another format (Win32 resource files
spring to mind) he/she can enhance the rstconv program so it can generate other types of
files as well.  GNU gettext was chosen because it is available on all platforms, and is already
widely used in the Unix and free software community.  Since the Free Pascal team doesn't
want to restrict the use of resource strings, the .rst format was chosen to provide a neutral
method, not restricted to any tool.

If  you  use  resource  strings  in  your  units,  and  you  want  people  to  be  able  to  translate  the
strings, you must provide the resource string file.  Currently, there is no way to extract them
from  the  unit  file,  though  this  is  in  principle  possible.   It  is  not  required  to  do  this,  the
program can be compiled without it, but then the translation of the strings isn't possible.

                                                                 70

__________________________________________________________________________9.3.___UPDATING_THE_STRING_TABLES________________________*
 *___
9.3        Updating  the  string  tables


Having compiled a program with resourcestrings is not enough to internationalize your pro-
gram.  At run-time, the program must initialize the string tables with the correct values for
the anguage that the user selected.  By default no such initialization is performed.  All strings
are initialized with their declared values.

The objpas unit provides the mechanism to correctly initialize the string tables.  There is no
need to include this unit in a uses clause, since it is automatically loaded when a program
or unit is compiled in Delphi or objfpc mode.  Since this is required to use resource strings,
the unit is always loaded when needed.

The resource strings are stored in tables, one per unit, and one for the program, if it contains
a resourcestring section as well.  Each resourcestring is stored with it's name, hash value,
default value, and the current value, all as AnsiStrings.

The objpas unit offers methods to retrieve the number of resourcestring tables, the number
of strings per table, and the above information for each string.  It also offers a method to set
the current value of the strings.

Here are the declarations of all the functions:


Function  ResourceStringTableCount  :  Longint;
Function  ResourceStringCount(TableIndex  :  longint)  :  longint;
Function  GetResourceStringName(TableIndex,
                                                   StringIndex  :  Longint)  :  Ansistring;
Function  GetResourceStringHash(TableIndex,
                                                   StringIndex  :  Longint)  :  Longint;
Function  GetResourceStringDefaultValue(TableIndex,
                                                                StringIndex  :  Longint)  :  AnsiString;
Function  GetResourceStringCurrentValue(TableIndex,
                                                                StringIndex  :  Longint)  :  AnsiString;
Function  SetResourceStringValue(TableIndex,
                                                    StringIndex  :  longint;
                                                    Value  :  Ansistring)  :  Boolean;
Procedure  SetResourceStrings  (SetFunction  :    TResourceIterator);


Two other function exist, for convenience only:


Function  Hash(S  :  AnsiString)  :  longint;
Procedure  ResetResourceTables;


Here is a short explanation of what each function does.  A more detailed explanation of the
functions can be found in the Reference guide.


ResourceStringTableCount                    returns the number of resource string tables in the program.

ResourceStringCount                returns the number of resource string entries in a given table (tables
       are denoted by a zero-based index).

GetResourceStringName                   returns the name of a resource string in a resource table.  This
       is the name of the unit, a dot (.)  and the name of the string constant, all in lowercase.
       The strings are denoted by index, also zero-based.

GetResourceStringHash                  returns the hash value of a resource string, as calculated by the
       compiler with the Hash function.

GetResourceStringDefaultValue                       returns the default value of a resource string, i.e.  the
       value that appears in the resource string declaration, and that is stored in the binary.



                                                                 71

_____________________________________________________________________________________________________9.4.___GNU_GETTEXT____________*
 *___
GetResourceStringCurrentValue                       returns the current value of a resource string, i.e.  the
       value  set  by  the  initialization  (the  default  value),  or  the  value  set  by  some  previous
       internationalization routine.

SetResourceStringValue                 sets the current value of a resource string.  This function must
       be called to initialize all strings.

SetResourceStrings              giving this function a callback will cause the calback to be called for
       all resource strings, one by one, and set the value of the string to the return value of
       the callback.


Two other functions exist, for convenience only:


Hash     can be used to calculate the hash value of a string.  The hash value stored in the tables
       is the result of this function, applied on the default value.  That value is calculated at
       compile time by the compiler.

ResetResourceTables               will reset all the resource strings to their default values.  It is called
       by the initialization code of the objpas unit.


Given some Translate function, the following code would initialize all resource strings:


Var  I,J  :  Longint;
      S  :  AnsiString;


begin
   For  I:=0  to  ResourceStringTableCount-1  do
      For  J:=0  to  ResourceStringCount(i)-1  do
         begin
         S:=Translate(GetResourceStringDefaultValue(I,J));
         SetResourceStringValue(I,J,S);
         end;
end;


Other methods are of course possible, and the Translate function can be implemented in a
variety of ways.
9.4        GNU  gettext


The  unit  gettext  provides  a  way  to  internationalize  an  application  with  the  GNU  gettext
utilities.  This unit is supplied with the Free Component Library (FCL). it can be used as
follows:

for a given application, the following steps must be followed:


   1.  Collect all resource string files and concatenate them together.

   2.  Invoke the rstconv  program with the file resulting out of step 1,  resulting in a single
       .po file containing all resource strings of the program.

   3.  Translate the .po file of step 2 in all required languages.

   4.  Run the msgfmt formatting program on all the .po files, resulting in a set of .mo files,
       which can be distributed with your application.

                                                                 72

________________________________________________________________________________________________________________9.5.___CAVEAT______*
 *___
   5.  Call the gettext unit's TranslateReosurceStrings method,  giving it a template for
       the location of the .mo files, e.g.  as in


       TranslateResourcestrings('intl/restest.%s.mo');


       the %s specifier will be replaced by the contents of the LANG environment variable.  This
       call should happen at program startup.


An example program exists in the FCL sources, in the fcl/tests directory.
9.5        Caveat


In principle it is possible to translate all resource strings at any time in a running program.
However, this change is not communicated to other strings; its change is noticed only when
a constant string is being used.

Consider the following example:


Const
   help  =  'With  a  little  help  of  a  programmer.';


Var
   A  :  AnsiString;
begin


   {  lots  of  code  }


   A:=Help;


   {  Again  some  code}


   TranslateStrings;


   {  More  code  }


After the call to TranslateStrings, the value of A will remain unchanged.  This means that
the assignment A:=Help must be executed again in order for the change to become visible.
This  is  important,  especially  for  GUI  programs  which  have  e.g.  a  menu.  In  order  for  the
change in resource strings to become visible, the new values must be reloaded by program
code into the menus...



                                                                 73


Chapter   10


Optimizations
10.1           Non  processor  specific


The following sections describe the general optimizations done by the compiler, they are not
processor specific.  Some of these require some compiler switch override while others are done
automatically (those which require a switch will be noted as such).
10.1.1          Constant  folding

In  Free  Pascal,  if  the  operand(s)  of  an  operator  are  constants,  they  will  be  evaluated  at
compile time.

Example


    x:=1+2+3+6+5;
will  generate  the  same  code  as
    x:=17;


Furthermore,  if an array index is a constant,  the offset will be evaluated at compile time.
This means that accessing MyData[5] is as efficient as accessing a normal variable.

Finally, calling Chr, Hi, Lo, Ord, Pred, or Succ functions with constant parameters generates
no run-time library calls, instead, the values are evaluated at compile time.
10.1.2          Constant  merging

Using  the  same  constant  string  two  or  more  times  generates  only  one  copy  of  the  string
constant.
10.1.3          Short  cut  evaluation

Evaluation  of  boolean  expression  stops  as  soon  as  the  result  is  known,  which  makes  code
execute faster then if all boolean operands were evaluated.
10.1.4          Constant  set  inlining

Using the in operator is always more efficient then using the equivalent <>, =, <=, >=, < and
> operators.  This is because range comparisons can be done more easily with in then with



                                                             74

               ______________________________________________________________________________10.1.____NON_PROCESSOR_SPECIFIC_______*
 *__________________
               normal comparison operators.
               10.1.5          Small  sets

               Sets which contain less then 33 elements can be directly encoded using a 32-bit value, there-
               fore no run-time library calls to evaluate operands on these sets are required; they are directly
               encoded by the code generator.
               10.1.6          Range  checking

               Assignments of constants to variables are range checked at compile time, which removes the
               need of the generation of runtime range checking code.

Remark:         This feature was not implemented before version 0.99.5 of Free Pascal.
               10.1.7          Shifts  instead  of  multiply  or  divide

               When  one  of  the  operands  in  a  multiplication  is  a  power  of  two,  they  are  encoded  using
               arithmetic shift instructions, which generates more efficient code.

               Similarly, if the divisor in a div operation is a power of two, it is encoded using arithmetic
               shift instructions.

               The  same  is  true  when  accessing  array  indexes  which  are  powers  of  two,  the  address  is
               calculated using arithmetic shifts instead of the multiply instruction.
               10.1.8          Automatic  alignment

               By default all variables larger then a byte are guaranteed to be aligned at least on a word
               boundary.

               Furthermore  all  pointers  allocated  using  the  standard  runtime  library  (New  and  GetMem
               among others) are guaranteed to return pointers aligned on a quadword boundary (64-bit
               alignment).

               Alignment of variables on the stack depends on the target processor.

Remark:         Two facts about alignment:


                  1.  Quadword  alignment  of  pointers  is  not  guaranteed  on  systems  which  don't  use  an
                      internal heap, such as for the Win32 target.

                  2.  Alignment  is  also  done  between  fields  in  records,  objects  and  classes,  this  is  not  the
                      same as in Turbo Pascal and may cause problems when using disk I/O with these types.
                      To get no alignment between fields use the packed directive or the {$PackRecords  n}
                      switch.  For further information, take a look at the reference manual under the record
                      heading.
               10.1.9        Smart  linking

               This feature removes all unreferenced code in the final executable file, making the executable
               file much smaller.

               Smart linking is switched on with the -Cx command-line switch, or using the {$SMARTLINK
               ON} global directive.

Remark:         Smart linking was implemented starting with version 0.99.6 of Free Pascal.



                                                                                75

               ______________________________________________________________________________10.1.____NON_PROCESSOR_SPECIFIC_______*
 *__________________
               10.1.10           Inline  routines

               The following runtime library routines are coded directly into the final executable :  Lo, Hi,
               High, Sizeof, TypeOf, Length, Pred, Succ, Inc, Dec and Assigned.

Remark:         Inline Inc and Dec were not completely implemented until version 0.99.6 of Free Pascal.
               10.1.11           Case  optimization

               When using the -O1 (or higher) switch, case statements will be generated using a jump table
               if appropriate, to make them execute faster.
               10.1.12           Stack  frame  omission

               Under specific conditions, the stack frame (entry and exit code for the routine, see section
               3.3) will be omitted, and the variable will directly be accessed via the stack pointer.

               Conditions for omission of the stack frame :


                   o  The function has no parameters nor local variables.

                   o  Routine does not call other routines.

                   o  Routine does not contain assembler statements.  However,  a assembler routine may
                      omit it's stack frame.

                   o  Routine is not declared using the Interrupt directive.

                   o  Routine is not a constructor or destructor.
               10.1.13           Register  variables

               When using the -Or switch, local variables or parameters which are used very often will be
               moved to registers for faster access.

Remark:         Register variable allocation is currently an experimental feature, and should be used with
               caution.
               10.1.14           Intel  x86  specific

               Here follows a listing of the optimizing techniques used in the compiler:


                  1.  When optimizing for a specific Processor (-Op1,  -Op2,  -Op3, the following is done:

                          o  In case statements, a check is done whether a jump table or a sequence of condi-
                             tional jumps should be used for optimal performance.

                          o  Determines a number of strategies when doing peephole optimization, e.g.: movzbl
                             (%ebp),  %eax  will  be  changed  into  xorl  %eax,%eax;  movb  (%ebp),%al    for
                             Pentium and PentiumMMX.

                  2.  When optimizing for speed (-OG, the default) or size (-Og), a choice is made between
                      using  shorter  instructions  (for  size)  such  as  enter  $4,  or  longer  instructions  subl
                      $4,%esp  for  speed.   When  smaller  size  is  requested,  things  aren't  aligned  on  4-byte
                      boundaries.  When speed is requested, things are aligned on 4-byte boundaries as much
                      as possible.

                  3.  Fast optimizations (-O1):  activate the peephole optimizer



                                                                                76

______________________________________________________________________________10.1.____NON_PROCESSOR_SPECIFIC______________________*
 *___
   4.  Slower optimizations (-O2):  also activate the common subexpression elimination (for-
       merly called the "reloading optimizer")

   5.  Uncertain optimizations (-Ou):  With this switch, the common subexpression elimina-
       tion algorithm can be forced into making uncertain optimizations.

       Although you can enable uncertain optimizations in most cases, for people who do not
       understand  the  following  technical  explanation,  it  might  be  the  safest  to  leave  them
       off.


              If uncertain optimizations are enabled, the CSE algortihm assumes that

                 o  If something is written to a local/global register or a procedure/function
                    parameter,  this  value  doesn't  overwrite  the  value  to  which  a  pointer
                    points.

                 o  If something is written to memory pointed to by a pointer variable, this
                    value  doesn't  overwrite  the  value  of  a  local/global  variable  or  a  proce-
                    dure/function parameter.


       The practical upshot of this is that you cannot use the uncertain optimizations if you
       both write and read local or global variables directly and through pointers (this includes
       Var parameters, as those are pointers too).

       The following example will produce bad code when you switch on uncertain optimiza-
       tions:


       Var  temp:  Longint;


       Procedure  Foo(Var  Bar:  Longint);
       Begin
           If  (Bar  =  temp)
              Then
                 Begin
                     Inc(Bar);
                     If  (Bar  <>  temp)  then  Writeln('bug!')
                 End
       End;


       Begin
           Foo(Temp);
       End.


       The reason it produces bad code is because you access the global variable Temp both
       through  its  name  Temp  and  through  a  pointer,  in  this  case  using  the  Bar  variable
       parameter, which is nothing but a pointer to Temp in the above code.

       On the other hand, you can use the uncertain optimizations if you access global/local
       variables or parameters through pointers, and only access them through this pointer1 .

       For example:


       Type  TMyRec  =  Record
                                  a,  b:  Longint;
                              End;
                PMyRec  =  ^TMyRec;

___________________________________________________1
     You can use multiple pointers to point to the same variable as well, that doesn't matter.
                                                                 77

__________________________________________________________________________________10.2.___OPTIMIZATION_SWITCHES____________________*
 *___


                TMyRecArray  =  Array  [1..100000]  of  TMyRec;
                PMyRecArray  =  ^TMyRecArray;


       Var  MyRecArrayPtr:  PMyRecArray;
              MyRecPtr:  PMyRec;
              Counter:  Longint;


       Begin
           New(MyRecArrayPtr);
           For  Counter  :=  1  to  100000  Do
              Begin
                   MyRecPtr  :=  @MyRecArrayPtr^[Counter];
                   MyRecPtr^.a  :=  Counter;
                   MyRecPtr^.b  :=  Counter  div  2;
              End;
       End.


       Will produce correct code, because the global variable MyRecArrayPtr is not accessed
       directly, but only through a pointer (MyRecPtr in this case).

       In conclusion, one could say that you can use uncertain optimizations only when you
       know what you're doing.
10.1.15           Motorola  680x0  specific

Using  the  -O2  switch  does  several  optimizations  in  the  code  produced,  the  most  notable
being:


    o  Sign extension from byte to long will use EXTB

    o  Returning of functions will use RTD

    o  Range checking will generate no run-time calls

    o  Multiplication will use the long MULS instruction, no runtime library call will be gen-
       erated

    o  Division will use the long DIVS instruction, no runtime library call will be generated
10.2          Optimization  switches


This is where the various optimizing switches and their actions are described, grouped per
switch.


-On:     with  n  =  1..3:  these  switches  activate  the  optimizer.  A  higher  level  automatically
       includes all lower levels.

           o  Level 1 (-O1) activates the peephole optimizer (common instruction sequences are
              replaced by faster equivalents).

           o  Level 2 (-O2) enables the assembler data flow analyzer, which allows the common
              subexpression  elimination  procedure  to  remove  unnecessary  reloads  of  registers
              with values they already contain.

           o  Level 3 (-O3) enables uncertain optimizations.  For more info, see -Ou.



                                                                 78

_______________________________________________________________________________10.3.___TIPS_TO_GET_FASTER_CODE_____________________*
 *___
-OG:      This  causes  the  code  generator  (and  optimizer,  IF  activated),  to  favor  faster,  but
       code-wise  larger,  instruction  sequences  (such  as  "subl  $4,%esp")  instead  of  slower,
       smaller instructions ("enter  $4").  This is the default setting.

-Og:     This  one  is  exactly  the  reverse  of  -OG,  and  as  such  these  switches  are  mutually
       exclusive:  enabling one will disable the other.

-Or:     This setting (once it's fixed) causes the code generator to check which variables are
       used most, so it can keep those in a register.

-Opn:      with  n  =  1..3:  Setting  the  target  processor  does  NOT  activate  the  optimizer.  It
       merely influences the code generator and, if activated, the optimizer:

           o  During the code generation process, this setting is used to decide whether a jump
              table or a sequence of successive jumps provides the best performance in a case
              statement.

           o  The  peephole  optimizer  takes  a  number  of  decisions  based  on  this  setting,  for
              example it translates certain complex instructions, such as

              movzbl  (mem),  %eax|

              to a combination of simpler instructions

              xorl  %eax,  %eax
              movb  (mem),  %al

              for the Pentium.

-Ou:     This  enables  uncertain  optimizations.  You  cannot  use  these  always,  however.  The
       previous section explains when they can be used, and when they cannot be used.
10.3          Tips  to  get  faster  code


Here, some general tips for getting better code are presented.  They mainly concern coding
style.


    o  Find a better algorithm.  No matter how much you and the compiler tweak the code,
       a quicksort will (almost) always outperform a bubble sort, for example.

    o  Use variables of the native size of the processor you're writing for.  For the 80x86 and
       compatibles, this is 32 bit, so you're best of using longint and cardinal variables.

    o  Turn on the optimizer.

    o  Write your if/then/else statements so that the code in the "then"-part gets executed
       most of the time (improves the rate of successful jump prediction).

    o  If you are allocating and disposing a lot of small memory blocks, check out the heap-
       blocks variable (heapblocks are on by default from release 0.99.8 and later)

    o  Profile  your  code  (see  the  -pg  switch)  to  find  out  where  the  bottlenecks  are.  If  you
       want, you can rewrite those parts in assembler.  You can take the code generated by the
       compiler as a starting point.  When given the -a command-line switch,  the compiler
       will not erase the assembler file at the end of the assembly process, so you can study
       the assembler file.

       Note:  Code blocks which contain an assembler block, are not processed at all by the
       optimizer at this time.  Update:  as of version 0.99.11, the Pascal code surrounding the
       assembler blocks is optimized.



                                                                 79

               _____________________________________________________________________________________________10.4.____FLOATING_POINT*
 *__________________
               10.4           Floating  point


               This is where can be found processor specific information on floating point code generated
               by the compiler.
               10.4.1          Intel  x86  specific

               All normal floating point types map to their real type, including comp and extended.
               10.4.2          Motorola  680x0  specific

               Early  generations  of  the  Motorola  680x0  processors  did  not  have  integrated  floating  point
               units,  so  to  circumvent  this  fact,  all  floating  point  operations  are  emulated  (with  the  $E+
               switch,  which  is  the  default)  using  the  IEEE  Single  floating  point  type.   In  other  words
               when  emulation  is  on,  Real,  Single,  Double  and  Extended  all  map  to  the  single  floating
               point type.

               When  the  $E  switch  is  turned  off,  normal  68882/68881/68040  floating  point  opcodes  are
               emitted.  The Real type still maps to Single but the other types map to their true floating
               point  types.   Only  basic  FPU  opcodes  are  used,  which  means  that  it  can  work  on  68040
               processors correctly.

Remark:        Double and Extended types in true floating point mode have not been extensively tested as
               of version 0.99.5.

Remark:         The comp data type is currently not supported.

                                                                                80


 Chapter   11


 Programming   libraries
 11.1          Introduction


 Free Pascal supports the creation of shared libraries on linux and Windows 32-bit.  The
 mechanism is the same on both systems, although on Windows 32-bit library indexes can
 be used, which is not the case on linux.

 In the following sections we discuss how to create a library, and how to use these libraries in
 programs.
 11.2          Creating  a  library


 Creation of libraries is supported in any mode of the Free Pascal compiler,  but it may be
 that the arguments or return values differ if the library is compiled in 2 different modes.

 A library can be created just as a program, only it uses the library keyword, and it has an
 exports section.  The following listing demonstrates a simple library:

 Listing:  progex/subs.pp

________________________________________________________________________________________________________________________________
 {
    Example       l i b r a r y
 }
 l i b r a r y s u b s;


 f u n c t i o nS u b S t r( C S t r i n g: PChar    ; FromPos     , ToPos    :  L o n g i n t) : PChar    ;
      c d e c l;  e x p o r t;


 v a r
    Length     :  I n t e g e r;


 b e g i n
    Length      : =   StrLen    ( C S t r i n g) ;
    S u b S t r : =   C S t r i n g+   Length     ;
    i f  ( FromPos       >  0 )   and    (ToPos     >=    FromPos      )  then
    b e g i n
        i f  Length     >=    FromPos       then
           S u b S t r : =   C S t r i n g+   FromPos       -  1 ;
        i f  Length      >   ToPos     then
        C S t r i n g[ToPos    ]  : =  # 0 ;
                                                              81

 ________________________________________________________11.3.___USING_A_LIBRARY_IN_A_PASCAL_PROGRAM_______________________________*
 *____
    end   ;
 end  ;


 e x p o r t s
    S u b S t r;


_end__._________________________________________________________________________________________________________________________

 The function SubStr does not have to be declared in the library file itself.  It can also be
 declared in the interface section of a unit that is used by the library.

 Compilation of this source will result in the creation of a library called libsubs.so on linux,
 or subs.dll on Windows 32-bit.  The compiler will take care of any additional linking that
 is required to create a shared library.

 The library exports one function:  SubStr.  The case is important.  The case as it appears in
 the exports clause is used to export the function.

 Creation of libraries is supported in any mode of the Free Pascal compiler,  but it may be
 that the arguments or return values differ if the library is compiled in 2 different modes.  E.g.
 if your function expects an Integer argument, then the library will expect different integer
 sizes if you compile it in Delphi mode or in TP mode.

 If you want your library to be called from C programs, it is important to specify the C calling
 convention for the exported functions, with the cdecl modifier.  Since a C compiler doesn't
 know about the Free Pascal calling conventions, your functions would be called incorrectly,
 resulting in a corrupted stack.

 On Windows 32-bit, most libraries use the stdcall convention, so it may be better to use
 that one if your library is to be used on Windows 32-bit systems.
 11.3          Using  a  library  in  a  pascal  program


 In order to use a function that resides in a library, it is sufficient to declare the function as it
 exists in the library as an external function, with correct arguments and return type.  The
 calling convention used by the function should be declared correctly as well.  The compiler
 will then link the library as specified in the external statement to your program1 .

 For  example,  to  use  the  library  as  defined  above  from  a  pascal  program,  you  can  use  the
 following pascal program:

 Listing:  progex/psubs.pp

________________________________________________________________________________________________________________________________
 program       t e s t s u b s;


 f u n c t i o nS u b S t r( c o n s t C S t r i n g:  PChar    ;  FromPos     ,   ToPos    :  l o n g i n t) : PChar    ;
    c d e c l;   e x t e r n a l' s u b s' ;


 v a r
    s :  PChar    ;
    FromPos      ,  ToPos    :  I n t e g e r;
 b e g i n
    s  : =   ' T e s t';
    FromPos       : =  2 ;
    ToPos     : =  3 ;
    WriteLn     ( S u b S t r(s ,   FromPos     ,  ToPos    ) ) ;
_end__.__________________________________________________________________________________________________________________________
     1If you omit the library name in the external modifier, then you can still tell the compiler to link to that
 library using the {$Linklib  } directive.



                                                                  82

 ________________________________________________________11.3.___USING_A_LIBRARY_IN_A_PASCAL_PROGRAM_______________________________*
 *____
 As  is  shown  in  the  example,  you  must  declare  the  function  as  external.  Here  also,  it  is
 necessary to specify the correct calling convention (it should always match the convention
 as used by the function in the library), and to use the correct casing for your declaration.

 This program can be compiled without any additional command-switches,  and should run
 just like that, provided the library is placed where the system can find it.  On linux, this
 is /usr/lib or any directory listed in the /etc/ld.so.conf  file.  On Windows 32-bit, this can
 be the program directory, the Windows system directory, or any directoy mentioned in the
 PATH.

 Using the library in this way links the library to your program at compile time.  This means
 that


    1.  The library must be present on the system where the program is compiled.

    2.  The library must be present on the system where the program is executed.

    3.  Both libraries must be exactly the same.


 Or it may simply be that you don't know the name of the function to be called,  you just
 know the arguments it expects.

 It is therefore also possible to load the library at run-time, store the function address in a
 procedural variable, and use this procedural variable to access the function in the library.

 The following example demonstrates this technique:

 Listing:  progex/plsubs.pp

________________________________________________________________________________________________________________________________
 program       t e s t s u b s;


 Type
    TSubStrFunc         =
        f u n c t i o n(c o n s t C S t r i n g:PChar    ;FromPos      ,ToPos    :   l o n g i n t) :PChar   ; c d e c l;


 F u n c t i o n d l o p e n(name   :  p c h a r;mode    :  l o n g i n t) :p o i n t e r;c d e c l;e x t e r n a l ' d l' ;
 F u n c t i o nd l s y m( l i b:   p o i n t e r; name   :   p c h a r) :p o i n t e r;c d e c l;e x t e r n a l ' d l' ;
 F u n c t i o n d l c l o s e(l i b:  p o i n t e r) :l o n g i n t;c d e c l;e x t e r n a l ' d l' ;


 v a r
    s :  PChar    ;
    FromPos      ,  ToPos    :  I n t e g e r;
    l i b  :   p o i n t e r;
    S u b S t r :   TSubStrFunc        ;


 b e g i n
    s  : =   ' T e s t';
    FromPos       : =  2 ;
    ToPos     : =  3 ;
    l i b:=  d l o p e n(' l i b s u b s.so ' , 1 ) ;
    P o i n t e r(S u b s t r):=  d l s y m( l i b,' S u b S t r') ;
    WriteLn     ( S u b S t r(s ,   FromPos     ,  ToPos    ) ) ;
    d l c l o s e(l i b ) ;
_end__._________________________________________________________________________________________________________________________

 As in the case of compile-time linking, the crucial thing in this listing is the declaration of
 the TSubStrFunc type.  It should match the declaration of the function you're trying to use.
 Failure to specify a correct definition will result in a faulty stack or, worse still, may cause
 your program to crash with an access violation.

                                                                  83

               ______________________________________________11.4.___USING_A_PASCAL_LIBRARY_FROM_A_C_PROGRAM_______________________*
 *__________________
               11.4          Using  a  pascal  library  from  a  C  program


Remark:         The examples in this section assume a linux system; similar commands as the ones below
               exist for Windows 32-bit, though.

               You can also call a Free Pascal generated library from a C program:

               Listing:  progex/ctest.c

              _____________________________________________________________________________________________________________________*
 *___________
              #  i n c l u d e< s t r i n g.h >


               e x t e r n char   *  S u b S t r( c o n s t char   * ,  i n t ,  i n t) ;


               i n t  main   ( )
               {
                      char    * s ;
                      i n t  FromPos     ,  ToPos    ;


                      s  =   s t r d u p(" T e s t" ) ;
                      FromPos      =  2 ;
                      ToPos     =  3 ;
                      p r i n t f(" R e s u l t|_|from |_|S u b S t:r|_|' %s' \n " ,  S u b S t r(s ,   FromPos     ,  ToPos    ) )*
 * ;
                      r e t u r n 0 ;
              _}___________________________________________________________________________________________________________________*
 *___________


               To compile this example, the following command can be used:


               gcc  -o  ctest  ctest.c  -lsubs


               provided the code is in ctest.c.

               The library can also be loaded dynamically from C, as shown in the following example:

               Listing:  progex/ctest2.c

              _____________________________________________________________________________________________________________________*
 *___________
              #  i n c l u d e< d l f c n.h >
              #  i n c l u d e< s t r i n g.h >


               i n t  main   ( )
               {
                      v o i d * l i b;
                      char    * s ;
                      i n t  FromPos     ,  ToPos    ;
                      char   *  ( * S u b S t r) (c o n s t char   * ,  i n t ,  i n t) ;


                      l i b =   d l o p e n(" . / l i b s u b s.so " ,  RTLD_LAZY       ) ;
                      S u b S t r=   d l s y m( l i b,  " SUBSTR     " ) ;


                      s  =   s t r d u p(" T e s t" ) ;
                      FromPos      =  2 ;
                      ToPos     =  3 ;
                      p r i n t f(" R e s u l t|_|from |_|S u b S t:r|_|' %s' \n " ,  ( * S u b S t r) (s ,  FromPos     ,  ToPos  *
 *  ) ) ;
                      d l c l o s e(l i b) ;
                      r e t u r n 0 ;
              _}___________________________________________________________________________________________________________________*
 *___________


               This can be compiled using the following command:


               gcc  -o  ctest2  ctest2.c  -ldl



                                                                                84

______________________________________________11.4.___USING_A_PASCAL_LIBRARY_FROM_A_C_PROGRAM______________________________________*
 *___
The -ldl tells gcc that the program needs the libdl.so library to load dynamical libraries.



                                                                 85


               Chapter   12


               Using   Windows   resources
               12.1          The  resource  directive  $R


               Under  Windows  32-bit,  you  can  include  resources  in  your  executable  or  library  using
               the {$R  filename} directive.  These resources can then be accessed through the standard
               windows API calls.

               When the compiler encounters a resource directive, it just creates an entry in the unit .ppu
               file; it doesn't link the resource.  Only when it creates a library or executable, it looks for all
               the resource files for which it encountered a directive, and tries to link them in.

               The default extension for resource files is .res.  When the filename has as the first character
               an asterix (*), the compiler will replace the asterix with the name of the current unit, library
               or program.

Remark:         This means that the asterix may only be used after a unit, library or program clause.
               12.2          Creating  resources


               The Free Pascal compiler itself doesn't create any resource files; it just compiles them into
               the executable.  To create resource files, you can use some GUI tools as the Borland resource
               workshop; but it is also possible to use a windows resource compiler like gnu windres.  windres
               comes with the gnu binutils, but the Free Pascal distribution also contains a version which
               you can use.

               The  usage  of  windres  is  straightforward;  it  reads  an  input  file  describing  the  resources  to
               create and outputs a resource file.

               A typical invocation of  windres would be


               windres  -i  mystrings.rc  -o  mystrings.res


               this will read the mystrings.rc file and output a mystrings.res resource file.

               A complete overview of the windres tools is outside the scope of this document, but here are
               some things you can use it for:


               stringtables       that contain lists of strings.

               bitmaps       which are read from an external file.

               icons    which are also read from an external file.



                                                                            86

______________________________________________________________________________________12.3.___USING_STRING_TABLES._________________*
 *___
Version information              which can be viewed with the Windows explorer.

Menus       Can be designed as resources and used in your GUI applications.

Arbitrary data          Can be included as resources and read with the windows API calls.


Some of these will be described below.
12.3          Using  string  tables.


String tables can be used to store and retrieve large collections of strings in your application.

A string table looks as follows:


STRINGTABLE  {  1,  "hello  World  !"
                       2,  "hello  world  again  !"
                       3,  "last  hello  world  !"  }


You can compile this (we assume the file is called tests.rc) as follows:


windres  -i  tests.rc  -o  tests.res


And this is the way to retrieve the strings from your program:


program  tests;


{$mode  objfpc}


Uses  Windows;


{$R  *.res}


   Function  LoadResourceString  (Index  :  longint):  Shortstring;


   begin
      SetLength(Result,LoadString(FindResource(0,Nil,RT_STRING),Index,@Result[1],SizeOf(Result)))
   end;


Var
      I:  longint;


begin
   For  i:=1  to  3  do
      Writeln  (Loadresourcestring(I));
end.


The  call  to  FindResource  searches  for  the  stringtable  in  the  compiled-in  resources.   The
LoadString function then reads the string with index i out of the table,  and puts it in a
buffer, which can then be used.  Both calls are in the windows unit.
12.4          Inserting  version  information


The win32 API allows to store version information in your binaries.  This information can
be made visible with the Windows 32-bit Explorer, by right-clicking on the executable or



                                                                 87

____________________________________________________________________12.5.___INSERTING_AN_APPLICATION_ICON__________________________*
 *___
library, and selecting the 'Properties' menu.  In the tab 'Version' the version information will
be displayed.

Here is how to insert version information in your binary:


1  VERSIONINFO
FILEVERSION  4,  0,  3,  17
PRODUCTVERSION  3,  0,  0,  0
FILEFLAGSMASK  0
FILEOS  0x40000
FILETYPE  1
{
 BLOCK  "StringFileInfo"
 {
   BLOCK  "040904E4"
   {
    VALUE  "CompanyName",  "Free  Pascal"
    VALUE  "FileDescription",  "Free  Pascal  version  information  extractor"
    VALUE  "FileVersion",  "1.0"
    VALUE  "InternalName",  "Showver"
    VALUE  "LegalCopyright",  "GNU  Public  License"
    VALUE  "OriginalFilename",  "showver.pp"
    VALUE  "ProductName",  "Free  Pascal"
    VALUE  "ProductVersion",  "1.0"
   }
 }
}


As  you  can  see,  you  can  insert  various  kinds  of  information  in  the  version  info  block.
The keyword VERSIONINFO marks the beginning of the version information resource block.
The  keywords  FILEVERSION,  PRODUCTVERSION  give  the  actual  file  version,  while  the  block
StringFileInfo gives other information that is displayed in the explorer.

The  Free  Component  Library  comes  with  a  unit  (fileinfo)  that  allows  to  extract  and  view
version  information  in  a  straightforward  and  easy  manner;  the  demo  program  that  comes
with it (showver) shows version information for an arbitrary executable or DLL.
12.5          Inserting  an  application  icon


When  Windows  32-bit  shows  an  executable  in  the  Explorer,  it  looks  for  an  icon  in  the
executable to show in front of the filename, the application icon.

Inserting an application icon is very easy and can be done as follows


AppIcon  ICON  "filename.ico"


This will read the file filename.ico and insert it in the resource file.
12.6          Using  a  pascal  preprocessor


Sometimes you want to use symbolic names in your resource file, and use the same names
in your program to access the resources.  To accomplish this, there exists a preprocessor for
windres that understands pascal syntax:  fprcp.  This preprocessor is shipped with the Free
Pascal distribution.



                                                                 88

______________________________________________________________________12.6.___USING_A_PASCAL_PREPROCESSOR__________________________*
 *___
The  idea  is  that  the  preprocessor  reads  a  pascal  unit  that  has  some  symbolic  constants
defined in it, and replaces symbolic names in the resource file by the values of the constants
in the unit:

As an example:  consider the follwoing unit:


unit  myunit;


interface


Const
   First    =  1;
   Second  =  2:
   Third    =  3;


Implementation
end.


And the following resource file:


#include  "myunit.pp"


STRINGTABLE  {  First,  "hello  World  !"
                       Second,  "hello  world  again  !"
                       Third,  "last  hello  world  !"  }
if you invoke windres with the --preprocessor option:


windres  --preprocessor  fprcp  -i  myunit.rc  -o  myunit.res


Then the preprocessor will replace the symbolic names 'first', 'second' and 'third' with their
actual values.

In your program, you can then refer to the strings by their symbolic names (the constants)
instead of using a numeric index.
                                                                 89


Appendix   A


Anatomy   of   a   unit   file
A.1         Basics


The best and most updated documentation about the ppu files can be found in ppu.pas and
ppudump.pp which can be found in rtl/utils/.

To read or write the ppufile, you can use the ppu unit ppu.pas which has an object called
tppufile which holds all routines that deal with ppufile handling.  While describing the layout
of a ppufile, the methods which can be used for it are presented as well.

A unit file consists of basically five or six parts:


   1.  A unit header.

   2.  A file interface part.

   3.  A definition part.  Contains all type and procedure definitions.

   4.  A symbol part.  Contains all symbol names and references to their definitions.

   5.  A browser part.  Contains all references from this unit to other units and inside this
       unit.  Only available when the uf_has_browser flag is set in the unit flags

   6.  A file implementation part (currently unused).
A.2         reading  ppufiles


We will first create an object ppufile which will be used below.  We are opening unit test.ppu
as an example.


var
   ppufile  :  pppufile;
begin
{  Initialize  object  }
   ppufile:=new(pppufile,init('test.ppu');
{  open  the  unit  and  read  the  header,  returns  false  when  it  fails  }
   if  not  ppufile.open  then
      error('error  opening  unit  test.ppu');


{  here  we  can  read  the  unit  }



                                                             90

_______________________________________________________________________________________________________A.3.___THE_HEADER___________*
 *___


{  close  unit  }
   ppufile.close;
{  release  object  }
   dispose(ppufile,done);
end;


Note:  When  a  function  fails  (for  example  not  enough  bytes  left  in  an  entry)  it  sets  the
ppufile.error variable.
A.3         The  Header


The header consists of a record containing 24 bytes:


tppuheader=packed  record
      id            :  array[1..3]  of  char;  {  =  'PPU'  }
      ver          :  array[1..3]  of  char;
      compiler  :  word;
      cpu          :  word;
      target     :  word;
      flags       :  longint;
      size        :  longint;  {  size  of  the  ppufile  without  header  }
      checksum  :  longint;  {  checksum  for  this  ppufile  }
   end;


The header is already read by the ppufile.open command.  You can access all fields using
ppufile.header which holds the current header record.

_field____________description__________________________________________________________________________________
  id               this      is      allways      'PPU',      can      be      checked      with
                   function  ppufile.CheckPPUId:boolean;
  ver              ppu    version,     currently    '015',     can    be    checked    with
                   function  ppufile.GetPPUVersion:longint;                         (returns 15)
  compiler         compiler  version  used  to  create  the  unit.   Doesn't  contain  the
                   patchlevel.  Currently  0.99  where  0  is  the  high  byte  and  99  the
                   low byte
  cpu              cpu for which this unit is created.  0 = i386 1 = m68k
  target           target for which this unit is created, this depends also on the cpu!
                   For i386:    0    Go32v1
                                1    Go32V2
                                2    Linux-i386
                                3    OS/2
                                4    Win32
                   For m68k:    0    Amiga
                                1    Mac68k
                                2    Atari
                                3    Linux-m68k
  flag             the unit flags, contains a combination of the uf_ constants which
                   are definied in ppu.pas
  size             size of this unit without this header
  checksum         checksum of the interface parts of this unit, which determine if a
                   unit is changed or not, so other units can see if they need to be
___________________recompiled__________________________________________________________________________________



                                                                 91

_____________________________________________________________________________________________________A.4.___THE_SECTIONS___________*
 *___
A.4         The  sections


After this header follow the sections.  All sections work the same!  A section consists of entries
and ends also with an entry,  but containing the specific ibend constant (see ppu.pas for a
list of constants).

Each entry starts with an entryheader.


   tppuentry=packed  record
      id     :  byte;
      nr     :  byte;
      size  :  longint;
   end;


_field_____Description_________________________________________________________________________________
  id        this  is  1  or  2  and  can  be  checked  to  see  whether  the  entry  is
            correctly found.  1 means its a main entry,  which says that it is
            part of the basic layout as explained before.  2 means that it it a
            sub entry of a record or object.
  nr        contains the ib constant number which determines what kind of
            entry it is.
  size      size of this entry without the header, can be used to skip entries
____________very_easily._______________________________________________________________________________

To read an entry you can simply call ppufile.readentry:byte, it returns the tppuentry.nr
field, which holds the type of the entry.  A common way how this works is (example is for
the symbols):


   repeat
      b:=ppufile.readentry;
      case  b  of
    ib<etc>  :  begin
                     end;
 ibendsyms  :  break;
      end;
   until  false;


Then  you  can  parse  each  entry  type  yourself.  ppufile.readentry  will  take  care  of  skip-
ping  unread  bytes  in  the  entry  and  reads  the  next  entry  correctly!   A  special  function  is
skipuntilentry(untilb:byte):boolean;  which  will  read  the  ppufile  until  it  finds  entry
untilb in the main entries.

Parsing an entry can be done with ppufile.getxxx functions.  The available functions are:


procedure  ppufile.getdata(var  b;len:longint);
function    getbyte:byte;
function    getword:word;
function    getlongint:longint;
function    getreal:ppureal;
function    getstring:string;


To check if you're at the end of an entry you can use the following function:


function    EndOfEntry:boolean;


notes:



                                                                 92

___________________________________________________________________________________________A.5.___CREATING_PPUFILES________________*
 *___
   1.  ppureal is the best real that exists for the cpu where the unit is created for.  Currently
       it is extended for i386 and single for m68k.

   2.  the  ibobjectdef  and  ibrecorddef  have  stored  a  definition  and  symbol  section  for
       themselves.  So you'll need a recursive call.  See ppudump.pp for a correct implementa-
       tion.


A complete list of entries and what their fields contain can be found in ppudump.pp.
A.5         Creating  ppufiles


Creating  a  new  ppufile  works  almost  the  same  as  reading  one.  First  you  need  to  init  the
object and call create:


   ppufile:=new(pppufile,init('output.ppu'));
   ppufile.create;


After that you can simply write all needed entries.  You'll have to take care that you write
at least the basic entries for the sections:


   ibendinterface
   ibenddefs
   ibendsyms
   ibendbrowser  (only  when  you've  set  uf_has_browser!)
   ibendimplementation
   ibend


Writing an entry is a little different than reading it.  You need to first put everything in the
entry with ppufile.putxxx:


procedure  putdata(var  b;len:longint);
procedure  putbyte(b:byte);
procedure  putword(w:word);
procedure  putlongint(l:longint);
procedure  putreal(d:ppureal);
procedure  putstring(s:string);


After putting all the things in the entry you need to call ppufile.writeentry(ibnr:byte)
where ibnr is the entry number you're writing.

At the end of the file you need to call ppufile.writeheader to write the new header to the
file.  This takes automatically care of the new size of the ppufile.  When that is also done you
can call ppufile.close and dispose the object.

Extra functions/variables available for writing are:


ppufile.NewHeader;
ppufile.NewEntry;


This will give you a clean header or entry.  Normally this is called automatically in ppufile.writeentry,
so there should be no need to call these methods.


ppufile.flush;


to flush the current buffers to the disk



                                                                 93

___________________________________________________________________________________________A.5.___CREATING_PPUFILES________________*
 *___
ppufile.do_crc:boolean;


set to false if you don't want that the crc is updated, this is necessary if you write for example
the browser data.


                                                                 94


Appendix   B


Compiler   and   RTL   source   tree



structure
B.1         The  compiler  source  tree


All compiler source files are in one directory, normally in source/compiler.  For more informa-
tions about the structure of the compiler have a look at the Compiler Manual which contains
also some informations about compiler internals.

The compiler directory contains a subdirectory utils, which contains mainly the utilities for
creation and maintainance of the message files.
B.2         The  RTL  source  tree


The RTL source tree is divided in many subdirectories, but is very structured and easy to
understand.  It mainly consists of three parts:


   1.  A OS-dependent directory.  This contains the files that are different for each operating
       system.  When  compiling  the  RTL,  you  should  do  it  here.  The  following  directories
       exist:

           o  atari for the atari.  Not maintained any more.

           o  amiga for the amiga.  Not maintained any more.

           o  go32v1 For dos, using the GO32v1 extender.  Not maintained any more.

           o  go32v2 For dos, using the GO32v2 extender.

           o  linux for linux platforms.  It has two subdirect

           o  os2 for os/2.

           o  win32 for Win32 platforms.

   2.  A processor dependent directory.  This contains files that are system independent, but
       processor  dependent.  It  contains  mostly  optimized  routines  for  a  specific  processor.
       The following directories exist:

           o  i386 for the Intel series of processors.

           o  m68k for the motorola m68000 series of processors.
                                                             95

_______________________________________________________________________________________B.2.___THE_RTL_SOURCE_TREE__________________*
 *___
   3.  An OS-independent and Processor independent directory:  inc.  This contains complete
       units, and include files containing interface parts of units.


                                                                 96


Appendix   C


Compiler   limits



Although many of the restrictions imposed by the MS-DOS system are removed by use of an
extender, or use of another operating system, there still are some limitations to the compiler:


   1.  Procedure or Function definitions can be nested to a level of 32.

   2.  Maximally 255 units can be used in a program when using the real-mode compiler (i.e.
       a binary that was compiled by Borland Pascal).  When using the 32-bit compiler, the
       limit is set to 1024.  You can change this by redefining the maxunits constant in the
       files.pas compiler source file.


                                                             97


Appendix   D


Compiler   modes



Here we list the exact effect of the different compiler modes.  They can be set with the $Mode
switch, or by command line switches.
D.1         FPC  mode


This mode is selected by the $MODE  FPC switch.  On the command-line, this means that you
use none of the other compatibility mode switches.  It is the default mode of the compiler.
This means essentially:


   1.  You must use the address operator to assign procedural variables.

   2.  A forward declaration must be repeated exactly the same by the implementation of a
       function/procedure.  In particular, you can not omit the parameters when implementing
       the function or procedure.

   3.  Overloading of functions is allowed.

   4.  Nested comments are allowed.

   5.  The Objpas unit is NOT loaded.

   6.  You can use the cvar type.

   7.  PChars are converted to strings automatically.
D.2         TP  mode


This mode is selected by the $MODE  TP switch.  On the command-line, this mode is selected
by the -So switch.


   1.  You cannot use the address operator to assign procedural variables.

   2.  A forward declaration must not be repeated exactly the same by the implementation of
       a function/procedure.  In particular, you can omit the parameters when implementing
       the function or procedure.

   3.  Overloading of functions is not allowed.

   4.  The Objpas unit is NOT loaded.



                                                             98

______________________________________________________________________________________________________D.3.___DELPHI_MODE___________*
 *___
   5.  Nested comments are not allowed.

   6.  You can not use the cvar type.
D.3         Delphi  mode


This  mode  is  selected  by  the  $MODE  DELPHI  switch.   On  the  command-line,  this  mode  is
selected by the -Sd switch.


   1.  You can not use the address operator to assign procedural variables.

   2.  A forward declaration must not be repeated exactly the same by the implementation of
       a function/procedure.  In particular, you not omit the parameters when implementing
       the function or procedure.

   3.  Overloading of functions is not allowed.

   4.  Nested comments are not allowed.

   5.  The Objpas unit is loaded right after the system unit.  One of the consequences of this
       is that the type Integer is redefined as Longint.
D.4         GPC  mode


This mode is selected by the $MODE  GPC switch.  On the command-line, this mode is selected
by the -Sp switch.


   1.  You must use the address operator to assign procedural variables.

   2.  A forward declaration must not be repeated exactly the same by the implementation of
       a function/procedure.  In particular, you can omit the parameters when implementing
       the function or procedure.

   3.  Overloading of functions is not allowed.

   4.  The Objpas unit is NOT loaded.

   5.  Nested comments are not allowed.

   6.  You can not use the cvar type.
D.5         OBJFPC  mode


This  mode  is  selected  by  the  $MODE  OBJFPC  switch.   On  the  command-line,  this  mode  is
selected by the -S2 switch.


   1.  You must use the address operator to assign procedural variables.

   2.  A forward declaration must be repeated exactly the same by the implementation of a
       function/procedure.  In particular, you can not omit the parameters when implementing
       the function or procedure.

   3.  Overloading of functions is allowed.

   4.  Nested comments are allowed.



                                                                 99

_____________________________________________________________________________________________________D.5.___OBJFPC_MODE____________*
 *___
   5.  The Objpas unit is loaded right after the system unit.  One of the consequences of this
       is that the type Integer is redefined as Longint.

   6.  You can use the cvar type.

   7.  PChars are converted to strings automatically.
                                                                100


Appendix   E


Using   fpcmake
E.1         Introduction


Free Pascal comes with a special makefile tool, fpcmake, which can be used to construct a
Makefile for use with gnu make.  All sources from the Free Pascal team are compiled with
this system.

fpcmake uses a file Makefile.fpc and constructs a file Makefile from it, based on the settings
in Makefile.fpc.

The following sections explain what settings can be set in Makefile.fpc,  what variables are
set by fpcmake, what variables it expects to be set, and what targets it defines.  After that,
some settings in the resulting Makefile are explained.
E.2         Usage


fpcmake reads a Makefile.fpc and converts it to a Makefile suitable for reading by gnu make
to compile your projects.  It is similar in functionality to GNU configure or Imake for making
X projects.

fpcmake accepts filenames of makefile description files as it's command-line arguments.  For
each  of  these  files  it  will  create  a  Makefile  in  the  same  directory  where  the  file  is  located,
overwriting any existing file with that name.

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.
E.3         Format  of  the  configuration  file


This section describes the rules that can be present in the file that is fed to fpcmake.

The file Makefile.fpc is a plain ASCII file that contains a number of pre-defined sections as
in a Windows 32-bit .ini-file, or a Samba configuration file.

They look more or less as follows:


[targets]
units=mysql_com  mysql_version  mysql
examples=testdb

                                                            101

_____________________________________________________________E.3.___FORMAT_OF_THE_CONFIGURATION_FILE_______________________________*
 *___
[dirs]
fpcdir=../..


[rules]
mysql$(PPUEXT):  mysql$(PASEXT)  mysql_com$(PPUEXT)
testdb$(EXEEXT):  testdb$(PASEXT)  mysql$(PPUEXT)


The following sections are recognized (in alphabetical order):
E.3.1        Clean

Specifies  rules  for  cleaning  the  directory  of  units  and  programs.  The  following  entries  are
recognized:


units    names of all units that should be removed when cleaning.  Don't specify extensions,
       the makefile will append these by itself.

files  names of files that should be removed.  Specify full filenames.
E.3.2        Defaults

The defaults section contains some default settings.  The following keywords are recognized:


defaultdir

defaultbuilddir

defaultinstalldir

defaultzipinstalldir

defaultcleandir

defaultrule       Specifies the default rule to execute.  fpcmake will make sure that this rule is
       executed if make is executed without arguments, i.e., without an explicit target.

defaulttarget         Specifies the default operating system target for which the Makefile should
       compile the units and programs.  By default this is determined from the default com-
       piler target.

defaultcpu        Specifies the default target processor for which the Makefile should compile the
       units and programs.  By default this is determined from the default compiler processor.
E.3.3        Dirs

In  this  section  you  can  specify  the  location  of  several  directories  which  the  Makefile  could
need for compiling other packages or for finding the units.

The following keywords are recognised:


fpcdir    Specifies  the  directory  where  all  the  Free  Pascal  source  trees  reside.   Below  this
       directory the Makefile expects to find the rtl, fcl and packages directory trees.

packagedir        Specifies the directory where all the package source directories are.  By default
       this equals $(FPCDIR)/packages.

toolkitdir      Specifies the directory where toolkit source directories are.



                                                                102

_____________________________________________________________E.3.___FORMAT_OF_THE_CONFIGURATION_FILE_______________________________*
 *___
componentdir           Specifies the directory where component source directories are.

unitdir     A colon-separated list of directories that must be added to the unit search path of
       the compiler.

libdir    A colon-separated list of directories that must be added to the library search path of
       the compiler.

objdir     A colon-separated list of directories that must be added to the object file search path
       of the compiler.

targetdir      Specifies the directory where the compiled programs should go.

sourcesdir       A space separated list of directories where sources can reside.  This will be used
       for the vpath setting of  gnu make.

unittargetdir         Specifies the directory where the compiled units should go.

incdir    A  colon-separated  list  of  directories  that  must  be  added  to  the  include  file  search
       path of the compiler.
E.3.4        Info

This section can be used to customize the information generating targets that fpcmake gen-
erates.  It is simply a series of boolean values that specify whether a certain part of the info
target will be generated.  The following keywords are recognised:


infoconfig      Specifies whether configuration info should be shown.  By default this is True.

infodirs     Specifies whether a list of subdirectories to be treated will be shown.  By degault
       this is False.

infotools      Specifies whether a list of tools that are used by the makefile will be shown.  By
       default this is False.

infoinstall      Specifies whether the installation rules will be shown.  By default this is True.

infoobjects       Specifies whether the Makefile objects will be shown, i.e.  a list of all units and
       programs that will be built by make.
E.3.5        Install

Contains instructions for installation of your units and programs.  The following keywords
are recognized:


dirprefix      is  the  directory  below  wchich  all  installs  are  done.   This  corresponds  to  the
       --prefix argument to gnu configure.  It is used for the installation of programs and
       units.  By default, this is /usr on linux, and /pp on all other platforms.

dirbase     The directory that is used as the base directory for the installation of units.  De-
       fault this is dirprefix appended with /lib/fpc/FPC_VERSION for linux or simply the
       dirprefix on other platforms.


Units will be installed in the subdirectory units/$(OS_TARGET) of the dirbase entry.
                                                                103

_____________________________________________________________E.3.___FORMAT_OF_THE_CONFIGURATION_FILE_______________________________*
 *___
E.3.6        Libs

This section specifies what units should be merged into a library, and what external libraries
are needed.  It can contain the following keywords:


libname       the name of the library that should be created.

libunits     a comma-separated list of units that should be moved into one library.

needgcclib       a boolean value that specifies whether the gcc library is needed.  This will make
       sure that the path to the GCC library is inserted in the library search path.

needotherlib         (linux  only)  a  boolean  value  that  tells  the  makefile  that  it  should  add  all
       library directories from the ld.so.conf  file to the compiler command-line.
E.3.7        Packages

Which packages must be used.  This section can contain the following keywords:


packages       A comma-separated list of packages that are needed to compile the targets.  Valid
       for  all  platforms.   In  order  to  differentiate  between  platforms,  you  can  prepend  the
       keyword packages with the OS you are compiling for, e.g.  linuxpackages if you want
       the makefile to use the listed packages on linux only.

fcl  This is a boolean value (0 or 1) that indicates whether the FCL is used.

rtl  This is a boolean value (0 or 1) that indicates whether the RTL should be recompiled.
E.3.8        Postsettings

Anything that is in this section will be inserted as-is in the makefile after  the makefile rules
that are generated by fpcmake, but before  the general configuration rules.  In this section,
you cannot use variables that are defined by fpcmake rules,  but you can define additional
rules and configuration variables.
E.3.9        Presettings

Anything that is in this section will be inserted as-is in the makefile before the makefile target
rules that are generated by fpcmake.  This means that you cannot use any variables that are
normally defined by fpcmake rules.
E.3.10         Rules

In this section you can insert dependency rules and any other targets you wish to have.  Do
not insert 'default rules' here.
E.3.11         Sections

Here you can specify which 'rule sections' should be included in the Makefile.  The sections
consist of a series of boolean keywords; each keyword decies whether a particular section will
be written to the makefile.  By default, all sections are written.

You can have the following boolean keywords in this section.


none     If this is set to true, then no sections are written.



                                                                104

_____________________________________________________________E.3.___FORMAT_OF_THE_CONFIGURATION_FILE_______________________________*
 *___
units    If set to False, fpcmake omits the rules for compiling units.

exes    If set to False, fpcmake omits the rules for compiling executables.

loaders     If set to False, fpcmake omits the rules for assembling assembler files.

examples        If set to False, fpcmake omits the rules for compiling examples.

package      If set to False, fpcmake omits the rules for making packages.

compile      If set to False, fpcmake omits the generic rules for compiling pascal files.

depend       If set to False, fpcmake omits the dependency rules.

install    If set to False, fpcmake omits the rules for installing everything.

sourceinstall        If set to False, fpcmake omits the rules for installing the sources.

zipinstall     If set to False, fpcmake omits the rules for installing archives.

clean    If set to False, fpcmake omits the rules for cleaning the directories.

libs   If set to False, fpcmake omits the rules for making libraries.

command         If set to False, fpcmake omits the rules for composing the command-line based
       on the various variables.

exts   If set to False, fpcmake omits the rules for making libraries.

dirs   If set to False, fpcmake omits the rules for running make in subdirectories..

tools    If set to False, fpcmake omits the rules for running some tools as the erchiver, UPX
       and zip.

info   If set to False, fpcmake omits the rules for generating information.
E.3.12         Targets

In this section you can define the various targets.  The following keywords can be used there:


dirs   A space separated list of directories where make should also be run.

examples        A space separated list of example programs that need to be compiled when the
       user asks to compile the examples.  Do not specify an extension, the extension will be
       appended.

loaders     A space separated list of names of assembler files that must be assembled.  Don't
       specify the extension, the extension will be appended.

programs        A  space  separated  list  of  program  names  that  need  to  be  compiled.   Do  not
       specify an extension, the extension will be appended.

rst  a  list  of  rst  files  that  needs  to  be  converted  to  .po  files  for  use  with  gnu  gettext  and
       internationalization routines.

units    A  space  separated  list  of  unit  names  that  need  to  be  compiled.  Do  not  specify  an
       extension, just the name of the unit as it would appear un a uses clause is sufficient.

                                                                105

_______________________________E.4.___PROGRAMS_NEEDED_TO_USE_THE_GENERATED_MAKEFILE________________________________________________*
 *___
E.3.13         Tools

In this section you can specify which tools are needed.  Definitions to use each of the listed
tools will be inserted in the makefile, depending on the setting in this section.

Each keyword is a boolean keyword; you can switch the use of a tool on or off with it.

The following keywords are recognised:


toolppdep        Use ppdep, the dependency tool.  True by default.

toolppumove          Use ppumove, the Free Pascal unit mover.  True by default.

toolppufiles       Use the ppufile tool to determine dependencies of unit files.  True by default.

toolsed     Use sed the stream line editor.  False by default.

tooldata2inc         Use the data2inc tool to create include files from data files.  False by default.

tooldiff    Use the gnu diff  tool.  False by default.

toolcmp       Use the cmp file comparer tool.  False by default.

toolupx      Use the upx executable packer.True by default.

tooldate      use the date date displaying tool.  True by default.

toolzip     Use the zip file archiver.  This is used by the zip targets.  True by default.
E.3.14         Zip

This section can be used to make zip files from the compiled units and programs.  By default
all compiled units are zipped.  The zip behaviour can be influenced with the presettings and
postsettings sections.

The following keywords can be used in this unit:


zipname       this file is the name of the zip file that will be produced.

ziptarget      is the name of a makefile target that will be executed before the zip is made.  By
       default this is the install target.
E.4         Programs  needed  to  use  the  generated  makefile


The following programs are needed by the generated Makefile to function correctly:


cp   a copy program.

date    a program that prints the date.

install    a program to install files.

make     the make program, obviously.

pwd     a program that prints the current working directory.

rm    a program to delete files.
                                                                106

___________________________________E.5.___VARIABLES_THAT_AFFECT_THE_GENERATED_MAKEFILE_____________________________________________*
 *___
These  are  standard  programs  on  linux  systems,  with  the  possible  exception  of  make.  For
dos or Windows NT, they can be found in the file gnuutils.zip on the Free Pascal FTP site.

The following programs are optionally needed if you use some special targets.  Which ones
you need are controlled by the settings in the tools section.


cmp     a dos and Windows NT file comparer.  Used if  toolcmp is True.

diff  a file comparer.  Used if  tooldiff is True.

ppdep      the ppdep depency lister.  Used if toolppdep is True.  Distributed with Free Pascal.

ppufiles     the ppufiles unit file dependency lister.  Used if toolppufiles is True.  Distributed
       with Free Pascal.

ppumove        the Free Pascal unit mover.  Used if toolppumove is True.  Distributed with Free
       Pascal.

sed   the sed program.  Used if  toolsed is True.

upx    the UPX executable packer.  Used if  toolupx is True.

zip   the zip archiver program.  Used if  toolzip is True.


All  of  these  can  also  be  found  on  the  Free  Pascal  FTP  site  for  dos  and  Windows  NT.
ppdep,ppufiles and ppumove are distributed with the Free Pascal compiler.
E.5         Variables  that  affect  the  generated  makefile


The makefile generated by fpcmake contains a lot of variables.  Some of them are set in the
makefile itself, others can be set and are taken into account when set.

These variables can be split in several groups:


    o  Environment variables.

    o  Directory variables.

    o  Compiler command-line variables.


Each group will be discussed separately.
E.5.1        Environment  variables

In  principle,  fpcmake  doesn't  expect  any  environment  variable  to  be  set.  Optionally,  you
can set the variable FPCMAKEINI which should contain the name of a file with the basic rules
that fpcmake will generate.

By default, fpcmake has a compiled-in copy of fpcmake.ini, which contains the basic rules, so
there should be no need to set this variable.  You can set it however, if you wish to change
the way in which fpcmake works and creates rules.

The initial fpcmake.ini file can be found in the utils source package on the Free Pascal ftp
site.

                                                                107

______________________________________________________________________________E.6.___VARIABLES_SET_BY_FPCMAKE______________________*
 *___
E.5.2        Directory  variables

The first set of variables controls the directories that are recognised in the makefile.  They
should not be set in the Makefile.fpc file, but can be specified on the commandline.


INCDIR         this  is  a  list  of  directories,  separated  by  spaces,  that  will  be  added  as  include
       directories to the compiler command-line.  Each directory in the list is prepended with
       -I and added to the compiler options.

LIBDIR        is  a  list  of  library  paths,  separated  by  spaces.   Each  directory  in  the  list  is
       prepended with -Fl and added to the compiler options.

OBJDIR         is a list of object file directories, separated by spaces, that is added to the object
       files path, i.e.  Each directory in the list is prepended with -Fo.
E.5.3        Compiler  command-line  variables

The  following  variable  can  be  set  on  the  make  command-line,  they  will  be  recognised  and
integrated in the compiler command-line:


OPT      Any  options  that  you  want  to  pass  to  the  compiler.  The  contents  of  OPT  is  simply
       added to the compiler command-line.

OPTDEF          Are optional defines, added to the command-line of the compiler.  They do not
       get -d prepended.
E.6         Variables  set  by  fpcmake


All of the following variables are only set by  fpcmake, if they aren't already defined.  This
means that you can override them by setting them on the make commandline, or setting them
in the presettings section.  But most of them are correctly determined by the generated
Makefile or set by your settings in the configuration file.

The following sets of variables are defined:


    o  Directory variables.

    o  Program names.

    o  File extensions.

    o  Target files.


Each of these sets is discussed in the subsequent:
E.6.1        Directory  variables

The following directories are defined by the makefile:


BASEDIR           is set to the current directory if the pwd command is available.  If not, it is set
       to '.'.

BASEINSTALLDIR                   is the base for all directories where units are installed.  By default,
       On linux, this is set to $(PREFIXINSTALLDIR)/lib/fpc/$(RELEASEVER).
       On  other  systems,  it  is  set  to  $(PREFIXINSTALLDIR).  You  can  also  set  it  with  the
       basedir variable in the Install section.



                                                                108

______________________________________________________________________________E.6.___VARIABLES_SET_BY_FPCMAKE______________________*
 *___
BININSTALLDIR                 is set to $(BASEINSTALLDIR)/bin on linux, and
       $(BASEINSTALLDIR)/bin/$(OS_TARGET)  on  other  systems.   This  is  the  place  where
       binaries are installed.

GCCLIBDIR             (linux only) is set to the directory where libgcc.a is.  If  needgcclib is set
       to True in the Libs section, then this directory is added to the compiler commandline
       with -Fl.

LIBINSTALLDIR                 is set to $(BASEINSTALLDIR) on linux,
       and $(BASEINSTALLDIR)/lib on other systems.

NEEDINCDIR               is  a  space-separated  list  of  library  paths.   Each  directory  in  the  list  is
       prepended with -Fl and added to the compiler options.  Set by the incdir keyword in
       the Dirs section.

NEEDLIBDIR              is  a  space-separated  list  of  library  paths.   Each  directory  in  the  list  is
       prepended with -Fl and added to the compiler options.  Set by the libdir keyword in
       the Dirs section.

NEEDOBJDIR               is a list of object file directories, separated by spaces.  Each directory in
       the list is prepended with -Fo and added to the compiler options.  Set by the objdir
       keyword in the Dirs section.

NEEDUNITDIR                 is a list of unit directories, separated by spaces.  Each directory in the
       list is prepended with -Fu and is added to the compiler options.  Set by the unitdir
       keyword in the Dirs section.

TARGETDIR              This directory is added as the output directory of the compiler, where all
       units and executables are written, i.e.  it gets -FE prepended.  It is set by the targtdir
       keyword in the Dirs section.

TARGETUNITDIR                    If set, this directory is added as the output directory of the compiler,
       where all units and executables are written, i.e.  it gets -FU prepended.It is set by the
       targtdir keyword in the Dirs section.

PREFIXINSTALLDIR                     is  set  to  /usr  on  linux,  /pp  on  dos  or  Windows  NT.  Set  by
       the dirprefix keyword in the Install section.

UNITINSTALLDIR                   is where units will be installed.  This is set to
       $(BASEINSTALLDIR)/$(UNITPREFIX)
       on linux.  On other systems, it is set to
       $(BASEINSTALLDIR)/$(UNITPREFIX)/$(OS_TARGET).
E.6.2        Target  variables

The second set of variables controls the targets that are constructed by the makefile.  They
are created by fpcmake, so you can use them in your rules, but you shouldn't assign values
to them yourself.


EXEOBJECTS               This  is  a  list  of  executable  names  that  will  be  compiled.   the  makefile
       appends $(EXEEXT) to these names.  It is set by the programs keyword in the Targets
       section.

LOADEROBJECTS                    is a list of space-separated names that identify loaders to be com-
       piled.  This  is  mainly  used  in  the  compiler's  RTL  sources.  It  is  set  by  the  loaders
       keyword in the Targets section.

                                                                109

______________________________________________________________________________E.6.___VARIABLES_SET_BY_FPCMAKE______________________*
 *___
UNITOBJECTS                This is a list of unit names that will be compiled.  The makefile appends
       $(PPUEXT)  to  each  of  these  names  to  form  the  unit  file  name.   The  sourcename  is
       formed by adding $(PASEXT). It is set by the units keyword in the Targets section.

ZIPNAME            is the name of the archive that will be created by the makefile.  It is set by the
       zipname keyword in the Zip section.

ZIPTARGET             is  the  target  that  is  built  before  the  archive  is  made.  this  target  is  built
       first.  If successful, the zip archive will be made.  It is set by the ziptarget keyword in
       the Zip section.
E.6.3        Compiler  command-line  variables

The following variables control the compiler command-line:


CPU__SOURCE              the target CPU type is added as a define to the compiler command line.
       This is determined by the Makefile itself.

CPU__TARGET               the target CPU type is added as a define to the compiler command line.
       This is determined by the Makefile itself.

LIBNAME            if a shared library is requested this is the name of the shared library to produce.
       Don't add lib to this, the compiler will do that.  It is set by the libname keyword in
       the Libs section.

NEEDGCCLIB                if this variable is defined, then the path to libgcc is added to the library
       path.  It is set by the needgcclib keyword in the Libs section.

NEEDOTHERLIB                   (linux  only)  If  this  is  defined,  then  the  makefile  will  append  all
       directories  that  appear  in  /etc/ld.so.conf  to  the  library  path.   It  is  set  by  the
       needotherlib keyword in the Libs section.

OS__TARGET            What platform you want to compile for.  Added to the compiler command-
       line with a -T prepended.
E.6.4        Program  names

The following variables are program names, used in makefile targets.


AS    The assembler.  Default set to as.

COPY        a file copy program.  Default set to cp -fp.

CMP       a program to compare files.  Default set to cmp.

DEL     a file removal program.  Default set to rm -f.

DELTREE           a directory removal program.  Default set to rm -rf.

DATE       a program to display the date.

DIFF      a program to produce diff files.

ECHO        an echo program.

FPC     the Free Pascal compiler executable.  Default set to ppc386.exe

INSTALL          a program to install files.  Default set to install -m 644 on linux.



                                                                110

______________________________________________________________________________E.6.___VARIABLES_SET_BY_FPCMAKE______________________*
 *___
INSTALLEXE              a program to install executable files.  Default set to install -m 755 on linux.

LD    The linker.  Default set to ld.

LDCONFIG             (linux only) the program used to update the loader cache.

MKDIR         a  program  to  create  directories  if  they  don't  exist  yet.  Default  set  to  install  -m
       755 -d

MOVE        a file move program.  Default set to mv -f

PP    the Free Pascal compiler executable.  Default set to ppc386.exe

PPAS      the name of the shell script created by the compiler if the -s option is specified.  This
       command will be executed after compilation, if the -s option was detected among the
       options.

PPUMOVE             the program to move units into one big unit library.

SED     a stream-line editor program.  Default set to sed.

UPX      an  executable  packer  to  compress  your  executables  into  self-extracting  compressed
       executables.

ZIPPROG           a zip program to compress files.  zip targets are made with this program
E.6.5        File  extensions

The following variables denote extensions of files.  These variables include the .  (dot) of the
extension.  They are appended to object names.


ASMEXT           is the extension of assembler files produced by the compiler.

LOADEREXT               is the extension of the assembler files that make up the executable startup
       code.

OEXT       is the extension of the object files that the compiler creates.

PACKAGESUFFIX                    is a suffix that is appended to package names in zip targets.  This
       serves so packages can be made for different OSes.

PASEXT          is  the  extension  of  pascal  files  used  in  the  compile  rules.   It  is  determined  by
       looking at the first EXEOBJECTS source file or the first UNITOBJECTS files.

PPLEXT          is the extension of shared library unit files.

PPUEXT          is the extension of default units.

SHAREDLIBEXT                  is the extension of shared libraries.

SMARTEXT              is the extension of smartlinked unit assembler files.

STATICLIBEXT                is the extension of static libraries.



                                                                111

____________________________________________________E.7.___RULES_AND_TARGETS_CREATED_BY_FPCMAKE____________________________________*
 *___
E.6.6        Target  files

The following variables are defined to make targets and rules easier:


COMPILER             is the complete compiler commandline, with all options added, after all Make-
       file variables have been examined.

DATESTR           contains the date.

EXEFILES           is a list of executables that will be created by the makefile.

EXEOFILES            is a list of executable object files that will be created by the makefile.

LOADEROFILES                 is a list of object files that will be made from the loader assembler files.
       This is mainly for use in the compiler's RTL sources.

UNITPPUFILES                a list of unit files that will be made.  This is just the list of unit objects,
       with the correct unit extension appended.

UNITOFILES             a  list  of  unit  object  files  that  will  be  made.  This  is  just  the  list  of  unit
       objects, with the correct object file extension appended.
E.7         Rules  and  targets  created  by  fpcmake


The  makefile.fpc  defines  a  series  of  targets,  which  can  be  called  by  your  own  targets.
They have names that resemble default names (such as 'all',  'clean'),  only they have fpc_
prepended.
E.7.1        Pattern  rules

The makefile makes the following pattern rules:


units    how to make a pascal unit form a pascal source file.

executables        how to make an executable from a pascal source file.

object file      how to make an object file from an assembler file.
E.7.2        Build  rules

The following build targets are defined:


fpc__all   target that builds all units and executables as well as loaders.  If  DEFAULTUNITS is
       defined, executables are excluded from the targets.

fpc__exes     target to make all executables in EXEOBJECTS.

fpc__loaders      target to make all files in LOADEROBJECTS.

fpc__shared       target that makes all units as dynamic libraries.

fpc__smart      target that makes all units as smartlinked units.

fpc__units     target to make all units in UNITOBJECTS.



                                                                112

____________________________________________________E.7.___RULES_AND_TARGETS_CREATED_BY_FPCMAKE____________________________________*
 *___
E.7.3        Cleaning  rules

The following cleaning targets are defined:


fpc__clean     cleans all files that result when fpc_all was made.

fpc__cleanall      is the same as both previous target commands, but also deletes all object, unit
       and assembler files that are present.
E.7.4        archiving  rules

The following archiving targets are defined:


fpc__zipinstall      will  create  an  archive  file  (it's  name  is  taken  from  $(ZIPNAME))  from  the
       compiled units.

fpc__zipsourceinstall          will create an archive file (it's name is taken from $(ZIPNAME)), from
       the sources.


The zip is made uzing the ZIPEXE program.  Under linux, a .tar.gz file is created.
E.7.5        Informative  rules

The following targets produce information about the makefile:


fpc__cfginfo      gives general configuration information:  the location of the makefile, the com-
       piler version, target OS, CPU.

fpc__dirinfo      gives the directories, used by the compiler.

fpc__info    executes all other info targets.

fpc__installinfo       gives all directories where files will be installed.

fpc__objectinfo        lists all objects that will be made.

fpc__toolsinfo       lists all defined tools.
                                                                113


Appendix   F


Compiling   the   compiler   yourself
F.1         Introduction


The Free Pascal team releases at intervals a completely prepared package, with compiler and
units all ready to use, the so-called releases.  After a release, work on the compiler continues,
bugs  are  fixed  and  features  are  added.  The  Free  Pascal  team  doesn't  make  a  new  release
whenever they change something in the compiler, instead the sources are available for anyone
to use and compile.  Compiled versions of RTL and compiler are also made daily, and put on
the web.

There  are,  nevertheless,  circumstances  when  you'll  want  to  compile  the  compiler  yourself.
For instance if you made changes to compiler code, or when you download the compiler via
CVS.

There are essentially 2 ways of recompiling the compiler:  by hand, or using the makefiles.
Each of these methods will be discussed.
F.2         Before  you  begin


To compile the compiler easily,  it is best to keep the following directory structure (a base
directory of  /pp/src is supposed, but that may be different):


/pp/src/Makefile
           /makefile.fpc
           /rtl/linux
                  /inc
                  /i386
                  /...
           /compiler


If you want to use the makefiles, you must use the above directory tree.

The compiler and rtl source are zipped in such a way that if you unzip both files in the same
directory (/pp/src in the above) the above directory tree results.

The  makefile.fpc  and  Makefile  come  from  the  base.zip  file  on  the  ftp  site.   If  you  compile
manually, you don't need them.

There  are  2  ways  to  start  compiling  the  compiler  and  RTL.  Both  ways  must  be  used,  de-
pending  on  the  situation.  Usually,  the  RTL  must  be  compiled  first,  before  compiling  the
                                                            114

_____________________________________________________________________________________F.3.___COMPILING_USING_MAKE___________________*
 *___
compiler, after which the compiler is compiled using the current compiler.  In some special
cases the compiler must be compiled first, with a previously compiled RTL.

How  to  decide  which  should  be  compiled  first?  In  general,  the  answer  is  that  you  should
compile the RTL first.  There are 2 exceptions to this rule:


   1.  The first case is when some of the internal routines in the RTL have changed, or if new
       internal routines appeared.  Since the OLD compiler doesn't know about these changed
       internal routines, it will emit function calls that are based on the old compiled RTL,
       and hence are not correct.  Either the result will not link, or the binary will give errors.

   2.  The second case is when something is added to the RTL that the compiler needs to
       know about (a new default assembler mechanism, for example).


How  to  know  if  one  of  these  things  has  occurred  ?   There  is  no  way  to  know,  except  by
mailing the Free Pascal team.  If you cannot recompile the compiler when you first compile
the RTL, then try the other way.
F.3         Compiling  using  make


When compiling with make it is necessary to have the above directory structure.  Compiling
the compiler is achieved with the target cycle.

Under normal circumstances, recompiling the compiler is limited to the following instructions
(assuming you start in directory /pp/src):


cd  compiler
make  cycle


This will work only if the makefile.fpc is installed correctly and if the needed tools are present
in the PATH. Which tools must be installed can be found in appendix E.

The above instructions will do the following:


   1.  Using  the  current  compiler,  the  RTL  is  compiled  in  the  correct  directory,  which  is
       determined  by  the  OS  you  are  under.   e.g.   under  linux,  the  RTL  is  compiled  in
       directory rtl/linux.

   2.  The compiler is compiled using the newly compiled RTL. If successful, the newly com-
       piled compiler executable is copied to a temporary executable.

   3.  Using the temporary executable from the previous step, the RTL is re-compiled.

   4.  Using the temporary executable and the newly compiled RTL from the last step, the
       compiler is compiled again.


The  last  two  steps  are  repeated  3  times,  until  three  passes  have  been  made  or  until  the
generated compiler binary is equal to the binary it was compiled with.  This process ensures
that the compiler binary is correct.

Compiling for another target:  When you want to compile the compiler for another target,
you  must  specify  the  OS_TARGET  makefile  variable.   It  can  be  set  to  the  following  values:
win32,  go32v2,  os2  and  linux.   As  an  example,  cross-compilation  for  the  go32v2  target
from the win32 target is chosen:


cd  compiler
make  cycle  OS_TARGET=go32v2



                                                                115

    __________________________________________________________________________________________F.4.___COMPILING_BY_HAND_____________*
 *_______
    This will compile the go32v2 RTL, and compile a go32v2 compiler.

    If  you  want  to  compile  a  new  compiler,  but  you  want  the  compiler  to  be  compiled  first
    using  an  existing  compiled  RTL,  you  should  specify  the  all  target,  and  specify  another
    RTL directory than the default (which is the ../rtl/$(OS_TARGET) directory).  For instance,
    assuming that the compiled RTL units are in /pp/rtl, you could type


    cd  compiler
    make  clean
    make  all  UNITDIR=/pp/rtl


    This will then compile the compiler using the RTL units in /pp/rtl.  After this has been done,
    you can do the 'make cycle', starting with this compiler:


    make  cycle  PP=./ppc386


    This will do the make  cycle from above, but will start with the compiler that was generated
    by the make  all instruction.

    In all cases, many options can be passed to make to influence the compile process.  In general,
    the makefiles add any needed compiler options to the command-line, so that the RTL and
    compiler can be compiled.  You can specify additional options (e.g.  optimization options) by
    passing them in OPT.
    F.4         Compiling  by  hand


    Compiling by hand is difficult and tedious, but can be done.  We'll treat the compilation of
    RTL and compiler separately.
    F.4.1       Compiling  the  RTL

    To recompile the RTL, so a new compiler can be built, at least the following units must be
    built, in the order specified:


loaders    the program stubs, that are the startup code for each pascal program.  These files have
           the  .as  extension,  because  they  are  written  in  assembler.   They  must  be  assembled
           with the gnu as assembler.  These stubs are in the OS-dependent directory, except for
           linux,  where  they  are  in  a  processor  dependent  subdirectory  of  the  linux  directory
           (i386 or m68k).

system     the system unit.  This unit is named differently on different systems:

               o  Only on GO32v2, it's called system.

               o  For linux it's called syslinux.

               o  For Windows NT it's called syswin32.

               o  For os/2 it's called sysos2

           This unit resides in the OS-dependent subdirectories of the RTL.

 strings   The strings unit.  This unit resides in the inc subdirectory of the RTL.

     dos   The dos unit.  It resides in the OS-dependent subdirectory of the RTL. Possibly other
           units will be compiled as a consequence of trying to compile this unit (e.g.  on linux,
           the linux unit will be compiled, on go32, the go32 unit will be compiled).



                                                                    116

    __________________________________________________________________________________________F.4.___COMPILING_BY_HAND_____________*
 *_______
objects    the objects unit.  It resides in the inc subdirectory of the RTL.


    To compile these units on a i386, the following statements will do:


    ppc386  -Tlinux  -b-  -Fi../inc  -Fi../i386  -FE.  -di386  -Us  -Sg  syslinux.pp
    ppc386  -Tlinux  -b-  -Fi../inc  -Fi../i386  -FE.  -di386  ../inc/strings.pp
    ppc386  -Tlinux  -b-  -Fi../inc  -Fi../i386  -FE.  -di386  dos.pp
    ppc386  -Tlinux  -b-  -Fi../inc  -Fi../i386  -FE.  -di386  ../inc/objects.pp


    These are the minimum command-line options, needed to compile the RTL.

    For  another  processor,  you  should  change  the  i386  into  the  appropriate  processor.   For
    another operating system (target) you should change the syslinux in the appropriate system
    unit file, and you should change the target OS setting (-T).

    Depending on the target OS there are other units that you may wish to compile, but which
    are not strictly needed to recompile the compiler.  The following units are available for all
    plaforms:


    objpas     Needed for Delphi mode.  Needs -S2 as an option.  Resides in the objpas subdirectory.

    sysutils     many utility functions, like in Delphi.  Resides in the objpas directory, and needs
           -S2 to compile.

    typinfo     functions to access RTTI information, like Delphi.  Resides in the objpas directory.

    math     math functions like in Delphi.  Resides in the objpas directory.

    mmx      extensions for MMX class Intel processors.  Resides in in the i386 directory.

    getopts      a GNU compatible getopts unit.  resides in the inc directory.

    heaptrc      to debug the heap.  resides in the inc directory.
    F.4.2       Compiling  the  compiler

    Compiling the compiler can be done with one statement.  It's always best to remove all units
    from the compiler directory first, so something like


    rm  *.ppu  *.o


    on linux, and on dos


    del  *.ppu
    del  *.o


    After this, the compiler can be compiled with the following command-line:


    ppc386  -Tlinux    -Fu../rtl/linux  -di386  -dGDB  pp.pas


    So, the minimum options are:


       1.  The target OS. Can be skipped if you're compiling for the same target as the compiler
           you're using.

       2.  A  path  to  an  RTL.  Can  be  skipped  if  a  correct  ppc386.cfg  configuration  is  on  your
           system.   If  you  want  to  compile  with  the  RTL  you  compiled  first,  this  should  be
           ../rtl/OS  (replace  the  OS  with  the  appropriate  operating  system  subdirectory  of  the
           RTL).



                                                                    117

__________________________________________________________________________________________F.4.___COMPILING_BY_HAND_________________*
 *___

                             Table F.1:  Possible defines when compiling FPC


   __Define______________________does_what________________________________________________________________________________
     USE_RHIDE                   Generates errors and warnings in a format recognized
                                 by RHIDE.
     TP                          Needed to compile the compiler with Turbo or Borland Pascal.
     Delphi                      Needed to compile the compiler with Delphi from Borland.
     GDB                         Support of the GNU Debugger.
     I386                        Generate a compiler for the Intel i386+ processor family.
     M68K                        Generate a compiler for the M68000 processor family.
     USEOVERLAY                  Compiles a TP version which uses overlays.
     EXTDEBUG                    Some extra debug code is executed.
     SUPPORT_MMX                 only i386:  enables the compiler switch MMX which
                                 allows the compiler to generate MMX instructions.
     EXTERN_MSG                  Don't compile the msgfiles in the compiler, always use
                                 external messagefiles (default for TP).
     NOAG386INT                  no Intel Assembler output.
     NOAG386NSM                  no NASM output.
   __NOAG386BIN__________________leaves_out_the_binary_writer.____________________________________________________________

   3.  A define with the processor you're compiling for.  Required.

   4.  -dGDB is not strictly needed, but is better to add since otherwise you won't be able to
       compile with debug information.

   5.  -Sg  is  needed,  some  parts  of  the  compiler  use  goto  statements  (to  be  specific:  the
       scanner).


So the absolute minimal command line is


ppc386  -di386  -Sg  pp.pas


You can define some other command-line options, but the above are the minimum.  A list of
recognised options can be found in table (F.1).

This list may be subject to change, the source file pp.pas always contains an up-to-date list.

                                                                118
