home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 February / Chip_2000-02_cd.bin / zkuste / freesoft / freepascal / prog.txt < prev    next >
Text File  |  1999-12-19  |  187KB  |  5,563 lines
  1. Free Pascal
  2. Programmers' manual
  3.  
  4.                Programmers' manual for Free Pascal, version 0.99.12
  5.                                                                 1.6
  6.                                                          July 1999
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16. Micha¿el Van Canneyt
  17.  
  18.  
  19.  
  20. Contents
  21.  
  22. 1 Compiler directives                                                                 9
  23.   1.1 Local directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .    9
  24.        $A or $ALIGN: Align Data . . . . . . . . . . . . . . . . . . . . . . . .       9
  25.        $ASMMODE : Assembler mode . . . . . . . . . . . . . . . . . . . . . . .        9
  26.        $B or $BOOLEVAL: Complete boolean evaluation . . . . . . . . . . . . 10
  27.        $C or $ASSERTIONS : Assertion support . . . . . . . . . . . . . . . . . 10
  28.        $DEFINE : Define a symbol . . . . . . . . . . . . . . . . . . . . . . . . 10
  29.        $ELSE : Switch conditional compilation . . . . . . . . . . . . . . . . . 11
  30.        $ENDIF : End conditional compilation . . . . . . . . . . . . . . . . . 11
  31.        $ERROR : Generate error message . . . . . . . . . . . . . . . . . . . . 11
  32.        $F : Far or near functions . . . . . . . . . . . . . . . . . . . . . . . . 11
  33.        $FATAL : Generate fatal error message . . . . . . . . . . . . . . . . . 12
  34.        $GOTO : Support Goto and Label . . . . . . . . . . . . . . . . . . . . 12
  35.        $H or $LONGSTRINGS : Use AnsiStrings . . . . . . . . . . . . . . . . . 13
  36.        $HINT : Generate hint message . . . . . . . . . . . . . . . . . . . . . 13
  37.        $HINTS : Emit hints . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
  38.        $IF : Start conditional compilation . . . . . . . . . . . . . . . . . . . 13
  39.        $IFDEF : Start conditional compilation . . . . . . . . . . . . . . . . . 13
  40.        $IFNDEF : Start conditional compilation . . . . . . . . . . . . . . . . 13
  41.        $IFOPT : Start conditional compilation . . . . . . . . . . . . . . . . . 13
  42.        $INFO : Generate info message . . . . . . . . . . . . . . . . . . . . . 14
  43.        $INLINE : Allow inline code. . . . . . . . . . . . . . . . . . . . . . . . 14
  44.        $I or $IOCHECKS : Input/Output checking . . . . . . . . . . . . . . . 14
  45.        $I or $INCLUDE : Include file . . . . . . . . . . . . . . . . . . . . . . 15
  46.        $I or $INCLUDE : Include compiler info . . . . . . . . . . . . . . . . . 15
  47.        $I386 XXX : Specify assembler format . . . . . . . . . . . . . . . . . 16
  48.        $L or $LINK : Link object file . . . . . . . . . . . . . . . . . . . . . . 16
  49.        $LINKLIB : Link to a library . . . . . . . . . . . . . . . . . . . . . . . 16
  50.        $M or $TYPEINFO : Generate type info . . . . . . . . . . . . . . . . . 17
  51.        $MACRO : Allow use of macros. . . . . . . . . . . . . . . . . . . . . . . 17
  52.  
  53.  
  54.  
  55.                                           1
  56.  
  57.  
  58.  
  59. CONTENTS                                                               CONTENTS
  60.  
  61.  
  62.        $MESSAGE : Generate info message . . . . . . . . . . . . . . . . . . . 17
  63.        $MMX : Intel MMX support . . . . . . . . . . . . . . . . . . . . . . . . 17
  64.        $NOTE : Generate note message . . . . . . . . . . . . . . . . . . . . . 18
  65.        $NOTES : Emit notes . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
  66.        $OUTPUT FORMAT : Specify the output format . . . . . . . . . . . . . 19
  67.        $P or $OPENSTRINGS : Use open strings . . . . . . . . . . . . . . . . . 19
  68.        $PACKENUM : Minimum enumeration type size . . . . . . . . . . . . . 19
  69.        $PACKRECORDS : Alignment of record elements . . . . . . . . . . . . . 19
  70.        $Q $OVERFLOWCHECKS: Overflow checking . . . . . . . . . . . . . . . . 20
  71.        $R or $RANGECHECKS : Range checking . . . . . . . . . . . . . . . . . 20
  72.        $SATURATION : Saturation operations . . . . . . . . . . . . . . . . . . 20
  73.        $SMARTLINK : Use smartlinking . . . . . . . . . . . . . . . . . . . . . 20
  74.        $STATIC : Allow use of Static keyword. . . . . . . . . . . . . . . . . 21
  75.        $STOP : Generate fatal error message . . . . . . . . . . . . . . . . . . 21
  76.        $T or $TYPEDADDRESS : Typed address operator (@) . . . . . . . . . 21
  77.        $UNDEF : Undefine a symbol . . . . . . . . . . . . . . . . . . . . . . . 21
  78.        $V or $VARSTRINGCHECKS : Var-string checking . . . . . . . . . . . . 22
  79.        $WAIT : Wait for enter key press . . . . . . . . . . . . . . . . . . . . . 22
  80.        $WARNING : Generate warning message . . . . . . . . . . . . . . . . . 22
  81.        $WARNINGS : Emit warnings . . . . . . . . . . . . . . . . . . . . . . . 22
  82.        $X or $EXTENDEDSYNTAX : Extended syntax . . . . . . . . . . . . . . 22
  83.   1.2 Global directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
  84.        $APPTYPE : Specify type of application (Win32 only) . . . . . . . . . 23
  85.        $D or $DEBUGINFO: Debugging symbols . . . . . . . . . . . . . . . . . 23
  86.        $DESCRIPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
  87.        $E : Emulation of coprocessor . . . . . . . . . . . . . . . . . . . . . . 23
  88.        $G : Generate 80286 code . . . . . . . . . . . . . . . . . . . . . . . . 24
  89.        $INCLUDEPATH : Specify include path. . . . . . . . . . . . . . . . . . 24
  90.        $L or $LOCALSYMBOLS: Local symbol information . . . . . . . . . . . 24
  91.        $LIBRARYPATH : Specify library path. . . . . . . . . . . . . . . . . . . 25
  92.        $M or $MEMORY: Memory sizes . . . . . . . . . . . . . . . . . . . . . . 25
  93.        $MODE : Set compiler compatibility mode . . . . . . . . . . . . . . . . 25
  94.        $N : Numeric processing . . . . . . . . . . . . . . . . . . . . . . . . . 26
  95.        $O : Overlay code generation . . . . . . . . . . . . . . . . . . . . . . 26
  96.        $OBJECTPATH : Specify object path. . . . . . . . . . . . . . . . . . . . 26
  97.        $S : Stack checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
  98.        $UNITPATH : Specify unit path. . . . . . . . . . . . . . . . . . . . . . 26
  99.        $W or $STACKFRAMES : Generate stackframes . . . . . . . . . . . . . . 27
  100.        $Y or $REFERENCEINFO : Insert Browser information . . . . . . . . . 27
  101.  
  102.  
  103.  
  104.                                         2
  105.  
  106.  
  107.  
  108. CONTENTS                                                                CONTENTS
  109.  
  110.  
  111. 2 Using conditionals, messages and macros                                           28
  112.   2.1 Conditionals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
  113.   2.2 Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
  114.   2.3 Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
  115.  
  116. 3 Using Assembly language                                                           35
  117.   3.1 Intel syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
  118.   3.2 AT&T Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
  119.   3.3 Calling mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
  120.         Ix86 calling conventions . . . . . . . . . . . . . . . . . . . . . . . . 40
  121.         M680x0 calling conventions . . . . . . . . . . . . . . . . . . . . . . 41
  122.   3.4 Signalling changed registers . . . . . . . . . . . . . . . . . . . . . . . 41
  123.   3.5 Register Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
  124.         Intel x86 version    . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
  125.         Motorola 680x0 version . . . . . . . . . . . . . . . . . . . . . . . . . 42
  126.  
  127. 4 Linking issues                                                                    43
  128.   4.1 Using external functions or procedures . . . . . . . . . . . . . . . . . 43
  129.   4.2 Using external variables . . . . . . . . . . . . . . . . . . . . . . . . . 45
  130.   4.3 Linking to an object file . . . . . . . . . . . . . . . . . . . . . . . . . 46
  131.   4.4 Linking to a library . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
  132.   4.5 Making libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
  133.        Exporting functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
  134.        Exporting variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
  135.        Compiling libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
  136.        Moving units into a library . . . . . . . . . . . . . . . . . . . . . . . 50
  137.        Unit searching strategy . . . . . . . . . . . . . . . . . . . . . . . . . 50
  138.   4.6 Using smart linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
  139.  
  140. 5 Objects                                                                           52
  141.   5.1 Constructor and Destructor calls . . . . . . . . . . . . . . . . . . . . 52
  142.   5.2 Memory storage of objects . . . . . . . . . . . . . . . . . . . . . . . . 52
  143.   5.3 The Virtual Method Table . . . . . . . . . . . . . . . . . . . . . . . . 52
  144.  
  145. 6 Generated code                                                                    54
  146.   6.1 Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
  147.   6.2 Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
  148.  
  149. 7 Intel MMX support                                                                 56
  150.   7.1 What is it about ? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
  151.   7.2 Saturation support . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
  152.   7.3 Restrictions of MMX support . . . . . . . . . . . . . . . . . . . . . . 57
  153.  
  154.  
  155.                                          3
  156.  
  157.  
  158.  
  159. CONTENTS                                                                 CONTENTS
  160.  
  161.  
  162.   7.4 Supported MMX operations . . . . . . . . . . . . . . . . . . . . . . . 58
  163.   7.5 Optimizing MMX support . . . . . . . . . . . . . . . . . . . . . . . . 58
  164.  
  165. 8 Memory issues                                                                      59
  166.   8.1 The 32-bit model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
  167.   8.2 The stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
  168.          Intel x86 version    . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
  169.          Motorola 680x0 version . . . . . . . . . . . . . . . . . . . . . . . . . 61
  170.   8.3 The heap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
  171.          The heap grows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
  172.          Using Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
  173.          Using the split heap . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
  174.   8.4 Using dos memory under the Go32 extender . . . . . . . . . . . . . 63
  175.  
  176. 9 Optimizations                                                                      65
  177.   9.1    Non processor specific . . . . . . . . . . . . . . . . . . . . . . . . . 65
  178.          Constant folding . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
  179.          Constant merging . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
  180.          Short cut evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . 65
  181.          Constant set inlining . . . . . . . . . . . . . . . . . . . . . . . . . . 66
  182.          Small sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
  183.          Range checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
  184.          Shifts instead of multiply or divide . . . . . . . . . . . . . . . . . . 66
  185.          Automatic alignment . . . . . . . . . . . . . . . . . . . . . . . . . . 66
  186.          Smart linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
  187.          Inline routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
  188.          Case optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
  189.          Stack frame omission . . . . . . . . . . . . . . . . . . . . . . . . . . 67
  190.          Register variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
  191.          Intel x86 specific . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
  192.          Motorola 680x0 specific     . . . . . . . . . . . . . . . . . . . . . . . . 69
  193.   9.2 Optimization switches . . . . . . . . . . . . . . . . . . . . . . . . . . 69
  194.   9.3 Tips to get faster code . . . . . . . . . . . . . . . . . . . . . . . . . . 70
  195.   9.4    Floating point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
  196.          Intel x86 specific . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
  197.          Motorola 680x0 specific     . . . . . . . . . . . . . . . . . . . . . . . . 71
  198.  
  199. A Anatomy of a unit file                                                             72
  200.   A.1 Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
  201.   A.2 reading ppufiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
  202.   A.3 The Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
  203.  
  204.  
  205.                                           4
  206.  
  207.  
  208.  
  209. CONTENTS                                                                CONTENTS
  210.  
  211.  
  212.   A.4 The sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
  213.   A.5 Creating ppufiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
  214.  
  215. B Compiler and RTL source tree structure                                           77
  216.   B.1 The compiler source tree . . . . . . . . . . . . . . . . . . . . . . . . . 77
  217.   B.2 The RTL source tree . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
  218.  
  219. C Compiler limits                                                                  79
  220.  
  221. D Compiler modes                                                                   80
  222.   D.1 FPC mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
  223.   D.2 TP mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
  224.   D.3 Delphi mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
  225.   D.4 GPC mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
  226.   D.5 OBJFPC mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
  227.  
  228. E Using makefile.fpc                                                               83
  229.   E.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
  230.   E.2 Programs needed to use the makefile . . . . . . . . . . . . . . . . . . 83
  231.   E.3 Variables used by makefile.fpc . . . . . . . . . . . . . . . . . . . . . . 84
  232.        Required variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
  233.        Directory variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
  234.        Target variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
  235.        Compiler command-line variables . . . . . . . . . . . . . . . . . . . . 85
  236.   E.4 Variables set by makefile.fpc . . . . . . . . . . . . . . . . . . . . . . . 86
  237.        Directory variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
  238.        Program names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
  239.        File extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
  240.        Target files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
  241.   E.5 Rules and targets created by makefile.fpc . . . . . . . . . . . . . . . . 89
  242.        Pattern rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
  243.        Build rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
  244.        Cleaning rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
  245.        archiving rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
  246.        Informative rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
  247.   E.6 Using the provided template . . . . . . . . . . . . . . . . . . . . . . . 90
  248.  
  249. F Compiling the compiler yourself                                                  92
  250.   F.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
  251.   F.2 Before you begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
  252.   F.3 Compiling using make . . . . . . . . . . . . . . . . . . . . . . . . . . 93
  253.   F.4 Compiling by hand . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
  254.  
  255.  
  256.                                          5
  257.  
  258.  
  259.  
  260. CONTENTS                                                           CONTENTS
  261.  
  262.  
  263.      Compiling the RTL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
  264.      Compiling the compiler . . . . . . . . . . . . . . . . . . . . . . . . . 95
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.                                      6
  315.  
  316.  
  317.  
  318. List of Tables
  319.  
  320.  1.1 Formats generated by the x86 compiler . . . . . . . . . . . . . . . . . 19
  321.  
  322.  2.1 Symbols defined by the compiler. . . . . . . . . . . . . . . . . . . . . 29
  323.  2.2 Predefined macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
  324.  
  325.  3.1 Calling mechanisms in Free Pascal . . . . . . . . . . . . . . . . . . . 40
  326.  
  327.  5.1 Object memory layout . . . . . . . . . . . . . . . . . . . . . . . . . . 53
  328.  5.2 Virtual Method Table memory layout . . . . . . . . . . . . . . . . . 53
  329.  
  330.  8.1 Stack frame when calling a procedure . . . . . . . . . . . . . . . . . 60
  331.  
  332.  F.1 Possible defines when compiling FPC . . . . . . . . . . . . . . . . . . 96
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.                                       7
  361.  
  362.  
  363.  
  364. LIST OF TABLES                                                    LIST OF TABLES
  365.  
  366.  
  367. About this document
  368.  
  369. This is the programmer's manual for Free Pascal.
  370. It describes some of the peculiarities of the Free Pascal compiler, and provides
  371. a glimpse of how the compiler generates its code, and how you can change the
  372. generated code. It will not, however, provide you with a detailed account of the
  373. inner workings of the compiler, nor will it tell you how to use the compiler (described
  374. in the Users' guide). It also will not describe the inner workings of the Run-Time
  375. Library (RTL). The best way to learn about the way the RTL is implemented is
  376. from the sources themselves.
  377. The things described here are useful if you want to do things which need greater
  378. flexibility than the standard Pascal language constructs. (described in the Reference
  379. guide)
  380. Since the compiler is continuously under development, this document may get out
  381. of date. Wherever possible, the information in this manual will be updated. If you
  382. find something which isn't correct, or you think something is missing, feel free to
  383. contact me1.
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.   1at Michael.VanCanneyt@wisa.be
  417.  
  418.  
  419.                                           8
  420.  
  421.  
  422.  
  423. Chapter 1
  424.  
  425. Compiler directives
  426.  
  427. Free Pascal supports compiler directives in your source file. They are not the same
  428. as Turbo Pascal directives, although some are supported for compatibility. There is
  429. a distinction between local and global directives; local directives take e ect from the
  430. moment they are encountered, global directives have an e ect on all of the compiled
  431. code.
  432. Many switches have a long form also. If they do, then the name of the long form
  433. is given also. For long switches, the + or - character to switch the option on or o ,
  434. may be replaced by ON or OFF keywords.
  435. Thus {$I+} is equivalent to {$IOCHECKS ON} or {$IOCHECKS +} and {$C-} is equiv-
  436. alent to {$ASSERTIONS OFF} or {$ASSERTIONS -}
  437. The long forms of the switches are the same as their Delphi counterparts.
  438.  
  439.  
  440. 1.1 Local directives
  441.  
  442. Local directives can occur more than once in a unit or program, If they have a
  443. command-line counterpart, the command-line artgument is restored as the default
  444. for each compiled file. The local directives influence the compiler's behaviour from
  445. the moment they're encountered until the moment another switch annihilates their
  446. behaviour, or the end of the current unit or program is reached.
  447.  
  448.  
  449. $A or $ALIGN: Align Data
  450. This switch is recognized for Turbo Pascal Compatibility, but is not yet imple-
  451. mented. The alignment of data will be di erent in any case, since Free Pascal is a
  452. 32-bit compiler.
  453.  
  454.  
  455. $ASMMODE : Assembler mode
  456. The {$ASMMODE XXX directive informs the compiler what kind of assembler it can
  457. expect in an asm block. The XXX should be replaced by one of the following:
  458.  
  459. att Indicates that asm blocks contain AT&T syntax assembler.
  460.  
  461. intel Indicates that asm blocks contain Intel syntax assembler.
  462.  
  463.  
  464.                                           9
  465.  
  466.  
  467.  
  468. CHAPTER 1. COMPILER DIRECTIVES                          1.1. LOCAL DIRECTIVES
  469.  
  470.  
  471. direct Tells the compiler that asm blocks should be copied directly to the assem-
  472.         bler file.
  473.  
  474. These switches are local, and retain their value to the end of the unit that is
  475. compiled, unless they are replaced by another directive of the same type. The
  476. command-line switch that corresponds to this switch is -R.
  477.  
  478.  
  479. $B or $BOOLEVAL: Complete boolean evaluation
  480. This switch is understood by the Free Pascal compiler, but is ignored. The com-
  481. piler always uses shortcut evaluation, i.e. the evaluation of a boolean expression is
  482. stopped once the result of the total exression is known with certainty.
  483. So, in the following example, the function Bofu, which has a boolean result, will
  484. never get called.
  485.  
  486. If False and Bofu then
  487.   ...
  488.  
  489.  
  490. $C or $ASSERTIONS : Assertion support
  491. The {$ASSERTION} switch determines if assert statements are compiled into the
  492. binary or not. If the switch is on, the statement
  493.  
  494. Assert(BooleanExpression,AssertMessage);
  495.  
  496. Will be compiled in the binary. If te BooleanExpression evaluates to False, the
  497. RTL will check if the AssertErrorProc is set. If it is set, it will be called with as
  498. parameters the AssertMessage message, the name of the file, the LineNumber and
  499. the address. If it is not set, a runtime error 227 is generated.
  500. The AssertErrorProc is defined as
  501.  
  502. Type
  503.   TAssertErrorProc=procedure(const msg,fname:string;lineno,erroraddr:longint);
  504. VarAssertErrorProc = TAssertErrorProc;
  505. This can be used mainly for debugging purposes. The SYSTEM unit sets the
  506. AssertErrorProc to a handler that displays a message on stderr and simply exits.
  507. The SYSUTILS unit catches the run-time error 227 and raises an EAssertionFailed
  508. exception.
  509.  
  510.  
  511. $DEFINE : Define a symbol
  512. The directive
  513.  
  514. {$DEFINE name}
  515.  
  516. defines the symbol name. This symbol remains defined until the end of the current
  517. module (i.e. unit or program), or until a $UNDEF name directive is encountered.
  518. If name is already defined, this has no e ect. Name is case insensitive.
  519.  
  520.  
  521.  
  522.                                           10
  523.  
  524.  
  525.  
  526. CHAPTER 1. COMPILER DIRECTIVES                          1.1. LOCAL DIRECTIVES
  527.  
  528.  
  529. $ELSE : Switch conditional compilation
  530. The {$ELSE } switches between compiling and ignoring the source text delimited by
  531. the preceding {$IFxxx} and following {$ENDIF}. Any text after the ELSE keyword
  532. but before the brace is ignored:
  533.  
  534. {$ELSE some ignored text}
  535.  
  536. is the same as
  537.  
  538. {$ELSE}
  539.  
  540. This is useful for indication what switch is meant.
  541.  
  542.  
  543. $ENDIF : End conditional compilation
  544. The {$ENDIF} directive ends the conditional compilation initiated by the last {$IFxxx}
  545. directive. Any text after the ENDIF keyword but before the closing brace is ignored:
  546.  
  547. {$ENDIF some ignored text}
  548.  
  549. is the same as
  550.  
  551. {$ENDIF}
  552.  
  553. This is useful for indication what switch is meant to be ended.
  554.  
  555.  
  556. $ERROR : Generate error message
  557. The following code
  558.  
  559. {$ERROR This code is erroneous !}
  560.  
  561. will display an error message when the compiler encounters it, and increase the
  562. error count of the compiler. The compiler will continue to compile, but no code will
  563. be emitted.
  564.  
  565.  
  566. $F : Far or near functions
  567. This directive is recognized for compatibility with Turbo Pascal. Under the 32-bit
  568. programming model, the concept of near and far calls have no meaning, hence the
  569. directive is ignored. A warning is printed to the screen, telling you so.
  570. As an example, : the following piece of code :
  571.  
  572. {$F+}
  573.  
  574. Procedure TestProc;
  575.  
  576. begin
  577.  Writeln ('Hello From TestProc');
  578. end;
  579.  
  580. begin
  581.  testProc
  582. end.
  583.  
  584.                                          11
  585.  
  586.  
  587.  
  588. CHAPTER 1. COMPILER DIRECTIVES                        1.1. LOCAL DIRECTIVES
  589.  
  590.  
  591. Generates the following compiler output:
  592.  
  593. malpertuus: >pp -vw testf
  594. Compiler: ppc386
  595. Units are searched in: /home/michael;/usr/bin/;/usr/lib/ppc/0.9.1/linuxunits
  596. Target OS: Linux
  597. Compiling testf.pp
  598. testf.pp(1) Warning: illegal compiler switch
  599. 7739 kB free
  600. Calling assembler...
  601. Assembled...
  602. Calling linker...
  603. 12 lines compiled,
  604.  1.00000000000000E+0000
  605.  
  606. You can see that the verbosity level was set to display warnings.
  607. If you declare a function as Far (this has the same e ect as setting it between
  608. {$F+}...{$F-} directives), the compiler also generates a warning :
  609.  
  610. testf.pp(3) Warning: FAR ignored
  611.  
  612. The same story is true for procedures declared as Near. The warning displayed in
  613. that case is:
  614.  
  615. testf.pp(3) Warning: NEAR ignored
  616.  
  617.  
  618. $FATAL : Generate fatal error message
  619. The following code
  620.  
  621. {$FATAL This code is erroneous !}
  622.  
  623. will display an error message when the compiler encounters it, and trigger and
  624. increase the error count of the compiler. The compiler will immediatly stop the
  625. compilation process.
  626.  
  627.  
  628. $GOTO : Support Goto and Label
  629. If {$GOTO ON} is specified, the compiler will support Goto statements and Label
  630. declarations. By default, $GOTO OFF is assumed. This directive corresponds to the
  631. -Sg command-line option.
  632. As an example, the following code can be compiled:
  633.  
  634. {$GOTO ON}
  635.  
  636. label Theend;
  637.  
  638. begin
  639.   If ParamCount=0 then
  640.         GoTo TheEnd;
  641.   Writeln ('You spcified command-line options');
  642. TheEnd:
  643. end.
  644.  
  645.                                         12
  646.  
  647.  
  648.  
  649. CHAPTER 1. COMPILER DIRECTIVES                           1.1. LOCAL DIRECTIVES
  650.  
  651.  
  652. $H or $LONGSTRINGS : Use AnsiStrings
  653. If {$LONGSTRINGS ON} is specified, the keyword String (no length specifier) will
  654. be treated as AnsiString, and the compiler will treat the corresponding varible as
  655. an ansistring, and will generate corresponding code.
  656. By default, the use of ansistrings is o , corresponding to {$H-}.
  657. This feature is still experimental, and should be used with caution for the time
  658. being.
  659.  
  660.  
  661. $HINT : Generate hint message
  662. If the generation of hints is turned on, through the -vh command-line option or the
  663. {$HINTS ON} directive, then
  664.  
  665. {$Hint This code should be optimized }
  666.  
  667. will display a hint message when the compiler encounters it.
  668.  
  669.  
  670. $HINTS : Emit hints
  671. {$HINTS ON} switches the generation of hints on. {$HINTS OFF} switches the gen-
  672. eration of hints o . Contrary to the command-line option -vh this is a local switch,
  673. this is useful for checking parts of your code.
  674.  
  675.  
  676. $IF : Start conditional compilation
  677. The directive {$IF expr} will continue the compilation if the boolean expression
  678. expr evaluates to true. If the compilation evaluates to false, then the source are
  679. skipped to the first {$ELSE} or {$ENDIF} directive.
  680. The compiler must be able to evaluate the expression at compile time. This means
  681. that you cannot use variables or constants that are defined in the source. Macros
  682. and symbols may be used, however.
  683. More information on this can be found in the section about conditionals.
  684.  
  685.  
  686. $IFDEF : Start conditional compilation
  687. The {$IFDEF name} will skip the compilation of the text that follows it if the symbol
  688. name is not defined. If it is defined, then compilation continues as if the directive
  689. wasn't there.
  690.  
  691.  
  692. $IFNDEF : Start conditional compilation
  693. The {$IFNDEF name} will skip the compilation of the text that follows it if the
  694. symbol name is defined. If it is not defined, then compilation continues as if the
  695. directive wasn't there.
  696.  
  697.  
  698. $IFOPT : Start conditional compilation
  699. The {$IFOPT switch} will compile the text that follows it if the switch switch is
  700. currently in the specified state. If it isn't in the specified state, then compilation
  701. continues after the corresponding {$ENDIF} directive.
  702.  
  703.                                           13
  704.  
  705.  
  706.  
  707. CHAPTER 1. COMPILER DIRECTIVES                          1.1. LOCAL DIRECTIVES
  708.  
  709.  
  710. As an example:
  711.  
  712. {$IFOPT M+}
  713.   Writeln ('Compiled with type information');
  714. {$ENDIF}
  715.  
  716. Will compile the writeln statement if generation of type information is on.
  717. Remark: The {$IFOPT} directive accepts only short options, i.e. {$IFOPT TYPEINFO}
  718. will not be accepted.
  719.  
  720.  
  721. $INFO : Generate info message
  722. If the generation of info is turned on, through the -vi command-line option, then
  723.  
  724. {$INFO This was coded on a rainy day by Bugs Bunny }
  725.  
  726. will display an info message when the compiler encounters it.
  727.  
  728.  
  729. $INLINE : Allow inline code.
  730. The {$INLINE ON} directive tells the compiler that the Inline procedure modifier
  731. should be allowed. Procedures that are declared inline are copied to the places
  732. where they are called. This has the e ect that there is no actual procedure call, the
  733. code of the procedure iis just copied to where the procedure is needed. By default,
  734. Inline procedures are not allowed. You need to specify this directive if you want
  735. to use inlined code. This directive is equivalent to the command-line switch -Si.
  736. Inline code is NOT exported from a unit. This means that if you call an inline
  737. procedure from another unit, a normal procedure call will be performed. Only
  738. inside units, Inline procedures are really inline.
  739.  
  740.  
  741. $I or $IOCHECKS : Input/Output checking
  742. The {$I-} or {$IOCHECKS OFF} directive tells the compiler not to generate in-
  743. put/output checking code in your program. By default, the compiler does not
  744. generate this code, you must switch it on using the -Ci command-lne switch.
  745. If you compile using the -Ci compiler switch, the Free Pascal compiler inserts
  746. input/output checking code after every input/output call in your program. If an
  747. error occurred during input or output, then a run-time error will be generated. Use
  748. this switch if you wish to avoid this behavior. If you still want to check if something
  749. went wrong, you can use the IOResult function to see if everything went without
  750. problems.
  751. Conversely, {$I+} will turn error-checking back on, until another directive is en-
  752. countered which turns it o  again.
  753. The most common use for this switch is to check if the opening of a file went without
  754. problems, as in the following piece of code:
  755.  
  756. ...
  757. assign (f,'file.txt');
  758. {$I-}
  759. rewrite (f);
  760. {$I+}
  761.  
  762.                                           14
  763.  
  764.  
  765.  
  766. CHAPTER 1. COMPILER DIRECTIVES                            1.1. LOCAL DIRECTIVES
  767.  
  768.  
  769. if IOResult<>0 then
  770.   begin
  771.   Writeln ('Error opening file : "file.txt"');
  772.   exit
  773.   end;
  774. ...
  775.  
  776.  
  777. $I or $INCLUDE : Include file
  778. The {$I filename} or {$INCLUDE filename} directive tells the compiler to read
  779. further statements from the file filename. The statements read there will be in-
  780. serted as if they occurred in the current file.
  781. The compiler will append the .pp extension to the file if you don't specify an exten-
  782. sion yourself. Do not put the filename between quotes, as they will be regarded as
  783. part of the file's name.
  784. You can nest included files, but not infinitely deep. The number of files is restricted
  785. to the number of file descriptors available to the Free Pascal compiler.
  786. Contrary to Turbo Pascal, include files can cross blocks. I.e. you can start a block
  787. in one file (with a Begin keyword) and end it in another (with a End keyword).
  788. The smallest entity in an include file must be a token, i.e. an identifier, keyword or
  789. operator.
  790. The compiler will look for the file to include in the following places:
  791.  
  792.    1. It will look in the path specified in the include file name.
  793.  
  794.    2. It will look in the directory where the current source file is.
  795.  
  796.    3. it will look in all directories specified in the include file search path.
  797.  
  798. You can add directories to the include file search path with the -I command-line
  799. option.
  800.  
  801.  
  802. $I or $INCLUDE : Include compiler info
  803. In this form:
  804.  
  805. {$INCLUDE %xxx%}
  806.  
  807. where xxx is one of TIME, DATE, FPCVERSION or FPCTARGET, will generate a macro
  808. with the value of these things. If xxx is none of the above, then it is assumed to be
  809. the value of an environment variable. It's value will be fetched, and inserted in the
  810. code as if it were a string.
  811. For example, the following program
  812.  
  813. Program InfoDemo;
  814.  
  815. Const User = {$I %USER%};
  816.  
  817. begin
  818.   Write ('This program was compiled at ',{$I %TIME%});
  819.   Writeln (' on ',{$I %DATE%});
  820.   Writeln ('By ',User);
  821.  
  822.                                            15
  823.  
  824.  
  825.  
  826. CHAPTER 1. COMPILER DIRECTIVES                           1.1. LOCAL DIRECTIVES
  827.  
  828.  
  829.   Writeln ('Compiler version : ',{$I %FPCVERSION%});
  830.   Writeln ('Target CPU : ',{$I %FPCTARGET%});
  831. end.
  832.  
  833. Creates the following output :
  834.  
  835. This program was compiled at 17:40:18 on 1998/09/09
  836. By michael
  837. Compiler version : 0.99.7
  838. Target CPU : i386
  839.  
  840.  
  841. $I386 XXX : Specify assembler format
  842. This switch selects the assembler reader. {$I386 XXX} has the same e ect as
  843. {$ASMMODE XXX}, section 1.1, page 9
  844.  
  845.  
  846. $L or $LINK : Link object file
  847. The {$L filename} or {$LINK filename} directive tells the compiler that the file
  848. filename should be linked to your program.
  849. The compiler will look for this file in the following way:
  850.  
  851.   1. It will look in the path specified in the object file name.
  852.  
  853.   2. It will look in the directory where the current source file is.
  854.  
  855.   3. it will look in all directories specified in the object file search path.
  856.  
  857. You can add directories to the object file search path with the -Fo option.
  858. On linux systems, the name is case sensitive, and must be typed exactly as it
  859. appears on your system.
  860. Remark : Take care that the object file you're linking is in a format the linker
  861. understands. Which format this is, depends on the platform you're on. Typing ld
  862. on the command line gives a list of formats ld knows about.
  863. You can pass other files and options to the linker using the -k command-line option.
  864. You can specify more than one of these options, and they will be passed to the linker,
  865. in the order that you specified them on the command line, just before the names of
  866. the object files that must be linked.
  867.  
  868.  
  869. $LINKLIB : Link to a library
  870. The {$LINKLIB name} will link to a library name. This has the e ect of passing
  871. -lname to the linker.
  872. As an example, consider the following unit:
  873.  
  874. unit getlen;
  875.  
  876. interface
  877. {$LINKLIB c}
  878.  
  879. function strlen (P : pchar) : longint;cdecl;
  880.  
  881.                                           16
  882.  
  883.  
  884.  
  885. CHAPTER 1. COMPILER DIRECTIVES                        1.1. LOCAL DIRECTIVES
  886.  
  887.  
  888.  
  889. implementation
  890.  
  891. function strlen (P : pchar) : longint;cdecl;external;
  892.  
  893. end.
  894.  
  895. If one would issue the command
  896.  
  897. ppc386 foo.pp
  898.  
  899. where foo.pp has the above unit in its uses clause, then the compiler would link
  900. your program to the c library, by passing the linker the -lc option.
  901. The same e ect could be obtained by removing the linklib directive in the above
  902. unit, and specify -k-lc on the command-line:
  903.  
  904. ppc386 -k-lc foo.pp
  905.  
  906.  
  907. $M or $TYPEINFO : Generate type info
  908. For classes that are compiled in the {$M+ } or {$TYPEINFO ON} state, the compiler
  909. will generate Run-Time Type Information (RTTI). All descendent objects of an
  910. object that was compiled in the {$M+} state will get RTTI information too, as well
  911. as any published classes. By default, no Run-Time Type Information is generated.
  912. The TPersistent object that is present in the FCL (Free Component Library)
  913. is generated in the {$M+} state. The generation of RTTI allows programmers to
  914. stream objects, and to access published properties of objects, without knowing the
  915. actual class of the object.
  916. The run-time type information is accessible through the TypInfo unit, which is part
  917. of the Free Pascal Run-Time Library.
  918.  
  919.  
  920. $MACRO : Allow use of macros.
  921. In the {$MACRO ON} state, the compiler allows you to use C-style (although not
  922. as elaborate) macros. Macros provide a means for simple text substitution. More
  923. information on using macros can be found in the section 2.3, page 33 section. This
  924. directive is equivalent to the command-line switch -Sm.
  925.  
  926.  
  927. $MESSAGE : Generate info message
  928. If the generation of info is turned on, through the -vi command-line option, then
  929.  
  930. {$MESSAGE This was coded on a rainy day by Bugs Bunny }
  931.  
  932. will display an info message when the compiler encounters it. The e ect is the same
  933. as the {$INFO} directive.
  934.  
  935.  
  936. $MMX : Intel MMX support
  937. As of version 0.9.8, Free Pascal supports optimization for the MMX Intel processor
  938. (see also 7).
  939.  
  940.  
  941.                                         17
  942.  
  943.  
  944.  
  945. CHAPTER 1. COMPILER DIRECTIVES                         1.1. LOCAL DIRECTIVES
  946.  
  947.  
  948. This optimizes certain code parts for the MMX Intel processor, thus greatly im-
  949. proving speed. The speed is noticed mostly when moving large amounts of data.
  950. Things that change are
  951.  
  952.    * Data with a size that is a multiple of 8 bytes is moved using the movq assembler
  953.         instruction, which moves 8 bytes at a time
  954.  
  955. Remark that MMX support is NOT emulated on non-MMX systems, i.e. if the pro-
  956. cessor doesn't have the MMX extensions, you cannot use the MMX optimizations.
  957. When MMX support is on, you aren't allowed to do floating point arithmetic. You
  958. are allowed to move floating point data, but no arithmetic can be done. If you wish
  959. to do floating point math anyway, you must first switch of MMX support and clear
  960. the FPU using the emms function of the cpu unit.
  961. The following example will make this more clear:
  962.  
  963. Program MMXDemo;
  964.  
  965. uses cpu;
  966.  
  967. vard1 : double;
  968.    a : array[0..10000] of double;
  969.    i : longint;
  970.  
  971. begin
  972.    d1:=1.0;
  973. {$mmx+}
  974.    { floating point data is used, but we do _no_ arithmetic }
  975.    for i:=0 to 10000 do
  976.          a[i]:=d2; { this is done with 64 bit moves }
  977. {$mmx-}
  978.    emms;       { clear fpu }
  979.    { now we can do floating point arithmetic }
  980.    ....
  981. end.
  982.  
  983. See, however, the chapter on MMX (7) for more information on this topic.
  984.  
  985.  
  986. $NOTE : Generate note message
  987. If the generation of notes is turned on, through the -vn command-line option or
  988. the {$NOTES ON} directive, then
  989.  
  990. {$NOTE Ask Santa Claus to look at this code }
  991.  
  992. will display a note message when the compiler encounters it.
  993.  
  994.  
  995. $NOTES : Emit notes
  996. {$NOTES ON} switches the generation of notes on. {$NOTES OFF} switches the gen-
  997. eration of notes o . Contrary to the command-line option -vn this is a local switch,
  998. this is useful for checking parts of your code.
  999.  
  1000.  
  1001.                                           18
  1002.  
  1003.  
  1004.  
  1005. CHAPTER 1. COMPILER DIRECTIVES                            1.1. LOCAL DIRECTIVES
  1006.  
  1007.  
  1008.  
  1009.                      Table 1.1: Formats generated by the x86 compiler
  1010.  
  1011.                 Switch value Generated format
  1012.                 att               AT&T assembler file.
  1013.                 o                 Unix object file.
  1014.                 obj               OMF file.
  1015.                 wasm              assembler for the Watcom assembler.
  1016.  
  1017.  
  1018. $OUTPUT FORMAT : Specify the output format
  1019. {$OUTPUT FORMAT format} has the same functionality as the -A command-line op-
  1020. tion : It tells the compiler what kind of object file must be generated. You can
  1021. specify this switch only befor the Program or Unit clause in your source file. The
  1022. di erent kinds of formats are shown in table (1.1).
  1023.  
  1024.  
  1025. $P or $OPENSTRINGS : Use open strings
  1026. $PACKENUM : Minimum enumeration type size
  1027. This directive tells the compiler the minimum number of bytes it should use when
  1028. storing enumerated types. It is of the following form:
  1029.  
  1030. {$PACKENUM xxx}
  1031. {$MINENUMSIZE xxx}
  1032.  
  1033. Where the form with $MINENUMSIZE is for Delphi compatibility. xxx can be one of
  1034. 1,2 or 4, or NORMAL or DEFAULT, corresponding to the default value of 4.
  1035. As an alternative form one can use {$Z1}, {$Z2} {$Z4}. Contrary to Delphi, the
  1036. default size is 4 bytes ({$Z4}).
  1037. So the following code
  1038.  
  1039. {$PACKENUM 1}
  1040. Type
  1041.   Days = (monday, tuesday, wednesday, thursday, friday,
  1042.             saturday, sunday);
  1043.  
  1044. will use 1 byte to store a variable of type Days, wheras it nomally would use 4 bytes.
  1045. The above code is equivalent to
  1046.  
  1047. {$Z1}
  1048. Type
  1049.   Days = (monday, tuesday, wednesday, thursday, friday,
  1050.             saturday, sunday);
  1051.  
  1052. Remark: Sets are always put in 32 bit or 32 bytes, this cannot be changed
  1053.  
  1054.  
  1055. $PACKRECORDS : Alignment of record elements
  1056. This directive controls the byte alignment of the elements in a record, object or
  1057. class type definition.
  1058. It is of the following form:
  1059.  
  1060.                                                19
  1061.  
  1062.  
  1063.  
  1064. CHAPTER 1. COMPILER DIRECTIVES                          1.1. LOCAL DIRECTIVES
  1065.  
  1066.  
  1067. {$PACKRECORDS n}
  1068.  
  1069. Where n is one of 1,2,4,16 or NORMAL or DEFAULT. This means that the elements of a
  1070. record that have size greater than n will be aligned on n byte boundaries. Elements
  1071. with size less than or equal to n will be aligned to a natural boundary, i.e. to a
  1072. power of two that is equal to or larger than the element's size.
  1073. The default alignment (which can be selected with DEFAULT) is 2, contrary to Turbo
  1074. Pascal, where it is 1.
  1075. More information on this and an example program can be found in the reference
  1076. guide, in the section about record types.
  1077. Remark: Sets are always put in 32 bit or 32 bytes, this cannot be changed
  1078.  
  1079.  
  1080. $Q $OVERFLOWCHECKS: Overflow checking
  1081. The {$Q+} or {$OVERFLOWCHECKS ON} directive turns on integer overflow checking.
  1082. This means that the compiler inserts code to check for overflow when doing com-
  1083. putations with integers. When an overflow occurs, the run-time library will print a
  1084. message Overflow at xxx, and exit the program with exit code 215.
  1085. Remark: Overflow checking behaviour is not the same as in Turbo Pascal since
  1086. all arithmetic operations are done via 32-bit values. Furthermore, the Inc() and
  1087. Dec() standard system procedures are checked for overflow in Free Pascal, while
  1088. in Turbo Pascal they are not.
  1089. Using the {$Q-} switch switches o  the overflow checking code generation.
  1090. The generation of overflow checking code can also be controlled using the -Co com-
  1091. mand line compiler option (see Users' guide).
  1092.  
  1093.  
  1094. $R or $RANGECHECKS : Range checking
  1095. By default, the compiler doesn't generate code to check the ranges of array in-
  1096. dices, enumeration types, subrange types, etc. Specifying the {$R+} switch tells
  1097. the computer to generate code to check these indices. If, at run-time, an index or
  1098. enumeration type is specified that is out of the declared range of the compiler, then
  1099. a run-time error is generated, and the program exits with exit code 201.
  1100. The {$RANGECHECKS OFF} switch tells the compiler not to generate range checking
  1101. code. This may result in faulty program behaviour, but no run-time errors will be
  1102. generated.
  1103. Remark: Range checking for sets and enumerations are not yet fully implemented.
  1104.  
  1105.  
  1106. $SATURATION : Saturation operations
  1107. This works only on the intel compiler, and MMX support must be on ({$MMX +})
  1108. for this to have any e ect. See the section on saturation support (section 7.2, page
  1109. 57) for more information on the e ect of this directive.
  1110.  
  1111.  
  1112. $SMARTLINK : Use smartlinking
  1113. A unit that is compiled in the {$SMARTLINK ON} state will be compiled in such a
  1114. way that it can be used for smartlinking. This means that the unit is chopped
  1115. in logical pieces: each procedure is put in it's own object file, and all object files
  1116.  
  1117.  
  1118.                                          20
  1119.  
  1120.  
  1121.  
  1122. CHAPTER 1. COMPILER DIRECTIVES                         1.1. LOCAL DIRECTIVES
  1123.  
  1124.  
  1125. are put together in a big archive. When using such a unit, only the pieces of code
  1126. that you really need or call, will be linked in your program, thus reducing the
  1127. size of your executable substantially. Beware that using smartlinked units slows
  1128. down the compilation process, because a separate object file must be created for
  1129. each procedure. If you have units with many functions and procedures, this can
  1130. be a time consuming process, even more so if you use an external assembler (the
  1131. assembler is called to assemble each procedure or function code block).
  1132. The smartlinking directive should be specified before the unit declaration part:
  1133.  
  1134. {$SMARTLINK ON}
  1135.  
  1136. Unit MyUnit;
  1137.  
  1138. Interface
  1139.  ...
  1140.  
  1141. This directive is equivalent to the -Cx command-line switch.
  1142.  
  1143.  
  1144. $STATIC : Allow use of Static keyword.
  1145. If you specify the {$STATIC ON} directive, then Static methods are allowed for ob-
  1146. jects. Static objects methods do not require a Self variable. They are equivalent
  1147. to Class methods for classes. By default, Static methods are not allowed.
  1148. This directive is equivalent to the -St command-line option.
  1149.  
  1150.  
  1151. $STOP : Generate fatal error message
  1152. The following code
  1153.  
  1154. {$STOP This code is erroneous !}
  1155.  
  1156. will display an error message when the compiler encounters it. The compiler will
  1157. immediatly stop the compilation process.
  1158. It has the same e ect as the {$FATAL} directive.
  1159.  
  1160.  
  1161. $T or $TYPEDADDRESS : Typed address operator (@)
  1162. In the {$T+} or {$TYPEDADDRESS ON} state the @ operator, when applied to a
  1163. variable, returns a result of type ^T, if the type of the variable is T. In the {$T-}
  1164. state, the result is always an untyped pointer, which is assignment compatible with
  1165. all other pointer types.
  1166.  
  1167.  
  1168. $UNDEF : Undefine a symbol
  1169. The directive
  1170.  
  1171. {$UNDEF name}
  1172.  
  1173. un-defines the symbol name if it was previously defined. Name is case insensitive.
  1174.  
  1175.  
  1176.  
  1177.                                          21
  1178.  
  1179.  
  1180.  
  1181. CHAPTER 1. COMPILER DIRECTIVES                          1.1. LOCAL DIRECTIVES
  1182.  
  1183.  
  1184. $V or $VARSTRINGCHECKS : Var-string checking
  1185. When in the + or ON state, the compiler checks that strings passed as parameters
  1186. are of the same, identical, string type as the declared parameters of the procedure.
  1187.  
  1188.  
  1189. $WAIT : Wait for enter key press
  1190. If the compiler encounters a
  1191.  
  1192. {$WAIT }
  1193.  
  1194. directive, it will resume compiling only after the user has pressed the enter key.
  1195. If the generation of info messages is turned on, then the compiler will display the
  1196. follwing message:
  1197.  
  1198. Press <return> to continue
  1199.  
  1200. before waiting for a keypress. Careful ! This may interfere with automatic compi-
  1201. lation processes. It should be used for debuggig purposes only.
  1202.  
  1203.  
  1204. $WARNING : Generate warning message
  1205. If the generation of warnings is turned on, through the -vw command-line option
  1206. or the {$WARNINGS ON} directive, then
  1207.  
  1208. {$WARNING This is dubious code }
  1209.  
  1210. will display a warning message when the compiler encounters it.
  1211.  
  1212.  
  1213. $WARNINGS : Emit warnings
  1214. {$WARNINGS ON} switches the generation of warnings on. {$WARNINGS OFF} switches
  1215. the generation of warnings o . Contrary to the command-line option -vw this is a
  1216. local switch, this is useful for checking parts of your code.
  1217.  
  1218.  
  1219. $X or $EXTENDEDSYNTAX : Extended syntax
  1220. Extended syntax allows you to drop the result of a function. This means that you
  1221. can use a function call as if it were a procedure. Standard this feature is on. You
  1222. can switch it o  using the {$X-} or {$EXTENDEDSYNTAX OFF}directive.
  1223. The following, for instance, will not compile :
  1224.  
  1225. function Func (var Arg : sometype) : longint;
  1226. begin
  1227. ...             { declaration of Func }
  1228. end;
  1229.  
  1230. ...
  1231.  
  1232. {$X-}
  1233. Func (A);
  1234.  
  1235.  
  1236.                                           22
  1237.  
  1238.  
  1239.  
  1240. CHAPTER 1. COMPILER DIRECTIVES                        1.2. GLOBAL DIRECTIVES
  1241.  
  1242.  
  1243. The reason this construct is supported is that you may wish to call a function for
  1244. certain side-e ects it has, but you don't need the function result. In this case you
  1245. don't need to assign the function result, saving you an extra variable.
  1246. The command-line compiler switch -Sa1 has the same e ect as the {$X+} directive.
  1247.  
  1248.  
  1249. 1.2 Global directives
  1250.  
  1251. Global directives a ect the whole of the compilation process. That is why they also
  1252. have a command-line counterpart. The command-line counterpart is given for each
  1253. of the directives.
  1254.  
  1255.  
  1256. $APPTYPE : Specify type of application (Win32 only)
  1257. The {$APPTYPE XXX} accepts one argument that can have two possible values : GUI
  1258. or CONSOLE. It is used to tell the windows Operating system if an application is
  1259. a console application or a graphical application. By default, a program compiled
  1260. by Free Pascal is a console application. Running it will display a console window.
  1261. Specifying the {$APPTYPE GUI} directive will mark the application as a graphical
  1262. application; no console window will be opened when the application is run. If run
  1263. from the command-line, the command prompt will be returned immediatly after
  1264. the application was started.
  1265. Care should be taken when compiling GUI applications; the Input and Output files
  1266. are not available in a GUI application, and attempting to read from or write to
  1267. them will result in a run-time error.
  1268. It is possible to determine the application type of a windows application at runtime.
  1269. The IsConsole constant, declared in the Win32 system unit as
  1270.  
  1271. Const
  1272.   IsConsole : Boolean
  1273.  
  1274. contains True if the application is a console application, False if the application is
  1275. a GUI application.
  1276.  
  1277.  
  1278. $D or $DEBUGINFO: Debugging symbols
  1279. When this switch is on ({$DEBUGINFO ON}), the compiler inserts GNU debugging
  1280. information in the executable. The e ect of this switch is the same as the command-
  1281. line switch -g. By default, insertion of debugging information is o .
  1282.  
  1283.  
  1284. $DESCRIPTION
  1285. This switch is recognised for compatibility only, but is ignored completely by the
  1286. compiler. At a later stage, this switch may be activated.
  1287.  
  1288.  
  1289. $E : Emulation of coprocessor
  1290. This directive controls the emulation of the coprocessor. There is no command-line
  1291. counterpart for this directive.
  1292.  
  1293.  
  1294.  
  1295.                                          23
  1296.  
  1297.  
  1298.  
  1299. CHAPTER 1. COMPILER DIRECTIVES                         1.2. GLOBAL DIRECTIVES
  1300.  
  1301.  
  1302. Intel x86 version
  1303.  
  1304. When this switch is enabled, all floating point instructions which are not supported
  1305. by standard coprocessor emulators will give out a warning.
  1306. The compiler itself doesn't do the emulation of the coprocessor.
  1307. To use coprocessor emulation under dos go32v1 there is nothing special required,
  1308. as it is handled automatically. (As of version 0.99.10, the go32v1 platform is no
  1309. longer be supported)
  1310. To use coprocessor emulation under dos go32v2 you must use the emu387 unit,
  1311. which contains correct initialization code for the emulator.
  1312. Under linux, the kernel takes care of the coprocessor support.
  1313.  
  1314. Motorola 680x0 version
  1315.  
  1316. When the switch is on, no floating point opcodes are emitted by the code generator.
  1317. Instead, internal run-time library routines are called to do the necessary calcula-
  1318. tions. In this case all real types are mapped to the single IEEE floating point
  1319. type.
  1320. Remark : By default, emulation is on. It is possible to intermix emulation code
  1321. with real floating point opcodes, as long as the only type used is single or real.
  1322.  
  1323.  
  1324. $G : Generate 80286 code
  1325. This option is recognised for Turbo Pascal compatibility, but is ignored.
  1326.  
  1327.  
  1328. $INCLUDEPATH : Specify include path.
  1329. This option serves to specify the include path, where the compiler looks for include
  1330. files. {$INCLUDEPATH XXX will add XXX to the include path. XXX can contain one or
  1331. more paths, separated by semi-colons or colons.
  1332. for example
  1333.  
  1334. {$INCLUDEPATH ../inc;../i386}
  1335.  
  1336. {$I strings.inc}
  1337.  
  1338. Will add the directories ../inc and ../i386 to the include path of the compiler. The
  1339. compiler will look for the file strings.inc in both these directories, and will include
  1340. the first found file. This directive is equivalent to the -Fi command-line switch.
  1341. Caution is in order when using this directive: If you distribute files, the places of
  1342. the files may not be the same as on your machine; moreover, the directory structure
  1343. may be di erent. In general it would be fair to say that you should avoid using
  1344. absolute paths, instead use relative paths, as in the example above. Only use this
  1345. directive if you are certain of the places where the files reside. If you are not sure,
  1346. it is better practice to use makefiles and makefile variables.
  1347.  
  1348.  
  1349. $L or $LOCALSYMBOLS: Local symbol information
  1350. This switch (not to be confused with the {$L file} file linking directive) is recog-
  1351. nised for Turbo Pascal compatibility, but is ignored. Generation of symbol infor-
  1352.  
  1353.                                           24
  1354.  
  1355.  
  1356.  
  1357. CHAPTER 1. COMPILER DIRECTIVES                       1.2. GLOBAL DIRECTIVES
  1358.  
  1359.  
  1360. mation is controlled by the $D switch.
  1361.  
  1362.  
  1363. $LIBRARYPATH : Specify library path.
  1364. This option serves to specify the library path, where the linker looks for static or
  1365. dynamic libraries. {$LIBRARYPATH XXX} will add XXX to the library path. XXX can
  1366. contain one or more paths, separated by semi-colons or colons.
  1367. for example
  1368.  
  1369. {$LIBRARYPATH /usr/X11/lib;/usr/local/lib}
  1370.  
  1371. {$LINKLIB X11}
  1372.  
  1373. Will add the directories /usr/X11/lib and /usr/local/lib to the linker library path.
  1374. The linker will look for the library libX11.so in both these directories, and use the
  1375. first found file. This directive is equivalent to the -Fl command-line switch.
  1376. Caution is in order when using this directive: If you distribute files, the places of
  1377. the libraries may not be the same as on your machine; moreover, the directory
  1378. structure may be di erent. In general it would be fair to say that you should avoid
  1379. using this directive. If you are not sure, it is better practice to use makefiles and
  1380. makefile variables.
  1381.  
  1382.  
  1383. $M or $MEMORY: Memory sizes
  1384. This switch can be used to set the heap and stacksize. It's format is as follows:
  1385.  
  1386. {$M StackSize,HeapSize}
  1387.  
  1388. where StackSize and HeapSize should be two integer values, greater than 1024.
  1389. The first number sets the size of the stack, and the second the size of the heap.
  1390. (Stack setting is ignored under linux). The two numbers can be set on the com-
  1391. mand line using the -Ch and -Cs switches.
  1392.  
  1393.  
  1394. $MODE : Set compiler compatibility mode
  1395. The {$MODE} sets the compatibility mode of the compiler. This is equivalent to
  1396. setting one of the command-line options -So, -Sd, -Sp or -S2. it has the following
  1397. arguments:
  1398.  
  1399. Default Default mode. This reverts back to the mode that was set on the command-
  1400.      line.
  1401. Delphi Delphi compatibility mode. All object-pascal extensions are enabled. This
  1402.      is the same as the command-line option -Sd.
  1403. TP Turbo pascal compatibility mode. Object pascal extensions are disabled, ex-
  1404.      cept ansistrings, which remain valid. This is the same as the command-line
  1405.      option -So
  1406. FPC FPC mode. This is the default, if no command-line switch is supplied.
  1407. OBJFPC Object pascal mode. This is the same as the -S2 command-line option.
  1408. GPC GNU pascal mode. This is the same as the -Sp command-line option.
  1409.  
  1410. For an exact description of each of these modes, see appendix D, on page 80.
  1411.  
  1412.                                           25
  1413.  
  1414.  
  1415.  
  1416. CHAPTER 1. COMPILER DIRECTIVES                         1.2. GLOBAL DIRECTIVES
  1417.  
  1418.  
  1419. $N : Numeric processing
  1420. This switch is recognised for Turbo Pascal compatibility, but is otherwise ignored,
  1421. since the compiler always uses the coprocessor for floating point mathematics.
  1422.  
  1423.  
  1424. $O : Overlay code generation
  1425. This switch is recognised for Turbo Pascal compatibility, but is otherwise ignored.
  1426.  
  1427.  
  1428. $OBJECTPATH : Specify object path.
  1429. This option serves to specify the object path, where the compiler looks for object
  1430. files. {$OBJECTPATH XXX will add XXX to the object path. XXX can contain one or
  1431. more paths, separated by semi-colons or colons.
  1432. for example
  1433.  
  1434. {$OBJECTPATH ../inc;../i386}
  1435.  
  1436. {$L strings.o}
  1437.  
  1438. Will add the directories ../inc and ../i386 to the object path of the compiler. The
  1439. compiler will look for the file strings.o in both these directories, and will link the
  1440. first found file in the program. This directive is equivalent to the -Fo command-line
  1441. switch.
  1442. Caution is in order when using this directive: If you distribute files, the places of
  1443. the files may not be the same as on your machine; moreover, the directory structure
  1444. may be di erent. In general it would be fair to say that you should avoid using
  1445. absolute paths, instead use relative paths, as in the example above. Only use this
  1446. directive if you are certain of the places where the files reside. If you are not sure,
  1447. it is better practice to use makefiles and makefile variables.
  1448.  
  1449.  
  1450. $S : Stack checking
  1451. The {$S+} directive tells the compiler to generate stack checking code. This gen-
  1452. erates code to check if a stack overflow occurred, i.e. to see whether the stack has
  1453. grown beyond its maximally allowed size. If the stack grows beyond the maximum
  1454. size, then a run-time error is generated, and the program will exit with exit code
  1455. 202.
  1456. Specifying {$S-} will turn generation of stack-checking code o .
  1457. The command-line compiler switch -Ct has the same e ect as the {$S+} directive.
  1458.  
  1459.  
  1460. $UNITPATH : Specify unit path.
  1461. This option serves to specify the unit path, where the compiler looks for unit files.
  1462. {$UNITPATH XXX} will add XXX to the unit path. XXX can contain one or more paths,
  1463. separated by semi-colons or colons.
  1464. for example
  1465.  
  1466. {$UNITPATH ../units;../i386/units}
  1467.  
  1468. Uses strings;
  1469.  
  1470.                                           26
  1471.  
  1472.  
  1473.  
  1474. CHAPTER 1. COMPILER DIRECTIVES                         1.2. GLOBAL DIRECTIVES
  1475.  
  1476.  
  1477. Will add the directories ../units and ../i386/units to the unit path of the compiler.
  1478. The compiler will look for the file strings.ppu in both these directories, and will
  1479. link the first found file in the program. This directive is equivalent to the -Fu
  1480. command-line switch.
  1481. Caution is in order when using this directive: If you distribute files, the places of
  1482. the files may not be the same as on your machine; moreover, the directory structure
  1483. may be di erent. In general it would be fair to say that you should avoid using
  1484. absolute paths, instead use relative paths, as in the example above. Only use this
  1485. directive if you are certain of the places where the files reside. If you are not sure,
  1486. it is better practice to use makefiles and makefile variables.
  1487.  
  1488.  
  1489. $W or $STACKFRAMES : Generate stackframes
  1490. The {$W} switch directove controls the generation of stackframes. In the on state
  1491. ({$STACKFRAMES ON}), the compiler will generate a stackframe for every procedure
  1492. or function.
  1493. In the o  state, the compiler will omit the generation of a stackframe if the following
  1494. conditions are satisfied:
  1495.  
  1496.    * The procedure has no parameters.
  1497.  
  1498.    * The procedure has no local variables.
  1499.  
  1500.    * If the procedure is not an assembler procedure, it must not have a asm ...
  1501.       end; block.
  1502.  
  1503.    * it is not a constuctor or desctructor.
  1504.  
  1505. If these conditions are satisfied, the stack frame will be omitted.
  1506.  
  1507.  
  1508. $Y or $REFERENCEINFO : Insert Browser information
  1509. This switch controls the generation of browser inforation. It is recognized for com-
  1510. patibility with Turbo Pascal and Delphi only, as Browser information generation is
  1511. not yet fully supported.
  1512.  
  1513.  
  1514.  
  1515.  
  1516.  
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.  
  1523.  
  1524.  
  1525.  
  1526.  
  1527.  
  1528.  
  1529.  
  1530.                                           27
  1531.  
  1532.  
  1533.  
  1534. Chapter 2
  1535.  
  1536. Using conditionals, messages
  1537. and macros
  1538.  
  1539. The Free Pascal compiler supports conditionals as in normal Turbo Pascal. It does,
  1540. however, more than that. It allows you to make macros which can be used in your
  1541. code, and it allows you to define messages or errors which will be displayed when
  1542. compiling.
  1543.  
  1544.  
  1545. 2.1 Conditionals
  1546.  
  1547. The rules for using conditional symbols are the same as under Turbo Pascal. Defin-
  1548. ing a symbol goes as follows:
  1549.  
  1550. {$Define Symbol }
  1551.  
  1552. From this point on in your code, the compiler knows the symbol Symbol. Symbols
  1553. are, like the Pascal language, case insensitive.
  1554. You can also define a symbol on the command line. the -dSymbol option defines
  1555. the symbol Symbol. You can specify as many symbols on the command line as you
  1556. want.
  1557. Undefining an existing symbol is done in a similar way:
  1558.  
  1559. {$Undef Symbol }
  1560.  
  1561. If the symbol didn't exist yet, this doesn't do anything. If the symbol existed
  1562. previously, the symbol will be erased, and will not be recognized any more in the
  1563. code following the {$Undef ...} statement.
  1564. You can also undefine symbols from the command line with the -u command-line
  1565. switch..
  1566. To compile code conditionally, depending on whether a symbol is defined or not,
  1567. you can enclose the code in a {$ifdef Symbol} .. {$endif} pair. For instance the
  1568. following code will never be compiled :
  1569.  
  1570. {$Undef MySymbol}
  1571. {$ifdef Mysymbol}
  1572.   DoSomething;
  1573.  
  1574.                                            28
  1575.  
  1576.  
  1577.  
  1578. CHAPTER 2. USING CONDITIONALS, MESSAGES AND MA
  1579.                                                                     2.1.     CROS
  1580.                                                                             CONDITIONALS
  1581.  
  1582.  
  1583.  
  1584.                      Table 2.1: Symbols defined by the compiler.
  1585.  
  1586.                                              Free
  1587.                                             VERv
  1588.                                           VERv r
  1589.                                          VERv r p
  1590.                                              OS
  1591.  
  1592.  
  1593.   ...
  1594. {$endif}
  1595.  
  1596. Similarly, you can enclose your code in a {$Ifndef Symbol} .. {$endif} pair. Then
  1597. the code between the pair will only be compiled when the used symbol doesn't exist.
  1598. For example, in the following example, the call to the DoSomething will always be
  1599. compiled:
  1600.  
  1601. {$Undef MySymbol}
  1602. {$ifndef Mysymbol}
  1603.   DoSomething;
  1604.   ...
  1605. {$endif}
  1606.  
  1607. You can combine the two alternatives in one structure, namely as follows
  1608.  
  1609. {$ifdef Mysymbol}
  1610.   DoSomething;
  1611. {$else}
  1612.   DoSomethingElse
  1613. {$endif}
  1614.  
  1615. In this example, if MySymbol exists, then the call to DoSomething will be compiled.
  1616. If it doesn't exist, the call to DoSomethingElse is compiled.
  1617. The Free Pascal compiler defines some symbols before starting to compile your
  1618. program or unit. You can use these symbols to di erentiate between di erent
  1619. versions of the compiler, and between di erent compilers. In table (2.1), a list of
  1620. pre-defined symbols is given1. In that table, you should change v with the version
  1621. number of the compiler you're using, r with the release number and p with the
  1622. patch-number of the compiler. 'OS' needs to be changed by the type of operating
  1623. system. Currently this can be one of DOS, GO32V2, LINUX, OS2, WIN32, MACOS, AMIGA
  1624. or ATARI.
  1625. The OS symbol is undefined if you specify a target that is di erent from the platform
  1626. you're compiling on. The -TSomeOS option on the command line will define the
  1627. SomeOS symbol, and will undefine the existing platform symbol2.
  1628. As an example : Version 0.9.1 of the compiler, running on a Linux system, defines
  1629. the following symbols before reading the command line arguments: FPC, VER0,
  1630. VER0 9, VER0 9 1 and LINUX. Specifying -TOS2 on the command-line will undefine
  1631. the LINUX symbol, and will define the OS2 symbol.
  1632. Remark: Symbols, even when they're defined in the interface part of a unit, are
  1633. not available outside that unit.
  1634.   1Remark: The FPK symbol is still defined for compatibility with older versions.
  1635.   2In versions prior to 0.9.4, this didn't happen, thus making Cross-compiling impossible.
  1636.  
  1637.  
  1638.                                               29
  1639.  
  1640.  
  1641.  
  1642. CHAPTER 2. USING CONDITIONALS, MESSAGES AND MA
  1643.                                                               2.1.     CROS
  1644.                                                                       CONDITIONALS
  1645.  
  1646.  
  1647. Except for the Turbo Pascal constructs, from version 0.9.8 and higher, the Free
  1648. Pascal compiler also supports a stronger conditional compile mechanism: The {$If
  1649. } construct.
  1650. The prototype of this construct is as follows :
  1651.  
  1652. {$If expr}
  1653.   CompileTheseLines;
  1654. {$else}
  1655.   BetterCompileTheseLines;
  1656. {$endif}
  1657.  
  1658. In this directive expr is a Pascal expression which is evaluated using strings, unless
  1659. both parts of a comparision can be evaluated as numbers, in which case they are
  1660. evaluated using numbers3. If the complete expression evaluates to '0', then it is
  1661. considered false and rejected. Otherwise it is considered true and accepted. This
  1662. may have unexpected consequences :
  1663.  
  1664. {$If 0}
  1665.  
  1666. Will evaluate to False and be rejected, while
  1667.  
  1668. {$If 00}
  1669.  
  1670. Will evaluate to True.
  1671. You can use any Pascal operator to construct your expression : =, <>, >, <, >=,
  1672. <=, AND, NOT, OR and you can use round brackets to change the precedence of the
  1673. operators.
  1674. The following example shows you many of the possibilities:
  1675.  
  1676. {$ifdef fpc}
  1677.  
  1678. vary : longint;
  1679. {$else fpc}
  1680.  
  1681. varz : longint;
  1682. {$endif fpc}
  1683.  
  1684. varx : longint;
  1685. begin
  1686.  
  1687. {$if (fpc_version=0) and (fpc_release>6) and (fpc_patch>4)}
  1688. {$info At least this is version 0.9.5}
  1689. {$else}
  1690. {$fatal Problem with version check}
  1691. {$endif}
  1692.  
  1693. {$define x:=1234}
  1694.   3Otherwise {$If 8>54} would evaluate to True
  1695.  
  1696.  
  1697.                                            30
  1698.  
  1699.  
  1700.  
  1701. CHAPTER 2. USING CONDITIONALS, MESSAGES AND MA
  1702.                                            2.1.     CROS
  1703.                                                    CONDITIONALS
  1704.  
  1705.  
  1706. {$if x=1234}
  1707. {$info x=1234}
  1708. {$else}
  1709. {$fatal x should be 1234}
  1710. {$endif}
  1711.  
  1712. {$if 12asdf and 12asdf}
  1713. {$info $if 12asdf and 12asdf is ok}
  1714. {$else}
  1715. {$fatal $if 12asdf and 12asdf rejected}
  1716. {$endif}
  1717.  
  1718. {$if 0 or 1}
  1719. {$info $if 0 or 1 is ok}
  1720. {$else}
  1721. {$fatal $if 0 or 1 rejected}
  1722. {$endif}
  1723.  
  1724. {$if 0}
  1725. {$fatal $if 0 accepted}
  1726. {$else}
  1727. {$info $if 0 is ok}
  1728. {$endif}
  1729.  
  1730. {$if 12=12}
  1731. {$info $if 12=12 is ok}
  1732. {$else}
  1733. {$fatal $if 12=12 rejected}
  1734. {$endif}
  1735.  
  1736. {$if 12<>312}
  1737. {$info $if 12<>312 is ok}
  1738. {$else}
  1739. {$fatal $if 12<>312 rejected}
  1740. {$endif}
  1741.  
  1742.  
  1743. {$if 12<=312}
  1744. {$info $if 12<=312 is ok}
  1745. {$else}
  1746. {$fatal $if 12<=312 rejected}
  1747. {$endif}
  1748.  
  1749. {$if 12<312}
  1750. {$info $if 12<312 is ok}
  1751. {$else}
  1752. {$fatal $if 12<312 rejected}
  1753. {$endif}
  1754.  
  1755. {$if a12=a12}
  1756. {$info $if a12=a12 is ok}
  1757. {$else}
  1758. {$fatal $if a12=a12 rejected}
  1759. {$endif}
  1760.  
  1761.                                  31
  1762.  
  1763.  
  1764.  
  1765. CHAPTER 2. USING CONDITIONALS, MESSAGES AND MACR
  1766.                                                                     2.2. OS
  1767.                                                                          MESSAGES
  1768.  
  1769.  
  1770.  
  1771. {$if a12<=z312}
  1772. {$info $if a12<=z312 is ok}
  1773. {$else}
  1774. {$fatal $if a12<=z312 rejected}
  1775. {$endif}
  1776.  
  1777.  
  1778. {$if a12<z312}
  1779. {$info $if a12<z312 is ok}
  1780. {$else}
  1781. {$fatal $if a12<z312 rejected}
  1782. {$endif}
  1783.  
  1784. {$if not(0)}
  1785. {$info $if not(0) is OK}
  1786. {$else}
  1787. {$fatal $if not(0) rejected}
  1788. {$endif}
  1789.  
  1790. {$info *************************************************}
  1791. {$info * Now have to follow at least 2 error messages: *}
  1792. {$info *************************************************}
  1793.  
  1794. {$if not(0}
  1795. {$endif}
  1796.  
  1797. {$if not(<}
  1798. {$endif}
  1799.  
  1800. end.
  1801.  
  1802. As you can see from the example, this construct isn't useful when used with normal
  1803. symbols, but it is if you use macros, which are explained in section 2.3, page 33,
  1804. they can be very useful. When trying this example, you must switch on macro
  1805. support, with the -Sm command-line switch.
  1806.  
  1807. 2.2 Messages
  1808.  
  1809. Free Pascal lets you define normal, warning and error messages in your code. Mes-
  1810. sages can be used to display useful information, such as copyright notices, a list of
  1811. symbols that your code reacts on etc.
  1812. Warnings can be used if you think some part of your code is still buggy, or if you
  1813. think that a certain combination of symbols isn't useful. In general anything which
  1814. may cause problems when compiling.
  1815. Error messages can be useful if you need a certain symbol to be defined to warn that
  1816. a certain variable isn't defined or so, or when the compiler version isn't suitable for
  1817. your code.
  1818. The compiler treats these messages as if they were generated by the compiler. This
  1819. means that if you haven't turned on warning messages, the warning will not be
  1820. displayed. Errors are always displayed, and the compiler stops if 50 errors have
  1821. occurred. After a fatal error, the compiler stops at once.
  1822.  
  1823.                                           32
  1824.  
  1825.  
  1826.  
  1827. CHAPTER 2. USING CONDITIONALS, MESSAGES AND MACROS
  1828.                                                                                  2.3. MACROS
  1829.  
  1830.  
  1831. For messages, the syntax is as follows :
  1832.  
  1833. {$Message Message text }
  1834.  
  1835. Or
  1836.  
  1837. {$Info Message text }
  1838.  
  1839. For notes:
  1840.  
  1841. {$Note Message text }
  1842.  
  1843. For warnings:
  1844.  
  1845. {$Warning Warning Message text }
  1846.  
  1847. For errors :
  1848.  
  1849. {$Error Error Message text }
  1850.  
  1851. Lastly, for fatal errors :
  1852.  
  1853. {$Fatal Error Message text }
  1854.  
  1855. or
  1856.  
  1857. {$Stop Error Message text }
  1858.  
  1859. The di erence between $Error and $FatalError or $Stop messages is that when
  1860. the compiler encounters an error, it still continues to compile. With a fatal error,
  1861. the compiler stops.
  1862. Remark : You cannot use the '}' character in your message, since this will be treated
  1863. as the closing brace of the message.
  1864. As an example, the following piece of code will generate an error when the symbol
  1865. RequiredVar isn't defined:
  1866.  
  1867. {$ifndef RequiredVar}
  1868. {$Error Requiredvar isn't defined !}
  1869. {$endif}
  1870.  
  1871. But the compiler will continue to compile. It will not, however, generate a unit file
  1872. or a program (since an error occurred).
  1873.  
  1874.  
  1875. 2.3 Macros
  1876.  
  1877. Macros are very much like symbols in their syntax, the di erence is that macros
  1878. have a value whereas a symbol simply is defined or is not defined. If you want macro
  1879. support, you need to specify the -Sm command-line switch, otherwise your macro
  1880. will be regarded as a symbol.
  1881. Defining a macro in your program is done in the same way as defining a symbol; in
  1882. a {$define } preprocessor statement4:
  1883.       4In compiler versions older than 0.9.8, the assignment operator for a macros wasn't :=, but =
  1884.  
  1885.  
  1886.                                                   33
  1887.  
  1888.  
  1889.  
  1890. CHAPTER 2. USING CONDITIONALS, MESSAGES AND MACROS
  1891.                                                                         2.3. MACROS
  1892.  
  1893.  
  1894.  
  1895.                              Table 2.2: Predefined macros
  1896.  
  1897.                 Symbol             Contains
  1898.                 FPC VERSION The version number of the compiler.
  1899.                 FPC RELEASE The release number of the compiler.
  1900.                 FPC PATCH          The patch number of the compiler.
  1901.  
  1902.  
  1903. {$define ident:=expr}
  1904.  
  1905. If the compiler encounters ident in the rest of the source file, it will be replaced
  1906. immediately by expr. This replacement works recursive, meaning that when the
  1907. compiler expanded one of your macros, it will look at the resulting expression again
  1908. to see if another replacement can be made. You need to be careful with this, because
  1909. an infinite loop can occur in this manner.
  1910. Here are two examples which illustrate the use of macros:
  1911.  
  1912. {$define sum:=a:=a+b;}
  1913. ...
  1914. sum             { will be expanded to 'a:=a+b;'
  1915.                   remark the absence of the semicolon}
  1916. ...
  1917. {$define b:=100}
  1918. sum             { Will be expanded recursively to a:=a+100; }
  1919. ...
  1920.  
  1921. The previous example could go wrong :
  1922.  
  1923. {$define sum:=a:=a+b;}
  1924. ...
  1925. sum             { will be expanded to 'a:=a+b;'
  1926.                   remark the absence of the semicolon}
  1927. ...
  1928. {$define b=sum} { DON'T do this !!!}
  1929. sum             { Will be infinitely recursively expanded... }
  1930. ...
  1931.  
  1932. On my system, the last example results in a heap error, causing the compiler to
  1933. exit with a run-time error 203.
  1934. Remark: Macros defined in the interface part of a unit are not available outside
  1935. that unit ! They can just be used as a notational convenience, or in conditional
  1936. compiles.
  1937. By default, from version 0.9.8 of the compiler on, the compiler predefines three
  1938. macros, containing the version number, the release number and the patch number.
  1939. They are listed in table (2.2).
  1940. Remark: Don't forget that macros support isn't on by default. You need to compile
  1941. with the -Sm command-line switch.
  1942.  
  1943.  
  1944.  
  1945.  
  1946.  
  1947.  
  1948.                                                34
  1949.  
  1950.  
  1951.  
  1952. Chapter 3
  1953.  
  1954. Using Assembly language
  1955.  
  1956. Free Pascal supports inserting of assembler instructions in your code. The mecha-
  1957. nism for this is the same as under Turbo Pascal. There are, however some substan-
  1958. tial di erences, as will be explained in the following.
  1959.  
  1960.  
  1961. 3.1 Intel syntax
  1962.  
  1963. As of version 0.9.7, Free Pascal supports Intel syntax for the Intel family of Ix86
  1964. processors in it's asm blocks.
  1965. The Intel syntax in your asm block is converted to AT&T syntax by the compiler,
  1966. after which it is inserted in the compiled source. The supported assembler constructs
  1967. are a subset of the normal assembly syntax. In what follows we specify what
  1968. constructs are not supported in Free Pascal, but which exist in Turbo Pascal:
  1969.  
  1970.    * The TBYTE qualifier is not supported.
  1971.  
  1972.    * The & identifier override is not supported.
  1973.  
  1974.    * The HIGH operator is not supported.
  1975.  
  1976.    * The LOW operator is not supported.
  1977.  
  1978.    * The OFFSET and SEG operators are not supported. use LEA and the various
  1979.       Lxx instructions instead.
  1980.  
  1981.    * Expressions with constant strings are not allowed.
  1982.  
  1983.    * Access to record fields via parenthesis is not allowed
  1984.  
  1985.    * Typecasts with normal pascal types are not allowed, only recognized assembler
  1986.       typecasts are allowed.
  1987.       Example:
  1988.  
  1989.       mov al, byte ptr MyWord              -- allowed,
  1990.       mov al, byte(MyWord)                 -- allowed,
  1991.       mov al, shortint(MyWord)             -- not allowed.
  1992.  
  1993.    * Pascal type typecasts on constants are not allowed.
  1994.       Example:
  1995.  
  1996.  
  1997.                                           35
  1998.  
  1999.  
  2000.  
  2001. CHAPTER 3. USING ASSEMBLY LANGUAGE                           3.1. INTEL SYNTAX
  2002.  
  2003.  
  2004.     const s= 10; const t = 32767;
  2005.  
  2006.     in Turbo Pascal:
  2007.  
  2008.     mov al, byte(s)                   -- useless typecast.
  2009.     mov al, byte(t)                   -- syntax error!
  2010.  
  2011.     In this parser, either of those cases will give out a syntax error.
  2012.  
  2013.   * Constant references expressions with constants only are not allowed (in all
  2014.     cases they do not work in protected mode, under linux i386).
  2015.     Examples:
  2016.  
  2017.     mov al,byte ptr ['c']             -- not allowed.
  2018.     mov al,byte ptr [100h]            -- not allowed.
  2019.  
  2020.     (This is due to the limitation of Turbo Assembler).
  2021.  
  2022.   * Brackets within brackets are not allowed
  2023.  
  2024.   * Expressions with segment overrides fully in brackets are presently not sup-
  2025.     ported, but they can easily be implemented in BuildReference if requested.
  2026.     Example:
  2027.  
  2028.     mov al,[ds:bx]          -- not allowed
  2029.  
  2030.     use instead:
  2031.  
  2032.     mov al,ds:[bx]
  2033.  
  2034.   * Possible allowed indexing are as follows:
  2035.  
  2036.       ¡ Sreg:[REG+REG*SCALING+/-disp]
  2037.       ¡ SReg:[REG+/-disp]
  2038.       ¡ SReg:[REG]
  2039.       ¡ SReg:[REG+REG+/-disp]
  2040.       ¡ SReg:[REG+REG*SCALING]
  2041.  
  2042.     Where Sreg is optional and specifies the segment override. Notes:
  2043.  
  2044.       1. The order of terms is important contrary to Turbo Pascal.
  2045.       2. The Scaling value must be a value, and not an identifier to a symbol.
  2046.          Examples:
  2047.          const myscale = 1;
  2048.          ...
  2049.          mov al,byte ptr [esi+ebx*myscale] -- not allowed.
  2050.          use:
  2051.          mov al, byte ptr [esi+ebx*1]
  2052.  
  2053.   * Possible variable identifier syntax is as follows: (Id = Variable or typed con-
  2054.     stant identifier.)
  2055.  
  2056.       1. ID
  2057.       2. [ID]
  2058.  
  2059.                                         36
  2060.  
  2061.  
  2062.  
  2063. CHAPTER 3. USING ASSEMBLY LANGUAGE                            3.1. INTEL SYNTAX
  2064.  
  2065.  
  2066.        3. [ID+expr]
  2067.        4. ID[expr]
  2068.  
  2069.      Possible fields are as follow:
  2070.  
  2071.        1. ID.subfield.subfield ...
  2072.        2. [ref].ID.subfield.subfield ...
  2073.        3. [ref].typename.subfield ...
  2074.  
  2075.    * Local Labels: Contrary to Turbo Pascal, local labels, must at least contain
  2076.      one character after the local symbol indicator.
  2077.      Example:
  2078.  
  2079.      @:                    -- not allowed
  2080.  
  2081.      use instead, for example:
  2082.  
  2083.      @1:                  -- allowed
  2084.  
  2085.    * Contrary to Turbo Pascal local references cannot be used as references, only
  2086.      as displacements.
  2087.      example:
  2088.  
  2089.      lds si,@mylabel        -- not allowed
  2090.  
  2091.    * Contrary to Turbo Pascal, SEGCS, SEGDS, SEGES and SEGSS segment overrides
  2092.      are presently not supported. (This is a planned addition though).
  2093.  
  2094.    * Contrary to Turbo Pascal where memory sizes specifiers can be practically
  2095.      anywhere, the Free Pascal Intel inline assembler requires memory size speci-
  2096.      fiers to be outside the brackets.
  2097.      example:
  2098.  
  2099.      mov al,[byte ptr myvar]              -- not allowed.
  2100.  
  2101.      use:
  2102.  
  2103.      mov al,byte ptr [myvar]              -- allowed.
  2104.  
  2105.    * Base and Index registers must be 32-bit registers. (limitation of the GNU
  2106.      Assembler).
  2107.  
  2108.    * XLAT is equivalent to XLATB.
  2109.  
  2110.    * Only Single and Double FPU opcodes are supported.
  2111.  
  2112.    * Floating point opcodes are currently not supported (except those which in-
  2113.      volve only floating point registers).
  2114.  
  2115. The Intel inline assembler supports the following macros :
  2116.  
  2117. @Result represents the function result return value.
  2118.  
  2119. Self represents the object method pointer in methods.
  2120.  
  2121.  
  2122.  
  2123.                                            37
  2124.  
  2125.  
  2126.  
  2127. CHAPTER 3. USING ASSEMBLY LANGUAGE                             3.2. AT&T SYNTAX
  2128.  
  2129.  
  2130. 3.2 AT&T Syntax
  2131.  
  2132. Free Pascal uses the gnu as assembler to generate its object files for the Intel Ix86
  2133. processors . Since the gnu assembler uses AT&T assembly syntax, the code you
  2134. write should use the same syntax. The di erences between AT&T and Intel syntax
  2135. as used in Turbo Pascal are summarized in the following:
  2136.  
  2137.    * The opcode names include the size of the operand. In general, one can say
  2138.      that the AT&T opcode name is the Intel opcode name, su xed with a 'l',
  2139.      'w' or 'b' for, respectively, longint (32 bit), word (16 bit) and byte (8 bit)
  2140.      memory or register references. As an example, the Intel construct 'mov al bl
  2141.      is equivalent to the AT&T style 'movb %bl,%al' instruction.
  2142.  
  2143.    * AT&T immediate operands are designated with '$', while Intel syntax doesn't
  2144.      use a prefix for immediate operands. Thus the Intel construct 'mov ax, 2'
  2145.      becomes 'movb $2, %al' in AT&T syntax.
  2146.  
  2147.    * AT&T register names are preceded by a '%' sign. They are undelimited in
  2148.      Intel syntax.
  2149.  
  2150.    * AT&T indicates absolute jump/call operands with '*', Intel syntax doesn't
  2151.      delimit these addresses.
  2152.  
  2153.    * The order of the source and destination operands are switched. AT&T syntax
  2154.      uses 'Source, Dest', while Intel syntax features 'Dest, Source'. Thus the
  2155.      Intel construct 'add eax, 4' transforms to 'addl $4, %eax' in the AT&T
  2156.      dialect.
  2157.  
  2158.    * Immediate long jumps are prefixed with the 'l' prefix. Thus the Intel 'call/jmp
  2159.      section:offset' is transformed to 'lcall/ljmp $section,$offset'. Sim-
  2160.      ilarly the far return is 'lret', instead of the Intel 'ret far'.
  2161.  
  2162.    * Memory references are specified di erently in AT&T and Intel assembly. The
  2163.      Intel indirect memory reference
  2164.  
  2165.            Section:[Base + Index*Scale + Offs]
  2166.  
  2167.      is written in AT&T syntax as :
  2168.  
  2169.            Section:Offs(Base,Index,Scale)
  2170.  
  2171.      Where Base and Index are optional 32-bit base and index registers, and Scale
  2172.      is used to multiply Index. It can take the values 1,2,4 and 8. The Section is
  2173.      used to specify an optional section register for the memory operand.
  2174.  
  2175. More information about the AT&T syntax can be found in the as manual, although
  2176. the following di erences with normal AT&T assembly must be taken into account :
  2177.  
  2178.    * Only the following directives are presently supported:
  2179.  
  2180.      .byte
  2181.      .word
  2182.      .long
  2183.      .ascii
  2184.      .asciz
  2185.      .globl
  2186.  
  2187.                                          38
  2188.  
  2189.  
  2190.  
  2191. CHAPTER 3. USING ASSEMBLY LANGUAGE 3.3. CALLING MECHANISM
  2192.  
  2193.  
  2194.    * The following directives are recognized but are not supported:
  2195.  
  2196.       .align
  2197.       .lcomm
  2198.  
  2199.       Eventually they will be supported.
  2200.  
  2201.    * Directives are case sensitive, other identifiers are not case sensitive.
  2202.  
  2203.    * Contrary to GAS local labels/symbols must start with .L
  2204.  
  2205.    * The not operator '!' is not supported.
  2206.  
  2207.    * String expressions in operands are not supported.
  2208.  
  2209.    * CBTW,CWTL,CWTD and CLTD are not supported, use the normal intel
  2210.       equivalents instead.
  2211.  
  2212.    * Constant expressions which represent memory references are not allowed even
  2213.       though constant immediate value expressions are supported.
  2214.       examples:
  2215.  
  2216.       const myid = 10;
  2217.       ...
  2218.       movl $myid,%eax            -- allowed
  2219.       movl myid(%esi),%eax -- not allowed.
  2220.  
  2221.    * When the .globl directive is found, the symbol following it is made public
  2222.       and is immediately emitted. Therefore label names with this name will be
  2223.       ignored.
  2224.  
  2225.    * Only Single and Double FPU opcodes are supported.
  2226.  
  2227. The AT&T inline assembler supports the following macros :
  2228.  
  2229.  RESULT represents the function result return value.
  2230.  
  2231.  SELF represents the object method pointer in methods.
  2232.  
  2233.  OLDEBP represents the old base pointer in recusrive routines.
  2234.  
  2235.  
  2236. 3.3 Calling mechanism
  2237.  
  2238. Procedures and Functions are called with their parameters on the stack. Contrary
  2239. to Turbo Pascal, all parameters are pushed on the stack, and they are pushed right
  2240. to left, instead of left to right for Turbo Pascal. This is especially important if you
  2241. have some assembly subroutines in Turbo Pascal which you would like to translate
  2242. to Free Pascal.
  2243. Function results are returned in the accumulator, if they fit in the register.
  2244. The registers are not saved when calling a function or procedure. If you want to
  2245. call a procedure or function from assembly language, you must save any registers
  2246. you wish to preserve.
  2247. The first thing a procedure does is saving the base pointer, and setting the base
  2248. pointer equal to the stack pointer. References to the pushed parameters and local
  2249. variables are constructed using the base pointer.
  2250.  
  2251.                                           39
  2252.  
  2253.  
  2254.  
  2255. CHAPTER 3. USING ASSEMBLY LANGUAGE 3.3. CALLING MECHANISM
  2256.  
  2257.  
  2258.  
  2259.                             Table 3.1: Calling mechanisms in Free Pascal
  2260.  
  2261.          Modifier      Pushing order Stack cleaned by Parameters in registers
  2262.          (none)        Right-to-left       Function           No
  2263.          cdecl         Right-to-left       Caller             No
  2264.          export        Right-to-left       Caller             No
  2265.          stdcall       Right-to-left       Function           No
  2266.          popstack Right-to-left            Caller             No
  2267.  
  2268.  
  2269. When the procedure or function exits, it clears the stack.
  2270. When you want your code to be called by a C library or used in a C program,
  2271. you will run into trouble because of this calling mechanism. In C, the calling
  2272. procedure is expected to clear the stack, not the called procedure. In other words,
  2273. the arguments still are on the stack when the procedure exits. To avoid this problem,
  2274. Free Pascal supports the export modifier. Procedures that are defined using the
  2275. export modifier, use a C-compatible calling mechanism. This means that they can
  2276. be called from a C program or library, or that you can use them as a callback
  2277. function.
  2278. This also means that you cannot call this procedure or function from your own
  2279. program, since your program uses the Pascal calling convention. However, in the
  2280. exported function, you can of course call other Pascal routines.
  2281. As of version 0.9.8, the Free Pascal compiler supports also the cdecl and stdcall
  2282. modifiers, as found in Delphi. The cdecl modifier does the same as the export
  2283. modifier, and stdcall does nothing, since Free Pascal pushes the paramaters from
  2284. right to left by default. In addition to the Delphi cdecl construct, Free Pascal
  2285. also supports the popstack directive; it is nearly the same a the cdecl directive,
  2286. only it still mangles the name, i.e. makes it into a name such as the compiler uses
  2287. internally.
  2288. All this is summarized in table (3.1). The first column lists the modifier you specify
  2289. for a procedure declaration. The second one lists the order the paramaters are
  2290. pushed on the stack. The third column specifies who is responsible for cleaning the
  2291. stack: the caller or the called function. Finally, the last column specifies if registers
  2292. are used to pass parameters to the function.
  2293. More about this can be found in chapter 4, page 43 on linking.
  2294.  
  2295.  
  2296.  Ix86 calling conventions
  2297. Standard entry code for procedures and functions is as follows on the x86 architec-
  2298. ture:
  2299.  
  2300.    pushl            %ebp
  2301.    movl             %esp,%ebp
  2302.  
  2303. The generated exit sequence for procedure and functions looks as follows:
  2304.  
  2305.   leave
  2306.   ret $xx
  2307.  
  2308. Where xx is the total size of the pushed parameters.
  2309.  
  2310.  
  2311.                                                  40
  2312.  
  2313.  
  2314.  
  2315. CHAPTER 3. USING ASSEMBLY LANGUA
  2316.                                      3.4.          GE
  2317.                                               SIGNALLING CHANGED REGISTERS
  2318.  
  2319.  
  2320. To have more information on function return values take a look at section 3.5, page
  2321. 41.
  2322.  
  2323.  
  2324.  M680x0 calling conventions
  2325. Standard entry code for procedures and functions is as follows on the 680x0 archi-
  2326. tecture:
  2327.  
  2328.        move.l a6,-(sp)
  2329.        move.l sp,a6
  2330.  
  2331. The generated exit sequence for procedure and functions looks as follows:
  2332.  
  2333.   unlk        a6
  2334.   move.l (sp)+,a0            ; Get return address
  2335.   add.l #xx,sp               ; Remove allocated stack
  2336.   move.l a0,-(sp)            ; Put back return address on top of the stack
  2337.  
  2338. Where xx is the total size of the pushed parameters.
  2339. To have more information on function return values take a look at section 3.5, page
  2340. 41.
  2341.  
  2342.  
  2343. 3.4 Signalling changed registers
  2344.  
  2345. When the compiler uses variables, it sometimes stores them, or the result of some
  2346. calculations, in the processor registers. If you insert assembler code in your program
  2347. that modifies the processor registers, then this may interfere with the compiler's
  2348. idea about the registers. To avoid this problem, Free Pascal allows you to tell the
  2349. compiler which registers have changed. The compiler will then avoid using these
  2350. registers. Telling the compiler which registers have changed, is done by specifying
  2351. a set of register names behind an assembly block, as follows:
  2352.  
  2353. asm...
  2354. end ['R1',...,'Rn'];
  2355.  
  2356. Here R1 to Rn are the names of the 32-bit registers you modify in your assembly
  2357. code.
  2358. As an example :
  2359.  
  2360.        asm
  2361.        movl BP,%eax
  2362.        movl 4(%eax),%eax
  2363.        movl %eax,__RESULT
  2364.        end ['EAX'];
  2365.  
  2366. This example tells the compiler that the EAX register was modified.
  2367.  
  2368.  
  2369. 3.5 Register Conventions
  2370.  
  2371. The compiler has di erent register conventions, depending on the target processor
  2372. used.
  2373.  
  2374.                                              41
  2375.  
  2376.  
  2377.  
  2378. CHAPTER 3. USING ASSEMBLY LANGUAGE
  2379.                                                  3.5. REGISTER CONVENTIONS
  2380.  
  2381.  
  2382.  Intel x86 version
  2383. When optimizations are on, no register can be freely modified, without first being
  2384. saved and then restored. Otherwise, EDI is usually used as a scratch register and
  2385. can be freely used in assembler blocks.
  2386.  
  2387.  
  2388.  Motorola 680x0 version
  2389. Registers which can be freely modified without saving are registers D0, D1, D6, A0,
  2390. A1, and floating point registers FP2 to FP7. All other registers are to be considered
  2391. reserved and should be saved and then restored when used in assembler blocks.
  2392.  
  2393.  
  2394.  
  2395.  
  2396.  
  2397.  
  2398.  
  2399.  
  2400.  
  2401.  
  2402.  
  2403.  
  2404.  
  2405.  
  2406.  
  2407.  
  2408.  
  2409.  
  2410.  
  2411.  
  2412.  
  2413.  
  2414.  
  2415.  
  2416.  
  2417.  
  2418.  
  2419.  
  2420.  
  2421.  
  2422.  
  2423.  
  2424.  
  2425.  
  2426.  
  2427.  
  2428.  
  2429.  
  2430.  
  2431.  
  2432.  
  2433.                                            42
  2434.  
  2435.  
  2436.  
  2437. Chapter 4
  2438.  
  2439. Linking issues
  2440.  
  2441. When you only use Pascal code, and Pascal units, then you will not see much of
  2442. the part that the linker plays in creating your executable. The linker is only called
  2443. when you compile a program. When compiling units, the linker isn't invoked.
  2444. However, there are times that you want to link to C libraries, or to external object
  2445. files that are generated using a C compiler (or even another pascal compiler). The
  2446. Free Pascal compiler can generate calls to a C function, and can generate functions
  2447. that can be called from C (exported functions). More on these calling conventions
  2448. can be found in section 3.3, page 39.
  2449. In general, there are 2 things you must do to use a function that resides in an
  2450. external library or object file:
  2451.  
  2452.    1. You must make a pascal declaration of the function or procedure you want to
  2453.       use.
  2454.  
  2455.    2. You must tell the compiler where the function resides, i.e. in what object file
  2456.       or what library, so the compiler can link the necessary code in.
  2457.  
  2458. The same holds for variables. To access a variable that resides in an external object
  2459. file, you must declare it, and tell the compiler where to find it. The following
  2460. sections attempt to explain how to do this.
  2461.  
  2462.  
  2463. 4.1 Using external functions or procedures
  2464.  
  2465. The first step in using external code blocks is declaring the function you want to
  2466. use. Free Pascal supports Delphi syntax, i.e. you must use the external directive.
  2467. The external directive replaces, in e ect, the code block of the function. As such,
  2468. It cannot be used in an interface section of a unit, but must always reside in the
  2469. implementation section.
  2470. There exist four variants of the external directive :
  2471.  
  2472.    1. A simple external declaration:
  2473.  
  2474.       Procedure ProcName (Args : TPRocArgs); external;
  2475.  
  2476.       The external directive tells the compiler that the function resides in an
  2477.       external block of code. You can use this together with the {$L } or {$LinkLib
  2478.  
  2479.                                          43
  2480.  
  2481.  
  2482.  
  2483. CHAPTER 4. LINKING
  2484.                      4.1. ISSUES
  2485.                            USING EXTERNAL FUNCTIONS OR PROCEDURES
  2486.  
  2487.  
  2488.       } directives to link to a function or procedure in a library or external object
  2489.       file. Object files are looked for in the object search path (set by -Fo) and
  2490.       libraries are searched for in the linker path (set by -Fl).
  2491.  
  2492.    2. You can give the external directive a library name as an argument:
  2493.  
  2494.       Procedure ProcName (Args : TPRocArgs); external 'Name';
  2495.  
  2496.       This tells the compiler that the procedure resides in a library with name
  2497.       'Name'. This method is equivalent to the following:
  2498.  
  2499.       Procedure ProcName (Args : TPRocArgs);external;
  2500.       {$LinkLib 'Name'}
  2501.  
  2502.    3. The external can also be used with two arguments:
  2503.  
  2504.       Procedure ProcName (Args : TPRocArgs); external 'Name'
  2505.                                                        name 'OtherProcName';
  2506.  
  2507.       This has the same meaning as the previous declaration, only the compiler will
  2508.       use the name 'OtherProcName' when linking to the library. This can be used
  2509.       to give di erent names to procedures and functions in an external library.
  2510.       This method is equivalent to the following code:
  2511.  
  2512.       Procedure OtherProcName (Args : TProcArgs); external;
  2513.       {$LinkLib 'Name'}
  2514.  
  2515.       Procedure ProcName (Args : TPRocArgs);
  2516.  
  2517.       begin
  2518.         OtherProcName (Args);
  2519.       end;
  2520.  
  2521.    4. Lastly, onder Windows and os/2, there is a fourth possibility to specify an
  2522.       external function: In .DLL files, functions also have a unique number (their
  2523.       index). It is possible to refer to these fuctions using their index:
  2524.  
  2525.       Procedure ProcName (Args : TPRocArgs); external 'Name' Index SomeIndex;
  2526.  
  2527.       This tells the compiler that the procedure ProcName resides in a dynamic link
  2528.       library, with index SomeIndex.
  2529.       Remark : Note that this is ONLY available under Windows and os/2.
  2530.  
  2531. In earlier versions of the Free Pascal compiler, the following construct was also
  2532. possible :
  2533.  
  2534. Procedure ProcName (Args : TPRocArgs); [ C ];
  2535.  
  2536. This method is equivalent to the following statement:
  2537.  
  2538. Procedure ProcName (Args : TPRocArgs); cdecl; external;
  2539.  
  2540. However, the [ C ] directive is no longer supported as of version 0.99.5 of Free
  2541. Pascal, therefore you should use the external directive, with the cdecl directive,
  2542. if needed.
  2543.  
  2544.                                           44
  2545.  
  2546.  
  2547.  
  2548. CHAPTER 4. LINKING ISSUES                      4.2. USING EXTERNAL VARIABLES
  2549.  
  2550.  
  2551. 4.2 Using external variables
  2552.  
  2553. Some libaries or code blocks have variables which they export. You can access
  2554. these variables much in the same way as external functions. To access an external
  2555. variable, you declare it as follows:
  2556.  
  2557. VarMyVar : MyType; external name 'varname';
  2558. The e ect of this declaration is twofold:
  2559.  
  2560.       1. No space is allocated for this variable.
  2561.       2. The name of the variable used in the assembler code is varname. This is a
  2562.          case sensitive name, so you must be careful.
  2563.  
  2564. The variable will be accessible with it's declared name, i.e. MyVar in this case.
  2565. A second possibility is the declaration:
  2566.  
  2567. Varvarname : MyType; cvar; external;
  2568. The e ect of this declaration is twofold as in the previous case:
  2569.  
  2570.       1. The external modifier ensures that no space is allocated for this variable.
  2571.       2. The cvar modifier tells the compiler that the name of the variable used in
  2572.          the assembler code is exactly as specified in the declaration. This is a case
  2573.          sensitive name, so you must be careful.
  2574.  
  2575. In this case, you access the variable with it's C name, but case insensitive. The first
  2576. possibility allows you to change the name of the external variable for internal use.
  2577. In order to be able to compile such statements, the compiler switch -Sv must be
  2578. used.
  2579. As an example, let's look at the following C file (in extvar.c):
  2580.  
  2581. /*
  2582. Declare a variable, allocate storage
  2583. */
  2584. int extvar = 12;
  2585.  
  2586. And the following program (in extdemo.pp):
  2587.  
  2588. Program ExtDemo;
  2589.  
  2590. {$L extvar.o}
  2591.  
  2592. Var { Case sensitive declaration !! }
  2593.         extvar : longint; cvar;external;
  2594.         I : longint; external name 'extvar';
  2595. begin
  2596.       { Extvar can be used case insensitive !! }
  2597.       Writeln ('Variable ''extvar'' has value : ',ExtVar);
  2598.       Writeln ('Variable ''I''             has value : ',i);
  2599. end.
  2600.  
  2601.                                              45
  2602.  
  2603.  
  2604.  
  2605. CHAPTER 4. LINKING ISSUES                        4.3. LINKING TO AN OBJECT FILE
  2606.  
  2607.  
  2608. Compiling the C file, and the pascal program:
  2609.  
  2610. gcc -c -o extvar.o extvar.c
  2611. ppc386 -Sv extdemo
  2612.  
  2613. Will produce a program extdemo which will print
  2614.  
  2615. Variable 'extvar' has value : 12
  2616. Variable 'I'             has value : 12
  2617.  
  2618. on your screen.
  2619.  
  2620.  
  2621. 4.3 Linking to an object file
  2622.  
  2623. Having declared the external function or variable that resides in an object file,
  2624. you can use it as if it was defined in your own program or unit. To produce an
  2625. executable, you must still link the object file in. This can be done with the {$L
  2626. file.o} directive.
  2627. This will cause the linker to link in the object file file.o. On linux systems, this
  2628. filename is case sensitive. Under dos, case isn't important. Note that file.o must
  2629. be in the current directory if you don't specify a path. The linker will not search
  2630. for file.o if it isn't found.
  2631. You cannot specify libraries in this way, it is for object files only.
  2632. Here we present an example. Consider that you have some assembly routine that
  2633. calculates the nth Fibonacci number :
  2634.  
  2635. .text      .align 4
  2636. .globl Fibonacci
  2637.            .type Fibonacci,@function
  2638. Fibonacci:
  2639.            pushl %ebp
  2640.            movl %esp,%ebp
  2641.            movl 8(%ebp),%edx
  2642.            xorl %ecx,%ecx
  2643.            xorl %eax,%eax
  2644.            movl $1,%ebx
  2645.            incl %edx
  2646. loop:      decl %edx
  2647.            je endloop
  2648.            movl %ecx,%eax
  2649.            addl %ebx,%eax
  2650.            movl %ebx,%ecx
  2651.            movl %eax,%ebx
  2652.            jmp loop
  2653. endloop:movl %ebp,%esp
  2654.            popl %ebp
  2655.            ret
  2656.  
  2657. Then you can call this function with the following Pascal Program:
  2658.  
  2659.                                            46
  2660.  
  2661.  
  2662.  
  2663. CHAPTER 4. LINKING ISSUES                          4.4. LINKING TO A LIBRARY
  2664.  
  2665.  
  2666. Program FibonacciDemo;
  2667.  
  2668. var i : longint;
  2669.  
  2670. Function Fibonacci (L : longint):longint;cdecl;external;
  2671.  
  2672. {$L fib.o}
  2673.  
  2674. begin
  2675.   For I:=1 to 40 do
  2676.         writeln ('Fib(',i,') : ',Fibonacci (i));
  2677. end.
  2678.  
  2679. With just two commands, this can be made into a program :
  2680.  
  2681. as -o fib.o fib.s
  2682. ppc386 fibo.pp
  2683.  
  2684. This example supposes that you have your assembler routine in fib.s, and your
  2685. Pascal program in fibo.pp.
  2686.  
  2687.  
  2688. 4.4 Linking to a library
  2689.  
  2690. To link your program to a library, the procedure depends on how you declared the
  2691. external procedure.
  2692. In case you used the follwing syntax to declare your procedure:
  2693.  
  2694. Procedure ProcName (Args : TPRocArgs); external 'Name';
  2695.  
  2696. You don't need to take additional steps to link your file in, the compiler will do all
  2697. that is needed for you. On Windows NT it will link to Name.dll, on linux your
  2698. program will be linked to library libname, which can be a static or dynamic library.
  2699. In case you used
  2700.  
  2701. Procedure ProcName (Args : TPRocArgs); external;
  2702.  
  2703. You still need to explicity link to the library. This can be done in 2 ways:
  2704.  
  2705.   1. You can tell the compiler in the source file what library to link to using the
  2706.         {$LinkLib 'Name'} directive:
  2707.  
  2708.         {$LinkLib 'gpm'}
  2709.  
  2710.         This will link to the gpm library. On linux systems, you needn't specify the
  2711.         extension or 'lib' prefix of the library. The compiler takes care of that. On
  2712.         dos or Windows systems, you need to specify the full name.
  2713.   2. You can also tell the compiler on the command-line to link in a library: The
  2714.         -k option can be used for that. For example
  2715.  
  2716.         ppc386 -k'-lgpm' myprog.pp
  2717.  
  2718.         Is equivalent to the above method, and tells the linker to link to the gpm
  2719.         library.
  2720.  
  2721.                                           47
  2722.  
  2723.  
  2724.  
  2725. CHAPTER 4. LINKING ISSUES                               4.5. MAKING LIBRARIES
  2726.  
  2727.  
  2728. As an example; consider the following program :
  2729.  
  2730. program printlength;
  2731.  
  2732. {$linklib c} { Case sensitive }
  2733.  
  2734. { Declaration for the standard C function strlen }
  2735. Function strlen (P : pchar) : longint; cdecl;external;
  2736.  
  2737. begin
  2738.   Writeln (strlen('Programming is easy !'));
  2739. end.
  2740.  
  2741. This program can be compiled with :
  2742.  
  2743. ppc386 prlen.pp
  2744.  
  2745. Supposing, of course, that the program source resides in prlen.pp.
  2746. You cannot use procedures or functions that have a variable number of arguments
  2747. in C. Pascal doesn't support this feature of C.
  2748.  
  2749. 4.5 Making libraries
  2750.  
  2751. Free Pascal supports making shared or static libraries in a straightforward and easy
  2752. manner. If you want to make libraries for other Free Pascal programmers, you just
  2753. need to provide a command line switch. If you want C programmers to be able to
  2754. use your code as well, you will need to adapt your code a little. This process is
  2755. described first.
  2756.  
  2757.  
  2758. Exporting functions
  2759. When exporting functions from a library, there are 2 things you must take in ac-
  2760. count:
  2761.  
  2762.    1. Calling conventions.
  2763.    2. Naming scheme.
  2764.  
  2765. The calling conventions are controlled by the modifiers cdecl, popstack, pascal,
  2766. stdcall. See section 3.3, page 39 for more information on the di erent kinds of
  2767. calling scheme.
  2768. The naming conventions can be controlled by 3 modifiers:
  2769.  
  2770. cdecl: A function that has a cdecl modifier, will be used with C calling conven-
  2771.         tions, that is, the caller clears the stack. Also the mangled name will be the
  2772.         name exactly as in the declaration. cdecl is part of the function declaration,
  2773.         and hence must be present both in the interface and implementation section
  2774.         of a unit.
  2775. export: A function that has an export modifier, uses also the exact declaration
  2776.         name as its mangled name. Under Windows NT and os/2, this modifier
  2777.         signals a function that is exported from a DLL. The calling conventions used
  2778.         by a export procedure depend on the OS. This keyword can be used only in
  2779.         the implementation section.
  2780.  
  2781.                                           48
  2782.  
  2783.  
  2784.  
  2785. CHAPTER 4. LINKING ISSUES                               4.5. MAKING LIBRARIES
  2786.  
  2787.  
  2788. Alias: The alias modifier can be used to give a supplementary assembler name
  2789.         to your function. This doesn't modify the calling conventions of the function.
  2790.  
  2791. If you want to make your procedures and functions available to C programmers, you
  2792. can do this very easily. All you need to do is declare the functions and procedures
  2793. that you want to make available as export, as follows:
  2794.  
  2795. Procedure ExportedProcedure; export;
  2796.  
  2797. Remark : You can only declare a function as exported in the Implementation
  2798. section of a unit. This function may not appear in the interface part of a unit. This
  2799. is logical, since a Pascal routine cannot call an exported function, anyway.
  2800. However, the generated object file will not contain the name of the function as you
  2801. declared it. The Free Pascal compiler "mangles" the name you give your function.
  2802. It makes the name all-uppercase, and adds the types of all parameters to it. There
  2803. are cases when you want to provide a mangled name without changing the calling
  2804. convention. In such cases, you can use the Alias modifier.
  2805. The Alias modifier allows you to specify another name (a nickname) for your
  2806. function or procedure.
  2807. The prototype for an aliased function or procedure is as follows :
  2808.  
  2809. Procedure AliasedProc; [ Alias : 'AliasName'];
  2810.  
  2811. The procedure AliasedProc will also be known as AliasName. Take care, the name
  2812. you specify is case sensitive (as C is).
  2813. Remark:       If you use in your unit functions that are in other units, or system
  2814. functions, then the C program will need to link in the object files from the units
  2815. too.
  2816.  
  2817.  
  2818. Exporting variables
  2819. Similarly as when you export functions, you can export variables. When exportig
  2820. variables, one should only consider the names of the variables. To declare a variable
  2821. that should be used by a C program, one declares it with the cvar modifier:
  2822.  
  2823. Var MyVar : MyTpe; cvar;
  2824.  
  2825. This will tell the compiler that the assembler name of the variable (the one which
  2826. is used by C programs) should be exactly as specified in the declaration, i.e., case
  2827. sensitive.
  2828. It is not allowed to declare multiple variables as cvar in one statement, i.e. the
  2829. following code will produce an error:
  2830.  
  2831. var Z1,Z2 : longint;cvar;
  2832.  
  2833.  
  2834. Compiling libraries
  2835. Once you have your (adapted) code, with exported and other functions, you can
  2836. compile your unit, and tell the compiler to make it into a library. The compiler will
  2837. simply compile your unit, and perform the necessary steps to transform it into a
  2838. static or shared (dynamical) library.
  2839. You can do this as follows, for a dynamical library:
  2840.  
  2841.                                             49
  2842.  
  2843.  
  2844.  
  2845. CHAPTER 4. LINKING ISSUES                                    4.5. MAKING LIBRARIES
  2846.  
  2847.  
  2848. ppc386 -CD myunit
  2849.  
  2850. On linux this will leave you with a file libmyunit.so. On Windows and os/2, this
  2851. will leave you with myunit.dll.
  2852. If you want a static library, you can do
  2853.  
  2854. ppc386 -CS myunit
  2855.  
  2856. This will leave you with libmyunit.a and a file myunit.ppu. The myunit.ppu is the
  2857. unit file needed by the Free Pascal compiler.
  2858. The resulting files are then libraries. To make static libraries, you need the ranlib or
  2859. ar program on your system. It is standard on any linux system, and is provided
  2860. with the GCC compiler under dos. For the dos distribution, a copy of ar is included
  2861. in the file gnuutils.zip.
  2862. BEWARE: This command doesn't include anything but the current unit in the
  2863. library. Other units are left out, so if you use code from other units, you must
  2864. deploy them together with your library.
  2865.  
  2866.  
  2867. Moving units into a library
  2868. You can put multiple units into a library with the ppumove command, as follows:
  2869.  
  2870. ppumove -e ppl -o name unit1 unit2 unit3
  2871.  
  2872. This will move 3 units in 1 library (called libname.so on linux, name.dll on Windows)
  2873. and it will create 3 files unit1.ppl, unit2.ppl and unit3.ppl, which are unit files, but
  2874. which tell the compiler to look in library name when linking your executable.
  2875. The ppumove program has options to create statical or dynamical libraries. It is
  2876. provided with the compiler.
  2877.  
  2878.  
  2879. Unit searching strategy
  2880. When you compile a program or unit, the compiler will by default always look for
  2881. .ppl files. If it doesn't find one, it will look for a .ppu file.
  2882. To be able to di erentiate between units that have been compiled as static or
  2883. dynamic libraries, there are 2 switches:
  2884.  
  2885. -XD: This will define the symbol FPC LINK DYNAMIC
  2886.  
  2887. -XS: This will define the symbol FPC LINK STATIC
  2888.  
  2889. Definition of one symbol will automatically undefine the other.
  2890. These two switches can be used in conjunction with the configuration file ppc386.cfg.
  2891. The existence of one of these symbols can be used to decide which unit search path
  2892. to set. For example:
  2893.  
  2894. # Set unit paths
  2895.  
  2896. #IFDEF FPC_LINK_STATIC
  2897. -Up/usr/lib/fpc/linuxunits/staticunits
  2898. #ENDIF
  2899.  
  2900.                                              50
  2901.  
  2902.  
  2903.  
  2904. CHAPTER 4. LINKING ISSUES                                4.6. USING SMART LINKING
  2905.  
  2906.  
  2907. #IFDEF FPC_LINK_DYNAMIC
  2908. -Up/usr/lib/fpc/linuxunits/sharedunits
  2909. #ENDIF
  2910.  
  2911. With such a configuration file, the compiler will look for it's units in di erent
  2912. directories, depending on whether -XD or -XS is used.
  2913.  
  2914.  
  2915. 4.6 Using smart linking
  2916.  
  2917. You can compile your units using smart linking. When you use smartlinking, the
  2918. compiler creates a series of code blocks that are as small as possible, i.e. a code
  2919. block will contain only the code for one procedure or function.
  2920. When you compile a program that uses a smart-linked unit, the compiler will only
  2921. link in the code that you actually need, and will leave out all other code. This
  2922. will result in a smaller binary, which is loaded in memory faster, thus speeding up
  2923. execution.
  2924. To enable smartlinking, one can give the smartlink option on the command line :
  2925. -Cx, or one can put the {$SMARTLINK ON} directive in the unit file:
  2926.  
  2927. Unit Testunit
  2928.  
  2929. {SMARTLINK ON}
  2930. Interface
  2931. ...
  2932.  
  2933. Smartlinking will slow down the compilation process, especially for large units.
  2934. When a unit foo.pp is smartlinked, the name of the codefile is changed to libfoo.a.
  2935. Technically speaking, the compiler makes small assembler files for each procedure
  2936. and function in the unit, as well as for all global defined variables (whether they're
  2937. in the interface section or not). It then assembles all these small files, and uses ar
  2938. to collect the resulting object files in one archive.
  2939. Smartlinking and the creation of shared (or dynamic) libraries are mutually exclu-
  2940. sive, that is, if you turn on smartlinking, then the creation of shared libraries is
  2941. turned of. The creation of static libraries is still possible. The reason for this is
  2942. that it has little sense in making a smarlinked dynamical library. The whole shared
  2943. library is loaded into memory anyway by the dynamic linker (or Windows NT),
  2944. so there would be no gain in size by making it smartlinked.
  2945.  
  2946.  
  2947.  
  2948.  
  2949.  
  2950.  
  2951.  
  2952.  
  2953.  
  2954.  
  2955.  
  2956.  
  2957.  
  2958.  
  2959.                                            51
  2960.  
  2961.  
  2962.  
  2963. Chapter 5
  2964.  
  2965. Objects
  2966.  
  2967. In this short chapter we give some technical things about objects. For instructions
  2968. on how to use and declare objects, see the Reference guide.
  2969.  
  2970.  
  2971. 5.1 Constructor and Destructor calls
  2972.  
  2973. When using objects that need virtual methods, the compiler uses two help pro-
  2974. cedures that are in the run-time library. They are called Help Destructor and
  2975. Help Constructor, and they are written in assembly language. They are used to
  2976. allocate the necessary memory if needed, and to insert the Virtual Method Table
  2977. (VMT) pointer in the newly allocated object.
  2978. When the compiler encounters a call to an object's constructor, it sets up the stack
  2979. frame for the call, and inserts a call to the Help Constructor procedure before
  2980. issuing the call to the real constructor. The helper procedure allocates the needed
  2981. memory (if needed) and inserts the VMT pointer in the object. After that, the real
  2982. constructor is called.
  2983. A call to Help Destructor is inserted in every destructor declaration, just before
  2984. the destructor's exit sequence.
  2985.  
  2986.  
  2987. 5.2 Memory storage of objects
  2988.  
  2989. Objects are stored in memory just as ordinary records with an extra field : a pointer
  2990. to the Virtual Method Table (VMT). This field is stored first, and all fields in the
  2991. object are stored in the order they are declared. This field is initialized by the call
  2992. to the object's Constructor method.
  2993. If the object you defined has no virtual methods, then a nil is stored in the VMT
  2994. pointer. This ensures that the size of objects is equal, whether they have virtual
  2995. methods or not.
  2996. The memory allocated looks as in table (5.1).
  2997.  
  2998.  
  2999. 5.3 The Virtual Method Table
  3000.  
  3001. The Virtual Method Table (VMT) for each object type consists of 2 check fields
  3002. (containing the size of the data), a pointer to the object's ancestor's VMT (Nil
  3003.  
  3004.                                           52
  3005.  
  3006.  
  3007.  
  3008. CHAPTER 5. OBJECTS                         5.3. THE VIRTUAL METHOD TABLE
  3009.  
  3010.  
  3011.  
  3012.                            Table 5.1: Object memory layout
  3013.  
  3014.              O set What
  3015.              +0        Pointer to VMT.
  3016.              +4        Data. All fields in the order the've been declared.
  3017.              ...
  3018.  
  3019.  
  3020.                     Table 5.2: Virtual Method Table memory layout
  3021.  
  3022.  O set What
  3023.  +0       Size of object type data
  3024.  +4       Minus the size of object type data. Enables determining of valid VMT pointers.
  3025.  +8       Pointer to ancestor VMT, Nil if no ancestor available.
  3026.  +12      Pointers to the virtual methods.
  3027.  ...
  3028.  
  3029.  
  3030. if there is no ancestor), and then the pointers to all virtual methods. The VMT
  3031. layout is illustrated in table (5.2).
  3032. The VMT is constructed by the compiler. Every instance of an object receives a
  3033. pointer to its VMT.
  3034.  
  3035.  
  3036.  
  3037.  
  3038.  
  3039.  
  3040.  
  3041.  
  3042.  
  3043.  
  3044.  
  3045.  
  3046.  
  3047.  
  3048.  
  3049.  
  3050.  
  3051.  
  3052.  
  3053.  
  3054.  
  3055.  
  3056.  
  3057.  
  3058.  
  3059.  
  3060.  
  3061.  
  3062.                                           53
  3063.  
  3064.  
  3065.  
  3066. Chapter 6
  3067.  
  3068. Generated code
  3069.  
  3070. The Free Pascal compiler relies on the assembler to make object files. It generates
  3071. just the assembly language file. In the following two sections, we discuss what is
  3072. generated when you compile a unit or a program.
  3073.  
  3074.  
  3075. 6.1 Units
  3076.  
  3077. When you compile a unit, the Free Pascal compiler generates 2 files :
  3078.  
  3079.    1. A unit description file (with extension .ppu, or .ppw on Windows NT ).
  3080.  
  3081.    2. An assembly language file (with extension .s).
  3082.  
  3083. The assembly language file contains the actual source code for the statements in
  3084. your unit, and the necessary memory allocations for any variables you use in your
  3085. unit. This file is converted by the assembler to an object file (with extension .o)
  3086. which can then be linked to other units and your program, to form an executable.
  3087. By default (compiler version 0.9.4 and up), the assembly file is removed after it
  3088. has been compiled. Only in the case of the -s command-line option, the assembly
  3089. file must be left on disk, so the assembler can be called later. You can disable the
  3090. erasing of the assembler file with the -a switch.
  3091. The unit file contains all the information the compiler needs to use the unit:
  3092.  
  3093.    1. Other used units, both in interface and implementation.
  3094.  
  3095.    2. Types and variables from the interface section of the unit.
  3096.  
  3097.    3. Function declarations from the interface section of the unit.
  3098.  
  3099.    4. Some debugging information, when compiled with debugging.
  3100.  
  3101.    5. A date and time stamp.
  3102.  
  3103. Macros, symbols and compiler directives are not saved to the unit description file.
  3104. Aliases for functions are also not written to this file, which is logical, since they
  3105. cannot appear in the interface section of a unit.
  3106. The detailed contents and structure of this file are described in the first appendix.
  3107. You can examine a unit description file using the dumpppu program, which shows
  3108. the contents of the file.
  3109.  
  3110.                                          54
  3111.  
  3112.  
  3113.  
  3114. CHAPTER 6. GENERATED CODE                                          6.2. PROGRAMS
  3115.  
  3116.  
  3117. If you want to distribute a unit without source code, you must provide both the
  3118. unit description file and the object file.
  3119. You can also provide a C header file to go with the object file. In that case, your
  3120. unit can be used by someone who wishes to write his programs in C. However, you
  3121. must make this header file yourself since the Free Pascal compiler doesn't make one
  3122. for you.
  3123.  
  3124.  
  3125. 6.2 Programs
  3126.  
  3127. When you compile a program, the compiler produces again 2 files :
  3128.  
  3129.    1. An assembly language file containing the statements of your program, and
  3130.       memory allocations for all used variables.
  3131.  
  3132.    2. A linker response file. This file contains a list of object files the linker must
  3133.       link together.
  3134.  
  3135. The link response file is, by default, removed from the disk. Only when you specify
  3136. the -s command-line option or when linking fails, then the file is left on the disk.
  3137. It is named link.res.
  3138. The assembly language file is converted to an object file by the assembler, and then
  3139. linked together with the rest of the units and a program header, to form your final
  3140. program.
  3141. The program header file is a small assembly program which provides the entry point
  3142. for the program. This is where the execution of your program starts, so it depends
  3143. on the operating system, because operating systems pass parameters to executables
  3144. in wildly di erent ways.
  3145. It's name is prt0.o, and the source file resides in prt0.s or some variant of this name.
  3146. It usually resided where the system unit source for your system resides. It's main
  3147. function is to save the environment and command-line arguments and set up the
  3148. stack. Then it calls the main program.
  3149.  
  3150.  
  3151.  
  3152.  
  3153.  
  3154.  
  3155.  
  3156.  
  3157.  
  3158.  
  3159.  
  3160.  
  3161.  
  3162.  
  3163.  
  3164.  
  3165.  
  3166.  
  3167.  
  3168.  
  3169.                                               55
  3170.  
  3171.  
  3172.  
  3173. Chapter 7
  3174.  
  3175. Intel MMX support
  3176.  
  3177. 7.1 What is it about ?
  3178.  
  3179. Free Pascal supports the new MMX (Multi-Media extensions) instructions of Intel
  3180. processors. The idea of MMX is to process multiple data with one instruction,
  3181. for example the processor can add simultaneously 4 words. To implement this
  3182. e ciently, the Pascal language needs to be extended. So Free Pascal allows to
  3183. add for example two array[0..3] of word, if MMX support is switched on. The
  3184. operation is done by the MMX unit and allows people without assembler knowledge
  3185. to take advantage of the MMX extensions.
  3186. Here is an example:
  3187.  
  3188. usesMMX; { include some predefined data types }
  3189. const
  3190.    { tmmxword = array[0..3] of word;, declared by unit MMX }
  3191.    w1 : tmmxword = (111,123,432,4356);
  3192.    w2 : tmmxword = (4213,63456,756,4);
  3193.  
  3194. varw3 : tmmxword;
  3195.    l : longint;
  3196.  
  3197. begin
  3198.    if is_mmx_cpu then { is_mmx_cpu is exported from unit mmx }
  3199.          begin
  3200. {$mmx+}           { turn mmx on }
  3201.                 w3:=w1+w2;
  3202. {$mmx-}
  3203.          end
  3204.    else
  3205.          begin
  3206.                 for i:=0 to 3 do
  3207.                   w3[i]:=w1[i]+w2[i];
  3208.          end;
  3209. end.
  3210.  
  3211.  
  3212.                                          56
  3213.  
  3214.  
  3215.  
  3216. CHAPTER 7. INTEL MMX SUPPORT                       7.2. SATURATION SUPPORT
  3217.  
  3218.  
  3219. 7.2 Saturation support
  3220.  
  3221. One important point of MMX is the support of saturated operations. If a operation
  3222. would cause an overflow, the value stays at the highest or lowest possible value for
  3223. the data type: If you use byte values you get normally 250+12=6. This is very
  3224. annoying when doing color manipulations or changing audio samples, when you
  3225. have to do a word add and check if the value is greater than 255. The solution
  3226. is saturation: 250+12 gives 255. Saturated operations are supported by the MMX
  3227. unit. If you want to use them, you have simple turn the switch saturation on:
  3228. $saturation+
  3229. Here is an example:
  3230.  
  3231. Program SaturationDemo;
  3232. { example for saturation, scales data (for example audio)
  3233.      with 1.5 with rounding to negative infinity
  3234. }
  3235.  
  3236. varaudio1 : tmmxword;
  3237. const
  3238.      helpdata1 : tmmxword = ($c000,$c000,$c000,$c000);
  3239.      helpdata2 : tmmxword = ($8000,$8000,$8000,$8000);
  3240.  
  3241. begin
  3242.      { audio1 contains four 16 bit audio samples }
  3243. {$mmx+}
  3244.      { convert it to $8000 is defined as zero, multiply data with 0.75 }
  3245.      audio1:=tmmxfixed16(audio1+helpdata2)*tmmxfixed(helpdata1);
  3246. {$saturation+}
  3247.      { avoid overflows (all values>$7fff becomes $ffff) }
  3248.      audio1:=(audio1+helpdata2)-helpdata2;
  3249. {$saturation-}
  3250.      { now mupltily with 2 and change to integer }
  3251.      audio1:=(audio1 shl 1)-helpdata2;
  3252. {$mmx-}
  3253. end.
  3254.  
  3255.  
  3256. 7.3 Restrictions of MMX support
  3257.  
  3258. In the beginning of 1997 the MMX instructions were introduced in the Pentium
  3259. processors, so multitasking systems wouldn't save the newly introduced MMX reg-
  3260. isters. To work around that problem, Intel mapped the MMX registers to the FPU
  3261. register.
  3262. The consequence is that you can't mix MMX and floating point operations. After
  3263. using MMX operations and before using floating point operations, you have to call
  3264. the routine EMMS of the MMX unit. This routine restores the FPU registers.
  3265. Careful: The compiler doesn't warn if you mix floating point and MMX operations,
  3266. so be careful.
  3267. The MMX instructions are optimized for multi media (what else?). So it isn't
  3268.  
  3269.                                         57
  3270.  
  3271.  
  3272.  
  3273. CHAPTER 7. INTEL MMX SUPPORT7.4. SUPPORTED MMX OPERATIONS
  3274.  
  3275.  
  3276. possible to perform each operation, some opertions give a type mismatch, see section
  3277. 7.4 for the supported MMX operations
  3278. An important restriction is that MMX operations aren't range or overflow checked,
  3279. even when you turn range and overflow checking on. This is due to the nature of
  3280. MMX operations.
  3281. The MMX unit must always be used when doing MMX operations because the exit
  3282. code of this unit clears the MMX unit. If it wouldn't do that, other program will
  3283. crash. A consequence of this is that you can't use MMX operations in the exit code
  3284. of your units or programs, since they would interfere with the exit code of the MMX
  3285. unit. The compiler can't check this, so you are responsible for this !
  3286.  
  3287.  
  3288. 7.4 Supported MMX operations
  3289.  
  3290. Still to be written...
  3291.  
  3292.  
  3293. 7.5 Optimizing MMX support
  3294.  
  3295. Here are some helpful hints to get optimal performance:
  3296.  
  3297.    * The EMMS call takes a lot of time, so try to seperate floating point and MMX
  3298.       operations.
  3299.  
  3300.    * Use MMX only in low level routines because the compiler saves all used MMX
  3301.       registers when calling a subroutine.
  3302.  
  3303.    * The NOT-operator isn't supported natively by MMX, so the compiler has to
  3304.       generate a workaround and this operation is ine cient.
  3305.  
  3306.    * Simple assignements of floating point numbers don't access floating point reg-
  3307.       isters, so you need no call to the EMMS procedure. Only when doing arithmetic,
  3308.       you need to call the EMMS procedure.
  3309.  
  3310.  
  3311.  
  3312.  
  3313.  
  3314.  
  3315.  
  3316.  
  3317.  
  3318.  
  3319.  
  3320.  
  3321.  
  3322.  
  3323.  
  3324.  
  3325.  
  3326.  
  3327.  
  3328.  
  3329.                                          58
  3330.  
  3331.  
  3332.  
  3333. Chapter 8
  3334.  
  3335. Memory issues
  3336.  
  3337. 8.1 The 32-bit model.
  3338.  
  3339. The Free Pascal compiler issues 32-bit code. This has several consequences:
  3340.  
  3341.    * You need a 386 processor to run the generated code. The compiler functions
  3342.      on a 286 when you compile it using Turbo Pascal, but the generated programs
  3343.      cannot be assembled or executed.
  3344.    * You don't need to bother with segment selectors. Memory can be addressed
  3345.      using a single 32-bit pointer. The amount of memory is limited only by the
  3346.      available amount of (virtual) memory on your machine.
  3347.    * The structures you define are unlimited in size. Arrays can be as long as you
  3348.      want. You can request memory blocks from any size.
  3349.  
  3350. The fact that 32-bit code is used, means that some of the older Turbo Pascal
  3351. constructs and functions are obsolete. The following is a list of functions which
  3352. shouldn't be used anymore:
  3353.  
  3354. Seg() : Returned the segment of a memory address. Since segments have no more
  3355.      meaning, zero is returned in the Free Pascal run-time library implementation
  3356.      of Seg.
  3357. Ofs() : Returned the o set of a memory address. Since segments have no more
  3358.      meaning, the complete address is returned in the Free Pascal implementation
  3359.      of this function. This has as a consequence that the return type is Longint
  3360.      instead of Word.
  3361. Cseg(), Dseg() : Returned, respectively, the code and data segments of your
  3362.      program. This returns zero in the Free Pascal implementation of the system
  3363.      unit, since both code and data are in the same memory space.
  3364. Ptr: Accepted a segment and o set from an address, and would return a pointer
  3365.      to this address. This has been changed in the run-time library. Standard it
  3366.      returns now simply the o set. If you want to retain the old functionality, you
  3367.      can recompile the run-time library with the DoMapping symbol defined. This
  3368.      will restore the Turbo Pascal behaviour.
  3369. memw and mem These arrays gave access to the dos memory. Free Pascal sup-
  3370.      ports them on the go32v2 platform, they are mapped into dos memory space.
  3371.      You need the GO32 unit for this. On other platforms, they are not supported
  3372.  
  3373.                                          59
  3374.  
  3375.  
  3376.  
  3377. CHAPTER 8. MEMORY ISSUES                                            8.2. THE STACK
  3378.  
  3379.  
  3380.  
  3381.                    Table 8.1: Stack frame when calling a procedure
  3382.  
  3383.              O set What is stored                             Optional ?
  3384.              +x        parameters                                Yes
  3385.              +12       function result                           Yes
  3386.              +8        self                                      Yes
  3387.              +4        Frame pointer of parent procedure         Yes
  3388.              +0        Return address                            No
  3389.  
  3390.  
  3391. You shouldn't use these functions, since they are very non-portable, they're specific
  3392. to dos and the ix86 processor. The Free Pascal compiler is designed to be portable
  3393. to other platforms, so you should keep your code as portable as possible, and not
  3394. system specific. That is, unless you're writing some driver units, of course.
  3395.  
  3396.  
  3397. 8.2 The stack
  3398.  
  3399. The stack is used to pass parameters to procedures or functions, to store local
  3400. variables, and, in some cases, to return function results.
  3401. When a function or procedure is called, then the following is done by the compiler :
  3402.  
  3403.   1. If there are any parameters to be passed to the procedure, they are pushed
  3404.      from right to left on the stack.
  3405.  
  3406.   2. If a function is called that returns a variable of type String, Set, Record,
  3407.      Object or Array, then an address to store the function result in, is pushed on
  3408.      the stack.
  3409.  
  3410.   3. If the called procedure or function is an object method, then the pointer to
  3411.      self is pushed on the stack.
  3412.  
  3413.   4. If the procedure or function is nested in another function or procedure, then
  3414.      the frame pointer of the parent procedure is pushed on the stack.
  3415.  
  3416.   5. The return address is pushed on the stack (This is done automatically by the
  3417.      instruction which calls the subroutine).
  3418.  
  3419. The resulting stack frame upon entering looks as in table (8.1).
  3420.  
  3421.  
  3422.  Intel x86 version
  3423. The stack is cleared with the ret I386 instruction, meaning that the size of all
  3424. pushed parameters is limited to 64K.
  3425.  
  3426. DOS
  3427.  
  3428. Under the DOS targets, the default stack is set to 256Kb. This value cannot be
  3429. modified for the GO32V1 target. But this can be modified with the GO32V2 target
  3430. using a special DJGPP utility stubedit. It is to note that the stack size may be
  3431. changed with some compiler switches, this stack size, if greater then the default
  3432. stack size will be used instead, otherwise the default stack size is used.
  3433.  
  3434.  
  3435.                                           60
  3436.  
  3437.  
  3438.  
  3439. CHAPTER 8. MEMORY ISSUES                                            8.3. THE HEAP
  3440.  
  3441.  
  3442. Linux
  3443.  
  3444. Under Linux, stack size is only limited by the available memory of the system.
  3445.  
  3446. OS/2
  3447.  
  3448. Under OS/2, stack size is determined by one of the runtime environment variables
  3449. set for EMX. Therefore, the stack size is user defined.
  3450.  
  3451.  
  3452.  Motorola 680x0 version
  3453. All depending on the processor target, the stack can be cleared in two manners, if
  3454. the target processor is a MC68020 or higher, the stack will be cleared with a simple
  3455. rtd instruction, meaning that the size of all pushed parameters is limited to 32K.
  3456. Otherwise on MC68000/68010 processors, the stack clearing mechanism is sligthly
  3457. more complicated, the exit code will look like this:
  3458.  
  3459. { move.l (sp)+,a0
  3460.      add.l    paramsize,a0
  3461.      move.l a0,-(sp)
  3462.      rts
  3463. }
  3464.  
  3465. Amiga
  3466.  
  3467. Under AmigaOS, stack size is determined by the user, which sets this value using
  3468. the stack program. Typical sizes range from 4K to 40K.
  3469.  
  3470. Atari
  3471.  
  3472. Under Atari TOS, stack size is currently limited to 8K, and it cannot be modified.
  3473. This may change in a future release of the compiler.
  3474.  
  3475.  
  3476. 8.3 The heap
  3477.  
  3478. The heap is used to store all dynamic variables, and to store class instances. The
  3479. interface to the heap is the same as in Turbo Pascal, although the e ects are maybe
  3480. not the same. On top of that, the Free Pascal run-time library has some extra
  3481. possibilities, not available in Turbo Pascal. These extra possibilities are explained
  3482. in the next subsections.
  3483.  
  3484.  
  3485. The heap grows
  3486. Free Pascal supports the HeapError procedural variable. If this variable is non-nil,
  3487. then it is called in case you try to allocate memory, and the heap is full. By default,
  3488. HeapError points to the GrowHeap function, which tries to increase the heap.
  3489. The growheap function issues a system call to try to increase the size of the memory
  3490. available to your program. It first tries to increase memory in a 1 Mb. chunk. If
  3491. this fails, it tries to increase the heap by the amount you requested from the heap.
  3492.  
  3493.                                           61
  3494.  
  3495.  
  3496.  
  3497. CHAPTER 8. MEMORY ISSUES                                                    8.3. THE HEAP
  3498.  
  3499.  
  3500. If the call to GrowHeap has failed, then a run-time error is generated, or nil is
  3501. returned, depending on the GrowHeap result.
  3502. If the call to GrowHeap was successful, then the needed memory will be allocated.
  3503.  
  3504.  
  3505. Using Blocks
  3506. If you need to allocate a lot of small blocks for a small period, then you may
  3507. want to recompile the run-time library with the USEBLOCKS symbol defined. If it is
  3508. recompiled, then the heap management is done in a di erent way.
  3509. The run-time library keeps a linked list of allocated blocks with size up to 256
  3510. bytes1. By default, it keeps 32 of these lists2.
  3511. When a piece of memory in a block is deallocated, the heap manager doesn't re-
  3512. ally deallocate the occupied memory. The block is simply put in the linked list
  3513. corresponding to its size.
  3514. When you then again request a block of memory, the manager checks in the list if
  3515. there is a non-allocated block which fits the size you need (rounded to 8 bytes). If
  3516. so, the block is used to allocate the memory you requested.
  3517. This method of allocating works faster if the heap is very fragmented, and you
  3518. allocate a lot of small memory chunks.
  3519. Since it is invisible to the program, this provides an easy way of improving the
  3520. performance of the heap manager.
  3521.  
  3522.  
  3523. Using the split heap
  3524. Remark : The split heap is still somewhat buggy. Use at your own risk for the
  3525. moment.
  3526. The split heap can be used to quickly release a lot of blocks you allocated previously.
  3527. Suppose that in a part of your program, you allocate a lot of memory chunks on
  3528. the heap. Suppose that you know that you'll release all this memory when this
  3529. particular part of your program is finished.
  3530. In Turbo Pascal, you could foresee this, and mark the position of the heap (using
  3531. the Mark function) when entering this particular part of your program, and release
  3532. the occupied memory in one call with the Release call.
  3533. For most purposes, this works very good. But sometimes, you may need to allo-
  3534. cate something on the heap that you don't want deallocated when you release the
  3535. allocated memory. That is where the split heap comes in.
  3536. When you split the heap, the heap manager keeps 2 heaps: the base heap (the
  3537. normal heap), and the temporary heap. After the call to split the heap, memory
  3538. is allocated from the temporary heap. When you're finished using all this memory,
  3539. you unsplit the heap. This clears all the memory on the split heap with one call.
  3540. After that, memory will be allocated from the base heap again.
  3541. So far, nothing special, nothing that can't be done with calls to mark and release.
  3542. Suppose now that you have split the heap, and that you've come to a point where
  3543. you need to allocate memory that is to stay allocated after you unsplit the heap
  3544. again. At this point, mark and release are of no use. But when using the split heap,
  3545. you can tell the heap manager to ¡temporarily¡ use the base heap again to allocate
  3546.   1The size can be set using the max size constant in the heap.inc source file.
  3547.   2The actual size is max size div 8.
  3548.  
  3549.  
  3550.                                                62
  3551.  
  3552.  
  3553.  
  3554. CHAPTER 8. MEMOR
  3555.                     8.4.     Y ISSUES
  3556.                             USING DOS MEMORY UNDER THE GO32 EXTENDER
  3557.  
  3558.  
  3559. memory. When you've allocated the needed memory, you can tell the heap manager
  3560. that it should start using the temporary heap again. When you're finished using
  3561. the temporary heap, you release it, and the memory you allocated on the base heap
  3562. will still be allocated.
  3563. To use the split-heap, you must recompile the run-time library with the TempHeap
  3564. symbol defined. This means that the following functions are available :
  3565.  
  3566.   procedure Split_Heap;
  3567.   procedure Switch_To_Base_Heap;
  3568.   procedure Switch_To_Temp_Heap;
  3569.   procedure Switch_Heap;
  3570.   procedure ReleaseTempHeap;
  3571.   procedure GetTempMem(var p : pointer;size : longint);
  3572.  
  3573. Split Heap is used to split the heap. It cannot be called two times in a row, without
  3574. a call to releasetempheap. Releasetempheap completely releases the memory used
  3575. by the temporary heap. Switching temporarily back to the base heap can be done
  3576. using the Switch To Base Heap call, and returning to the temporary heap is done
  3577. using the Switch To Temp Heap call. Switching from one to the other without
  3578. knowing on which one your are right now, can be done using the Switch Heap call,
  3579. which will split the heap first if needed.
  3580. A call to GetTempMem will allocate a memory block on the temporary heap, whatever
  3581. the current heap is. The current heap after this call will be the temporary heap.
  3582. Typically, what will appear in your code is the following sequence :
  3583.  
  3584. Split_Heap
  3585. ...
  3586. { Memory allocation }
  3587. ...
  3588. { !! non-volatile memory needed !!}
  3589. Switch_To_Base_Heap;
  3590. getmem (P,size);
  3591. Switch_To_Temp_Heap;
  3592. ...
  3593. {Memory allocation}
  3594. ...
  3595. ReleaseTempHeap;
  3596. {All allocated memory is now freed, except for the memory pointed to by 'P' }
  3597. ...
  3598.  
  3599.  
  3600. 8.4 Using dos memory under the Go32 extender
  3601.  
  3602. Because Free Pascal is a 32 bit compiler, and uses a dos extender, accessing DOS
  3603. memory isn't trivial. What follows is an attempt to an explanation of how to access
  3604. and use dos or real mode memory3.
  3605. In Proteced Mode, memory is accessed through Selectors and O sets. You can think
  3606. of Selectors as the protected mode equivalents of segments.
  3607. In Free Pascal, a pointer is an o set into the DS selector, which points to the Data
  3608. of your program.
  3609.   3Thanks to an explanation of Thomas schatzl (E-mail:tom at work@geocities.com).
  3610.  
  3611.  
  3612.                                               63
  3613.  
  3614.  
  3615.  
  3616. CHAPTER 8. MEMOR
  3617.                   8.4.     Y ISSUES
  3618.                           USING DOS MEMORY UNDER THE GO32 EXTENDER
  3619.  
  3620.  
  3621. To access the (real mode) dos memory, somehow you need a selector that points
  3622. to the dos memory. The GO32 unit provides you with such a selector: The
  3623. DosMemSelector variable, as it is conveniently called.
  3624. You can also allocate memory in dos's memory space, using the global dos alloc
  3625. function of the GO32 unit. This function will allocate memory in a place where dos
  3626. sees it.
  3627. As an example, here is a function that returns memory in real mode dos and returns
  3628. a selector:o set pair for it.
  3629.  
  3630. procedure dosalloc(var selector : word;
  3631.                           var segment : word;
  3632.                           size : longint);
  3633.  
  3634. var result : longint;
  3635.  
  3636. beginresult := global_dos_alloc(size);
  3637.         selector := word(result);
  3638.         segment := word(result shr 16);
  3639. end;
  3640.  
  3641. (You need to free this memory using the global dos free function.)
  3642. You can access any place in memory using a selector. You can get a selector using
  3643. the allocate ldt descriptor function, and then let this selector point to the
  3644. physical memory you want using the set segment base address function, and set
  3645. its length using set segment limit function. You can manipulate the memory
  3646. pointed to by the selector using the functions of the GO32 unit. For instance with
  3647. the seg fillchar function. After using the selector, you must free it again using
  3648. the free ldt selector function.
  3649. More information on all this can be found in the Unit reference, the chapter on the
  3650. GO32 unit.
  3651.  
  3652.  
  3653.  
  3654.  
  3655.  
  3656.  
  3657.  
  3658.  
  3659.  
  3660.  
  3661.  
  3662.  
  3663.  
  3664.  
  3665.  
  3666.  
  3667.  
  3668.  
  3669.  
  3670.  
  3671.  
  3672.                                         64
  3673.  
  3674.  
  3675.  
  3676. Chapter 9
  3677.  
  3678. Optimizations
  3679.  
  3680. 9.1          Non processor specific
  3681.  
  3682. The following sections describe the general optimizations done by the compiler, they
  3683. are not processor specific. Some of these require some compiler switch override while
  3684. others are done automatically (those which require a switch will be noted as such).
  3685.  
  3686.  
  3687.  Constant folding
  3688. In Free Pascal, if the operand(s) of an operator are constants, they will be evaluated
  3689. at compile time.
  3690. Example
  3691.  
  3692.    x:=1+2+3+6+5;
  3693. will generate the same code as
  3694.    x:=17;
  3695.  
  3696. Furthermore, if an array index is a constant, the o set will be evaluated at compile
  3697. time. This means that accessing MyData[5] is as e cient as accessing a normal
  3698. variable.
  3699. Finally, calling Chr, Hi, Lo, Ord, Pred, or Succ functions with constant parameters
  3700. generates no run-time library calls, instead, the values are evaluated at compile
  3701. time.
  3702.  
  3703.  
  3704.  Constant merging
  3705. Using the same constant string two or more times generates only one copy of the
  3706. string constant.
  3707.  
  3708.  
  3709.  Short cut evaluation
  3710. Evaluation of boolean expression stops as soon as the result is known, which makes
  3711. code execute faster then if all boolean operands were evaluated.
  3712.  
  3713.  
  3714.  
  3715.  
  3716.                                          65
  3717.  
  3718.  
  3719.  
  3720. CHAPTER 9. OPTIMIZATIONS                       9.1. NON PROCESSOR SPECIFIC
  3721.  
  3722.  
  3723.  Constant set inlining
  3724. Using the in operator is always more e cient then using the equivalent <>, =, <=,
  3725. >=, < and > operators. This is because range comparisons can be done more easily
  3726. with in then with normal comparison operators.
  3727.  
  3728.  
  3729.  Small sets
  3730. Sets which contain less then 33 elements can be directly encoded using a 32-bit
  3731. value, therefore no run-time library calls to evaluate operands on these sets are
  3732. required; they are directly encoded by the code generator.
  3733.  
  3734.  
  3735.  Range checking
  3736. Assignments of constants to variables are range checked at compile time, which
  3737. removes the need of the generation of runtime range checking code.
  3738. Remark: This feature was not implemented before version 0.99.5 of Free Pascal.
  3739.  
  3740.  
  3741.  Shifts instead of multiply or divide
  3742. When one of the operands in a multiplication is a power of two, they are encoded
  3743. using arithmetic shift instructions, which generates more e cient code.
  3744. Similarly, if the divisor in a div operation is a power of two, it is encoded using
  3745. arithmetic shift instructions.
  3746. The same is true when accessing array indexes which are powers of two, the address
  3747. is calculated using arithmetic shifts instead of the multiply instruction.
  3748.  
  3749.  
  3750.  Automatic alignment
  3751. By default all variables larger then a byte are guaranteed to be aligned at least on
  3752. a word boundary.
  3753. Furthermore all pointers allocated using the standard runtime library (New and
  3754. GetMem among others) are guaranteed to return pointers aligned on a quadword
  3755. boundary (64-bit alignment).
  3756. Alignment of variables on the stack depends on the target processor.
  3757.  Remark: Quadword alignment of pointers is not guaranteed on systems which
  3758. don't use an internal heap, such as for the Win32 target.
  3759. Remark: Alignment is also done between fields in records, objects and classes, this
  3760. is not the same as in Turbo Pascal and may cause problems when using disk I/O
  3761. with these types. To get no alignment between fields use the packed directive or
  3762. the {$PackRecords n} switch. For further information, take a look at the reference
  3763. manual under the record heading.
  3764.  
  3765.  
  3766.  Smart linking
  3767. This feature removes all unreferenced code in the final executable file, making the
  3768. executable file much smaller.
  3769. Smart linking is switched on with the -Cx command-line switch, or using the
  3770. {$SMARTLINK ON} global directive.
  3771.  
  3772.  
  3773.                                          66
  3774.  
  3775.  
  3776.  
  3777. CHAPTER 9. OPTIMIZATIONS                         9.1. NON PROCESSOR SPECIFIC
  3778.  
  3779.  
  3780.  Remark:        Smart linking was implemented starting with version 0.99.6 of Free
  3781. Pascal.
  3782.  
  3783.  
  3784.  Inline routines
  3785. The following runtime library routines are coded directly into the final executable
  3786. : Lo, Hi, High, Sizeof, TypeOf, Length, Pred, Succ, Inc, Dec and Assigned.
  3787. Remark: Inline Inc and Dec were not completely implemented until version 0.99.6
  3788. of Free Pascal.
  3789.  
  3790.  
  3791.  Case optimization
  3792. When using the -O1 (or higher) switch, case statements will be generated using a
  3793. jump table if appropriate, to make them execute faster.
  3794.  
  3795.  
  3796.  Stack frame omission
  3797. Under specific conditions, the stack frame (entry and exit code for the routine, see
  3798. section 3.3) will be omitted, and the variable will directly be accessed via the stack
  3799. pointer.
  3800. Conditions for omission of the stack frame :
  3801.  
  3802.    * The function has no parameters nor local variables.
  3803.  
  3804.    * Routine does not call other routines.
  3805.  
  3806.    * Routine does not contain assembler statements. However, a assembler rou-
  3807.      tine may omit it's stack frame.
  3808.  
  3809.    * Routine is not declared using the Interrupt directive.
  3810.  
  3811.    * Routine is not a constructor or destructor.
  3812.  
  3813.  
  3814.  Register variables
  3815. When using the -Or switch, local variables or parameters which are used very often
  3816. will be moved to registers for faster access.
  3817.  Remark: Register variable allocation is currently an experimental feature, and
  3818. should be used with caution.
  3819.  
  3820.  
  3821.  Intel x86 specific
  3822. Here follows a listing of the optimizing techniques used in the compiler:
  3823.  
  3824.   1. When optimizing for a specific Processor (-Op1, -Op2, -Op3, the following
  3825.      is done:
  3826.  
  3827.             * In case statements, a check is done whether a jump table or a sequence
  3828.               of conditional jumps should be used for optimal performance.
  3829.             * Determines a number of strategies when doing peephole optimization,
  3830.               e.g.: movzbl (%ebp), %eax will be changed into xorl %eax,%eax; movb
  3831.               (%ebp),%al for Pentium and PentiumMMX.
  3832.  
  3833.                                           67
  3834.  
  3835.  
  3836.  
  3837. CHAPTER 9. OPTIMIZATIONS                             9.1. NON PROCESSOR SPECIFIC
  3838.  
  3839.  
  3840.  2. When optimizing for speed (-OG, the default) or size (-Og), a choice is made
  3841.     between using shorter instructions (for size) such as enter $4, or longer in-
  3842.     structions subl $4,%esp for speed. When smaller size is requested, things
  3843.     aren't aligned on 4-byte boundaries. When speed is requested, things are
  3844.     aligned on 4-byte boundaries as much as possible.
  3845.  3. Fast optimizations (-O1): activate the peephole optimizer
  3846.  4. Slower optimizations (-O2): also activate the common subexpression elimina-
  3847.     tion (formerly called the "reloading optimizer")
  3848.  5. Uncertain optimizations (-Ou): With this switch, the common subexpression
  3849.     elimination algorithm can be forced into making uncertain optimizations.
  3850.     Although you can enable uncertain optimizations in most cases, for people
  3851.     who do not understand the following technical explanation, it might be the
  3852.     safest to leave them o .
  3853.  
  3854.             If uncertain optimizations are enabled, the CSE algortihm assumes
  3855.             that
  3856.               * If something is written to a local/global register or a proce-
  3857.                     dure/function parameter, this value doesn't overwrite the value
  3858.                     to which a pointer points.
  3859.               * If something is written to memory pointed to by a pointer vari-
  3860.                     able, this value doesn't overwrite the value of a local/global vari-
  3861.                     able or a procedure/function parameter.
  3862.     The practical upshot of this is that you cannot use the uncertain optimiza-
  3863.     tions if you both write and read local or global variables directly and through
  3864.     pointers (this includes Var parameters, as those are pointers too).
  3865.     The following example will produce bad code when you switch on uncertain
  3866.     optimizations:
  3867.  
  3868.     Var temp: Longint;
  3869.  
  3870.     Procedure Foo(Var Bar: Longint);
  3871.     Begin
  3872.        If (Bar = temp)
  3873.             Then
  3874.               Begin
  3875.                     Inc(Bar);
  3876.                     If (Bar <> temp) then Writeln('bug!')
  3877.               End
  3878.     End;
  3879.  
  3880.     Begin
  3881.        Foo(Temp);
  3882.     End.
  3883.  
  3884.     The reason it produces bad code is because you access the global variable Temp
  3885.     both through its name Temp and through a pointer, in this case using the Bar
  3886.     variable parameter, which is nothing but a pointer to Temp in the above code.
  3887.     On the other hand, you can use the uncertain optimizations if you access
  3888.     global/local variables or parameters through pointers, and only access them
  3889.     through this pointer1.
  3890.  1 You can use multiple pointers to point to the same variable as well, that doesn't matter.
  3891.  
  3892.  
  3893.                                                68
  3894.  
  3895.  
  3896.  
  3897. CHAPTER 9. OPTIMIZATIONS                           9.2. OPTIMIZATION SWITCHES
  3898.  
  3899.  
  3900.      For example:
  3901.  
  3902.      Type TMyRec = Record
  3903.                          a, b: Longint;
  3904.                        End;
  3905.               PMyRec = ^TMyRec;
  3906.  
  3907.  
  3908.               TMyRecArray = Array [1..100000] of TMyRec;
  3909.               PMyRecArray = ^TMyRecArray;
  3910.  
  3911.      Var MyRecArrayPtr: PMyRecArray;
  3912.              MyRecPtr: PMyRec;
  3913.              Counter: Longint;
  3914.  
  3915.      Begin
  3916.         New(MyRecArrayPtr);
  3917.         For Counter := 1 to 100000 Do
  3918.              Begin
  3919.                 MyRecPtr := @MyRecArrayPtr^[Counter];
  3920.                 MyRecPtr^.a := Counter;
  3921.                 MyRecPtr^.b := Counter div 2;
  3922.              End;
  3923.      End.
  3924.  
  3925.      Will produce correct code, because the global variable MyRecArrayPtr is not
  3926.      accessed directly, but only through a pointer (MyRecPtr in this case).
  3927.      In conclusion, one could say that you can use uncertain optimizations only
  3928.      when you know what you're doing.
  3929.  
  3930.  
  3931. Motorola 680x0 specific
  3932. Using the -O2 switch does several optimizations in the code produced, the most
  3933. notable being:
  3934.  
  3935.    * Sign extension from byte to long will use EXTB
  3936.    * Returning of functions will use RTD
  3937.    * Range checking will generate no run-time calls
  3938.    * Multiplication will use the long MULS instruction, no runtime library call will
  3939.      be generated
  3940.    * Division will use the long DIVS instruction, no runtime library call will be
  3941.      generated
  3942.  
  3943.  
  3944. 9.2 Optimization switches
  3945.  
  3946. This is where the various optimizing switches and their actions are described,
  3947. grouped per switch.
  3948.  
  3949. -On: with n = 1..3: these switches activate the optimizer. A higher level auto-
  3950.      matically includes all lower levels.
  3951.  
  3952.                                              69
  3953.  
  3954.  
  3955.  
  3956. CHAPTER 9. OPTIMIZATIONS                       9.3. TIPS TO GET FASTER CODE
  3957.  
  3958.  
  3959.         * Level 1 (-O1) activates the peephole optimizer (common instruction se-
  3960.            quences are replaced by faster equivalents).
  3961.         * Level 2 (-O2) enables the assembler data flow analyzer, which allows
  3962.            the common subexpression elimination procedure to remove unnecessary
  3963.            reloads of registers with values they already contain.
  3964.         * Level 3 (-O3) enables uncertain optimizations. For more info, see -Ou.
  3965.  
  3966. -OG: This causes the code generator (and optimizer, IF activated), to favor faster,
  3967.      but code-wise larger, instruction sequences (such as "subl $4,%esp") instead
  3968.      of slower, smaller instructions ("enter $4"). This is the default setting.
  3969.  
  3970. -Og: This one is exactly the reverse of -OG, and as such these switches are mu-
  3971.      tually exclusive: enabling one will disable the other.
  3972.  
  3973. -Or: This setting (once it's fixed) causes the code generator to check which vari-
  3974.      ables are used most, so it can keep those in a register.
  3975.  
  3976. -Opn: with n = 1..3: Setting the target processor does NOT activate the opti-
  3977.      mizer. It merely influences the code generator and, if activated, the optimizer:
  3978.  
  3979.         * During the code generation process, this setting is used to decide whether
  3980.            a jump table or a sequence of successive jumps provides the best perfor-
  3981.            mance in a case statement.
  3982.         * The peephole optimizer takes a number of decisions based on this setting,
  3983.            for example it translates certain complex instructions, such as
  3984.            movzbl (mem), %eax|
  3985.            to a combination of simpler instructions
  3986.            xorl %eax, %eax
  3987.            movb (mem), %al
  3988.            for the Pentium.
  3989.  
  3990. -Ou: This enables uncertain optimizations. You cannot use these always, however.
  3991.      The previous section explains when they can be used, and when they cannot
  3992.      be used.
  3993.  
  3994.  
  3995. 9.3 Tips to get faster code
  3996.  
  3997. Here, some general tips for getting better code are presented. They mainly concern
  3998. coding style.
  3999.  
  4000.    * Find a better algorithm. No matter how much you and the compiler tweak the
  4001.      code, a quicksort will (almost) always outperform a bubble sort, for example.
  4002.  
  4003.    * Use variables of the native size of the processor you're writing for. For the
  4004.      80x86 and compatibles, this is 32 bit, so you're best of using longint and
  4005.      cardinal variables.
  4006.  
  4007.    * Turn on the optimizer.
  4008.  
  4009.    * Write your if/then/else statements so that the code in the "then"-part gets
  4010.      executed most of the time (improves the rate of successful jump prediction).
  4011.  
  4012.  
  4013.  
  4014.                                          70
  4015.  
  4016.  
  4017.  
  4018. CHAPTER 9. OPTIMIZATIONS                                 9.4. FLOATING POINT
  4019.  
  4020.  
  4021.    * If you are allocating and disposing a lot of small memory blocks, check out
  4022.        the heapblocks variable (heapblocks are on by default from release 0.99.8 and
  4023.        later)
  4024.  
  4025.    * Profile your code (see the -pg switch) to find out where the bottlenecks are.
  4026.        If you want, you can rewrite those parts in assembler. You can take the code
  4027.        generated by the compiler as a starting point. When given the -a command-
  4028.        line switch, the compiler will not erase the assembler file at the end of the
  4029.        assembly process, so you can study the assembler file.
  4030.        Note: Code blocks which contain an assembler block, are not processed at all
  4031.        by the optimizer at this time. Update: as of version 0.99.11, the Pascal code
  4032.        surrounding the assembler blocks is optimized.
  4033.  
  4034.  
  4035. 9.4        Floating point
  4036.  
  4037. This is where can be found processor specific information on floating point code
  4038. generated by the compiler.
  4039.  
  4040.  
  4041.  Intel x86 specific
  4042. All normal floating point types map to their real type, including comp and extended.
  4043.  
  4044.  
  4045.  Motorola 680x0 specific
  4046. Early generations of the Motorola 680x0 processors did not have integrated floating
  4047. point units, so to circumvent this fact, all floating point operations are emulated
  4048. (with the $E+ switch, which is the default) using the IEEE Single floating point
  4049. type. In other words when emulation is on, Real, Single, Double and Extended all
  4050. map to the single floating point type.
  4051. When the $E switch is turned o , normal 68882/68881/68040 floating point opcodes
  4052. are emitted. The Real type still maps to Single but the other types map to their
  4053. true floating point types. Only basic FPU opcodes are used, which means that it
  4054. can work on 68040 processors correctly.
  4055. Remark: Double and Extended types in true floating point mode have not been
  4056. extensively tested as of version 0.99.5.
  4057. Remark: The comp data type is currently not supported.
  4058.  
  4059.  
  4060.  
  4061.  
  4062.  
  4063.  
  4064.  
  4065.  
  4066.  
  4067.  
  4068.  
  4069.  
  4070.  
  4071.  
  4072.  
  4073.                                             71
  4074.  
  4075.  
  4076.  
  4077. Appendix A
  4078.  
  4079. Anatomy of a unit file
  4080.  
  4081. A.1 Basics
  4082.  
  4083. The best and most updated documentation about the ppu files can be found in
  4084. ppu.pas and ppudump.pp which can be found in rtl/utils/.
  4085. To read or write the ppufile, you can use the ppu unit ppu.pas which has an object
  4086. called tppufile which holds all routines that deal with ppufile handling. While
  4087. describing the layout of a ppufile, the methods which can be used for it are presented
  4088. as well.
  4089. A unit file consists of basically five or six parts:
  4090.  
  4091.    1. A unit header.
  4092.  
  4093.    2. A file interface part.
  4094.  
  4095.    3. A definition part. Contains all type and procedure definitions.
  4096.  
  4097.    4. A symbol part. Contains all symbol names and references to their definitions.
  4098.  
  4099.    5. A browser part. Contains all references from this unit to other units and
  4100.       inside this unit. Only available when the uf has browser flag is set in the
  4101.       unit flags
  4102.  
  4103.    6. A file implementation part (currently unused).
  4104.  
  4105.  
  4106. A.2 reading ppufiles
  4107.  
  4108. We will first create an object ppufile which will be used below. We are opening unit
  4109. test.ppu as an example.
  4110.  
  4111. varppufile : pppufile;
  4112. begin
  4113. { Initialize object }
  4114.   ppufile:=new(pppufile,init('test.ppu');
  4115. { open the unit and read the header, returns false when it fails }
  4116.   if not ppufile.open then
  4117.      error('error opening unit test.ppu');
  4118.  
  4119.                                            72
  4120.  
  4121.  
  4122.  
  4123. APPENDIX A. ANATOMY OF A UNIT FILE                           A.3. THE HEADER
  4124.  
  4125.  
  4126.  
  4127. { here we can read the unit }
  4128.  
  4129. { close unit }
  4130.   ppufile.close;
  4131. { release object }
  4132.   dispose(ppufile,done);
  4133. end;
  4134.  
  4135. Note: When a function fails (for example not enough bytes left in an entry) it sets
  4136. the ppufile.error variable.
  4137.  
  4138.  
  4139. A.3 The Header
  4140.  
  4141. The header consists of a record containing 24 bytes:
  4142.  
  4143. tppuheader=packed record
  4144.         id        : array[1..3] of char; { = 'PPU' }
  4145.         ver       : array[1..3] of char;
  4146.         compiler : word;
  4147.         cpu       : word;
  4148.         target    : word;
  4149.         flags     : longint;
  4150.         size      : longint; { size of the ppufile without header }
  4151.         checksum : longint; { checksum for this ppufile }
  4152.   end;
  4153.  
  4154. The header is already read by the ppufile.open command. You can access all
  4155. fields using ppufile.header which holds the current header record.
  4156.  
  4157.  
  4158.  
  4159.  
  4160.  
  4161.  
  4162.  
  4163.  
  4164.  
  4165.  
  4166.  
  4167.  
  4168.  
  4169.  
  4170.  
  4171.  
  4172.  
  4173.  
  4174.  
  4175.  
  4176.  
  4177.  
  4178.  
  4179.                                         73
  4180.  
  4181.  
  4182.  
  4183. APPENDIX A. ANATOMY OF A UNIT FILE                                       A.4. THE SECTIONS
  4184.  
  4185.  
  4186.  field             description
  4187.  id                this      is     allways     'PPU',      can    be      checked    with
  4188.                    function ppufile.CheckPPUId:boolean;
  4189.  ver               ppu version,         currently '015',      can be checked with
  4190.                    function ppufile.GetPPUVersion:longint; (returns 15)
  4191.  compiler compiler version used to create the unit. Doesn't contain the
  4192.                    patchlevel. Currently 0.99 where 0 is the high byte and 99 the
  4193.                    low byte
  4194.  cpu               cpu for which this unit is created. 0 = i386 1 = m68k
  4195.  target            target for which this unit is created, this depends also on the cpu!
  4196.                    For i386: 0 Go32v1
  4197.                                    1 Go32V2
  4198.                                    2 Linux-i386
  4199.                                    3 OS/2
  4200.                                    4 Win32
  4201.                    For m68k: 0 Amiga
  4202.                                     1 Mac68k
  4203.                                     2 Atari
  4204.                                     3 Linux-m68k
  4205.  flag              the unit flags, contains a combination of the uf constants which
  4206.                    are definied in ppu.pas
  4207.  size              size of this unit without this header
  4208.  checksum checksum of the interface parts of this unit, which determine if a
  4209.                    unit is changed or not, so other units can see if they need to be
  4210.                    recompiled
  4211.  
  4212. A.4 The sections
  4213.  
  4214. After this header follow the sections. All sections work the same! A section consists
  4215. of entries and ends also with an entry, but containing the specific ibend constant
  4216. (see ppu.pas for a list of constants).
  4217. Each entry starts with an entryheader.
  4218.  
  4219.   tppuentry=packed record
  4220.        id      : byte;
  4221.        nr      : byte;
  4222.        size : longint;
  4223.   end;
  4224.  
  4225.  field Description
  4226.  id          this is 1 or 2 and can be checked to see whether the entry is
  4227.              correctly found. 1 means its a main entry, which says that it is
  4228.              part of the basic layout as explained before. 2 means that it it a
  4229.              sub entry of a record or object.
  4230.  nr          contains the ib constant number which determines what kind of
  4231.              entry it is.
  4232.  size        size of this entry without the header, can be used to skip entries
  4233.              very easily.
  4234. To read an entry you can simply call ppufile.readentry:byte, it returns the
  4235. tppuentry.nr field, which holds the type of the entry. A common way how this
  4236. works is (example is for the symbols):
  4237.  
  4238.   repeat
  4239.  
  4240.                                                    74
  4241.  
  4242.  
  4243.  
  4244. APPENDIX A. ANATOMY OF A UNIT FILE                        A.5. CREATING PPUFILES
  4245.  
  4246.  
  4247.      b:=ppufile.readentry;
  4248.      case b of
  4249.    ib<etc> : begin
  4250.                 end;
  4251.  ibendsyms : break;
  4252.      end;
  4253.   until false;
  4254.  
  4255. Then you can parse each entry type yourself. ppufile.readentry will take care
  4256. of skipping unread bytes in the entry and reads the next entry correctly! A special
  4257. function is skipuntilentry(untilb:byte):boolean; which will read the ppufile
  4258. until it finds entry untilb in the main entries.
  4259. Parsing an entry can be done with ppufile.getxxx functions. The available func-
  4260. tions are:
  4261.  
  4262. procedure ppufile.getdata(var b;len:longint);
  4263. function getbyte:byte;
  4264. function getword:word;
  4265. function getlongint:longint;
  4266. function getreal:ppureal;
  4267. function getstring:string;
  4268.  
  4269. To check if you're at the end of an entry you can use the following function:
  4270.  
  4271. function EndOfEntry:boolean;
  4272.  
  4273. notes:
  4274.  
  4275.    1. ppureal is the best real that exists for the cpu where the unit is created for.
  4276.       Currently it is extended for i386 and single for m68k.
  4277.    2. the ibobjectdef and ibrecorddef have stored a definition and symbol sec-
  4278.       tion for themselves. So you'll need a recursive call. See ppudump.pp for a
  4279.       correct implementation.
  4280.  
  4281. A complete list of entries and what their fields contain can be found in ppudump.pp.
  4282.  
  4283.  
  4284. A.5 Creating ppufiles
  4285.  
  4286. Creating a new ppufile works almost the same as writing. First you need to init the
  4287. object and call create:
  4288.  
  4289.   ppufile:=new(pppufile,'output.ppu');
  4290.   ppufile.create;
  4291.  
  4292. After that you can simply write all needed entries. You'll have to take care that
  4293. you write at least the basic entries for the sections:
  4294.  
  4295.   ibendinterface
  4296.   ibenddefs
  4297.   ibendsyms
  4298.   ibendbrowser (only when you've set uf_has_browser!)
  4299.   ibendimplementation
  4300.   ibend
  4301.  
  4302.                                           75
  4303.  
  4304.  
  4305.  
  4306. APPENDIX A. ANATOMY OF A UNIT FILE                      A.5. CREATING PPUFILES
  4307.  
  4308.  
  4309. Writing an entry is a little di erent than reading it. You need to first put everything
  4310. in the entry with ppufile.putxxx:
  4311.  
  4312. procedure putdata(var b;len:longint);
  4313. procedure putbyte(b:byte);
  4314. procedure putword(w:word);
  4315. procedure putlongint(l:longint);
  4316. procedure putreal(d:ppureal);
  4317. procedure putstring(s:string);
  4318.  
  4319. After putting all the things in the entry you need to call ppufile.writeentry(ibnr:byte)
  4320. where ibnr is the entry number you're writing.
  4321. At the end of the file you need to call ppufile.writeheader to write the new
  4322. header to the file. This takes automatically care of the new size of the ppufile.
  4323. When that is also done you can call ppufile.close and dispose the object.
  4324. Extra functions/variables available for writing are:
  4325.  
  4326. ppufile.NewHeader;
  4327. ppufile.NewEntry;
  4328.  
  4329. This will give you a clean header or entry. Normally called automatically in
  4330. ppufile.writeentry, so you can't forget it.
  4331.  
  4332. ppufile.flush;
  4333.  
  4334. to flush the current bu ers to the disk
  4335.  
  4336. ppufile.do_crc:boolean;
  4337.  
  4338. set to false if you don't want that the crc is updated, this is necessary if you write
  4339. for example the browser data.
  4340.  
  4341.  
  4342.  
  4343.  
  4344.  
  4345.  
  4346.  
  4347.  
  4348.  
  4349.  
  4350.  
  4351.  
  4352.  
  4353.  
  4354.  
  4355.  
  4356.  
  4357.  
  4358.  
  4359.  
  4360.  
  4361.  
  4362.                                            76
  4363.  
  4364.  
  4365.  
  4366. Appendix B
  4367.  
  4368. Compiler and RTL source
  4369. tree structure
  4370.  
  4371. B.1 The compiler source tree
  4372.  
  4373. All compiler source files are in one directory, normally in source/compiler. For more
  4374. informations about the structure of the compiler have a look at the Compiler Manual
  4375. which contains also some informations about compiler internals.
  4376. The compiler directory contains a subdirectory utils, which contains mainly the
  4377. utilities for creation and maintainance of the message files.
  4378.  
  4379.  
  4380. B.2 The RTL source tree
  4381.  
  4382. The RTL source tree is divided in many subdirectories, but is very structured and
  4383. easy to understand. It mainly consists of three parts:
  4384.  
  4385.   1. A OS-dependent directory. This contains the files that are di erent for each
  4386.      operating system. When compiling the RTL, you should do it here. The
  4387.      following directories exist:
  4388.  
  4389.         * atari for the atari. Not maintained any more.
  4390.         * amiga for the amiga. Not maintained any more.
  4391.         * go32v1 For dos, using the GO32v1 extender. Not maintained any more.
  4392.         * go32v2 For dos, using the GO32v2 extender.
  4393.         * linux for linux platforms. It has two subdirect
  4394.         * os2 for os/2.
  4395.         * win32 for Win32 platforms.
  4396.  
  4397.   2. A processor dependent directory. This contains files that are system indepen-
  4398.      dent, but processor dependent. It contains mostly optimized routines for a
  4399.      specific processor. The following directories exist:
  4400.  
  4401.         * i386 for the Intel series of processors.
  4402.         * m68k for the motorola m68000 series of processors.
  4403.  
  4404.  
  4405.                                          77
  4406.  
  4407.  
  4408.  
  4409. APPENDIX B. COMPILER AND RTL SOURCE TREE
  4410.                                                B.2.       STR
  4411.                                                        THE R UCTURE
  4412.                                                              TL SOURCE TREE
  4413.  
  4414.  
  4415.  3. An OS-independent and Processor independent directory: inc. This contains
  4416.    complete units, and include files containing interface parts of units.
  4417.  
  4418.  
  4419.  
  4420.  
  4421.  
  4422.  
  4423.  
  4424.  
  4425.  
  4426.  
  4427.  
  4428.  
  4429.  
  4430.  
  4431.  
  4432.  
  4433.  
  4434.  
  4435.  
  4436.  
  4437.  
  4438.  
  4439.  
  4440.  
  4441.  
  4442.  
  4443.  
  4444.  
  4445.  
  4446.  
  4447.  
  4448.  
  4449.  
  4450.  
  4451.  
  4452.  
  4453.  
  4454.  
  4455.  
  4456.  
  4457.  
  4458.  
  4459.  
  4460.  
  4461.  
  4462.  
  4463.  
  4464.  
  4465.  
  4466.                                       78
  4467.  
  4468.  
  4469.  
  4470. Appendix C
  4471.  
  4472. Compiler limits
  4473.  
  4474. Although many of the restrictions imposed by the MS-DOS system are removed
  4475. by use of an extender, or use of another operating system, there still are some
  4476. limitations to the compiler:
  4477.  
  4478.   1. Procedure or Function definitions can be nested to a level of 32.
  4479.  
  4480.   2. Maximally 255 units can be used in a program when using the real-mode
  4481.      compiler (i.e. a binary that was compiled by Borland Pascal). When using
  4482.      the 32-bit compiler, the limit is set to 1024. You can change this by redefining
  4483.      the maxunits constant in the files.pas compiler source file.
  4484.  
  4485.  
  4486.  
  4487.  
  4488.  
  4489.  
  4490.  
  4491.  
  4492.  
  4493.  
  4494.  
  4495.  
  4496.  
  4497.  
  4498.  
  4499.  
  4500.  
  4501.  
  4502.  
  4503.  
  4504.  
  4505.  
  4506.  
  4507.  
  4508.  
  4509.  
  4510.  
  4511.  
  4512.                                         79
  4513.  
  4514.  
  4515.  
  4516. Appendix D
  4517.  
  4518. Compiler modes
  4519.  
  4520. Here we list the exact e ect of the di erent compiler modes. They can be set with
  4521. the $Mode switch, or by command line switches.
  4522.  
  4523.  
  4524. D.1 FPC mode
  4525.  
  4526. This mode is selected by the $MODE FPC switch. On the command-line, this means
  4527. that you use none of the other compatibility mode switches. It is the default mode
  4528. of the compiler. This means essentially:
  4529.  
  4530.   1. You must use the address operator to assign procedural variables.
  4531.  
  4532.   2. A forward declaration must be repeated exactly the same by the implementa-
  4533.      tion of a function/procedure. In particular, you can not omit the parameters
  4534.      when implementing the function or procedure.
  4535.  
  4536.   3. Overloading of functions is allowed.
  4537.  
  4538.   4. Nested comments are allowed.
  4539.  
  4540.   5. The Objpas unit is NOT loaded.
  4541.  
  4542.   6. You can use the cvar type.
  4543.  
  4544.   7. PChars are converted to strings automatically.
  4545.  
  4546.  
  4547. D.2 TP mode
  4548.  
  4549. This mode is selected by the $MODE TP switch. On the command-line, this mode is
  4550. selected by the -So switch.
  4551.  
  4552.   1. You cannot use the address operator to assign procedural variables.
  4553.  
  4554.   2. A forward declaration must not be repeated exactly the same by the imple-
  4555.      mentation of a function/procedure. In particular, you can omit the parameters
  4556.      when implementing the function or procedure.
  4557.  
  4558.   3. Overloading of functions is not allowed.
  4559.  
  4560.   4. The Objpas unit is NOT loaded.
  4561.  
  4562.                                             80
  4563.  
  4564.  
  4565.  
  4566. APPENDIX D. COMPILER MODES                                 D.3. DELPHI MODE
  4567.  
  4568.  
  4569.   5. Nested comments are not allowed.
  4570.  
  4571.   6. You can not use the cvar type.
  4572.  
  4573.  
  4574. D.3 Delphi mode
  4575.  
  4576. This mode is selected by the $MODE DELPHI switch. On the command-line, this
  4577. mode is selected by the -Sd switch.
  4578.  
  4579.   1. You can not use the address operator to assign procedural variables.
  4580.  
  4581.   2. A forward declaration must not be repeated exactly the same by the im-
  4582.      plementation of a function/procedure. In particular, you can not omit the
  4583.      parameters when implementing the function or procedure.
  4584.  
  4585.   3. Overloading of functions is not allowed.
  4586.  
  4587.   4. Nested comments are not allowed.
  4588.  
  4589.   5. The Objpas unit is loaded right after the system unit. One of the consequences
  4590.      of this is that the type Integer is redefined as Longint.
  4591.  
  4592.  
  4593. D.4 GPC mode
  4594.  
  4595. This mode is selected by the $MODE GPC switch. On the command-line, this mode
  4596. is selected by the -Sp switch.
  4597.  
  4598.   1. You must use the address operator to assign procedural variables.
  4599.  
  4600.   2. A forward declaration must not be repeated exactly the same by the imple-
  4601.      mentation of a function/procedure. In particular, you can omit the parameters
  4602.      when implementing the function or procedure.
  4603.  
  4604.   3. Overloading of functions is not allowed.
  4605.  
  4606.   4. The Objpas unit is NOT loaded.
  4607.  
  4608.   5. Nested comments are not allowed.
  4609.  
  4610.   6. You can not use the cvar type.
  4611.  
  4612.  
  4613. D.5 OBJFPC mode
  4614.  
  4615. This mode is selected by the $MODE OBJFPC switch. On the command-line, this
  4616. mode is selected by the -S2 switch.
  4617.  
  4618.   1. You must use the address operator to assign procedural variables.
  4619.  
  4620.   2. A forward declaration must be repeated exactly the same by the implementa-
  4621.      tion of a function/procedure. In particular, you can not omit the parameters
  4622.      when implementing the function or procedure.
  4623.  
  4624.   3. Overloading of functions is allowed.
  4625.  
  4626.   4. Nested comments are allowed.
  4627.  
  4628.                                          81
  4629.  
  4630.  
  4631.  
  4632. APPENDIX D. COMPILER MODES                                D.5. OBJFPC MODE
  4633.  
  4634.  
  4635.  5. The Objpas unit is loaded right after the system unit. One of the consequences
  4636.    of this is that the type Integer is redefined as Longint.
  4637.  
  4638.  6. You can use the cvar type.
  4639.  
  4640.  7. PChars are converted to strings automatically.
  4641.  
  4642.  
  4643.  
  4644.  
  4645.  
  4646.  
  4647.  
  4648.  
  4649.  
  4650.  
  4651.  
  4652.  
  4653.  
  4654.  
  4655.  
  4656.  
  4657.  
  4658.  
  4659.  
  4660.  
  4661.  
  4662.  
  4663.  
  4664.  
  4665.  
  4666.  
  4667.  
  4668.  
  4669.  
  4670.  
  4671.  
  4672.  
  4673.  
  4674.  
  4675.  
  4676.  
  4677.  
  4678.  
  4679.  
  4680.  
  4681.  
  4682.  
  4683.  
  4684.  
  4685.  
  4686.  
  4687.                                       82
  4688.  
  4689.  
  4690.  
  4691. Appendix E
  4692.  
  4693. Using makefile.fpc
  4694.  
  4695. E.1 Introduction
  4696.  
  4697. Free Pascal comes with a special makefile, makefile.fpc, which can be included in any
  4698. makefile you use to compile with Free Pascal. There is a template Makefile provided
  4699. also. All sources from the Free Pascal team are compiled with this system.
  4700. These files are installed in the following directories:
  4701.  
  4702. linux
  4703.  
  4704. Dos or Windows
  4705.  
  4706. The template Makefile searches for the makefile.fpc in the following places :
  4707.  
  4708.   1. The file pointed to by the FPCMAKE environment variable.
  4709.  
  4710.   2. The directory pointed to by the FPCDIR envinonment variable.
  4711.  
  4712.   3. The directory pointed to by the DEFAULTFPCDIR make variable.
  4713.  
  4714.   4. The current directory.
  4715.  
  4716. Thus, setting FPCMAKE or FPCDIR as an environment string will ensure that make-
  4717. file.fpc is always found, and will be read by all makefiles, derived from the template.
  4718. The following sections explain what variables are set by makefile.fpc, what vari-
  4719. ables it expects to be set, and what targets it defines. After that, some settings in
  4720. the template makefile are explained.
  4721.  
  4722.  
  4723. E.2 Programs needed to use the makefile
  4724.  
  4725. The following programs are needed by the makefile to function correctly:
  4726.  
  4727. cp a copy program.
  4728.  
  4729. date a program that prints the date.
  4730.  
  4731. install a program to install files.
  4732.  
  4733. make the make program, obviously.
  4734.  
  4735.                                           83
  4736.  
  4737.  
  4738.  
  4739. APPENDIX E. USING MAKEFILE.FPC
  4740.                                       E.3. VARIABLES USED BY MAKEFILE.FPC
  4741.  
  4742.  
  4743. pwd a program that prints the current working directory.
  4744.  
  4745. rm a program to delete files.
  4746.  
  4747. These are standard programs on linux systems, with the possible exception of make.
  4748. For dos or Windows NT, they can be found in the file gnuutils.zip on the Free
  4749. Pascal FTP site.
  4750.  
  4751.  
  4752. E.3 Variables used by makefile.fpc
  4753.  
  4754. Many variables a ect the behaviour of the makefile. The variables can be split in
  4755. several groups:
  4756.  
  4757. Required variables
  4758.  
  4759. Directory variables
  4760.  
  4761. Target variables
  4762.  
  4763. Compiler command-line variables
  4764.  
  4765. Each group will be discussed separately in the subsequent.
  4766.  
  4767.  
  4768. Required variables
  4769. In principle, the makefile.fpc only expects one variable to be set:
  4770.  
  4771. FPCDIR This is the base directory of Free Pascal sources. The makefile expects
  4772.       to find a directory rtl below this directory.
  4773.  
  4774.  
  4775. Directory variables
  4776. The first set of variables controls the directories used in the makefile:
  4777.  
  4778. INC this is a list of directories, separated by spaces, that will be added as include
  4779.       directories to the compiler command-line.
  4780.  
  4781. LIBDIR is a list of library paths, separated by spaces. Each directory in the list
  4782.       is prepended with -Fl and added to the compiler options.
  4783.  
  4784. NEEDLIBDIR is a space-separated list of library paths. Each directory in the
  4785.       list is prepended with -Fl and added to the compiler options.
  4786.  
  4787. NEEDOBJDIR is a list of object file directories, separated by spaces. Each
  4788.       directory in the list is prepended with -Fo and added to the compiler options.
  4789.  
  4790. NEEDUNITDIR is a list of unit directories, separated by spaces. Each directory
  4791.       in the list is prepended with -Fu and is added to the compiler options.
  4792.  
  4793. OBJDIR is a list of object file directories, separated by spaces, that is added to
  4794.       the object files path, i.e. Each directory in the list is prepended with -Fo.
  4795.  
  4796. OSINC this is a space-separated list of OS-dependent directories that will be added
  4797.       as include directories to the compiler command line.
  4798.  
  4799.  
  4800.                                           84
  4801.  
  4802.  
  4803.  
  4804. APPENDIX E. USING MAKEFILE.FPC
  4805.                                      E.3. VARIABLES USED BY MAKEFILE.FPC
  4806.  
  4807.  
  4808. PROCINC is a space-separated list of processor-dependent directories that will
  4809.      be added as include directories to the compiler command-line.
  4810.  
  4811. RTL If RTLDIR is not set, RTL is used to construct RTLDIR, after which RTLDIR is
  4812.      added to the compiler unit path, with -Fu prepended. If RTLDIR is not set, it
  4813.      is set to $(RTL)/$(OS TARGET).
  4814.  
  4815. RTLDIR Directory where the RTL unit sources are. If RTLDIR is not set, it is set
  4816.      to $(RTL)/$(OS TARGET).
  4817.      If RTL is also not set, it is set to $(FPCDIR)/rtl/$(OS TARGET).
  4818.  
  4819. TARGETDIR If set, this directory is added as the output directory of the com-
  4820.      piler, where all units and executables are written, i.e. it gets -FE prepended.
  4821.  
  4822. UNIT If UNITDIR is not set, UNIT is used to construct UNITDIR. UNITDIR is added
  4823.      to the compiler unit path, with -Fu prepended.
  4824.  
  4825. UNITDIR Directory where the RTL compiled units are. If UNITDIR is not set, it
  4826.      is set to $(UNIT)/$(OS TARGET).
  4827.      If UNIT is also not set, it is set to $(FPCDIR)/rtl/$(OS TARGET).
  4828.  
  4829. UNITS The content of this variable are appended to the BASEINSTALLDIR variable
  4830.      to install the units.
  4831.  
  4832. UNITTARGETDIR If set, this directory is added as the output directory of
  4833.      the compiler, where all units are written, i.e. it gets -FU prepended. This
  4834.      overrides TARGETDIR.
  4835.  
  4836.  
  4837. Target variables
  4838. The second set of variables controls the targets that are constructed by the makefile:
  4839.  
  4840. DEFAULTUNITS If defined, only units will be made by the makefile. If not
  4841.      defined, then executables are made also.
  4842.  
  4843. EXEOBJECTS This is a list of executable names that will be compiled. the
  4844.      makefile appends $(EXEEXT) to these names.
  4845.  
  4846. LOADEROBJECTS is a list of space-separated names that identify loaders to
  4847.      be compiled. This is mainly used in the compiler's RTL sources.
  4848.  
  4849. UNITOBJECTS This is a list of unit names that will be compiled. The makefile
  4850.      appends $(PPUEXT) to each of these names to form the unit file name. The
  4851.      sourcename is formed by adding $(PASEXT).
  4852.  
  4853. ZIPNAME is the name of the archive that will be created by the makefile.
  4854.  
  4855. ZIPTARGET is the target that is built before the archive is made. this target is
  4856.      built first. If successful, the zip archive will be made.
  4857.  
  4858.  
  4859. Compiler command-line variables
  4860. The following variables control the compiler command-line:
  4861.  
  4862. CFGFILE if this variable is set, it will be used as the name of the config file to
  4863.      be used by the compiler.
  4864.  
  4865.  
  4866.                                          85
  4867.  
  4868.  
  4869.  
  4870. APPENDIX E. USING MAKEFILE.FPC
  4871.                                       E.4. VARIABLES SET BY MAKEFILE.FPC
  4872.  
  4873.  
  4874. CPU the CPU type is added as a define to the compiler command line. Automat-
  4875.      ically determined by the makefile.
  4876.  
  4877. LIBNAME if smartlinking is requested (i.e. SMARTLINK is set to YES), this is the
  4878.      name of the static library to produce. Don't add lib to this, the compiler
  4879.      will do that.
  4880.  
  4881. LIBTYPE if set to shared, then the compiler will emit a shared library, with
  4882.      name LIBNAME.If LIBTYPE is set to static, the compiler will emit a static,
  4883.      smartlinked library,
  4884.  
  4885. NEEDGCCLIB if this variable is defined, then the path to libgcc is added to the
  4886.      library path.
  4887.  
  4888. NEEDOTHERLIB (linux only) If this is defined, then the makefile will append
  4889.      all directories that appear in /etc/ld.so.conf to the library path.
  4890.  
  4891. OPT Any options that you want to pass to the compiler. The contents of OPT is
  4892.      simply added to the compiler command-line.
  4893.  
  4894. OPTDEF Are optional defines, added to the command-line of the compiler. They
  4895.      do not get -d prepended.
  4896.  
  4897. OS TARGET What platform you want to compile for. Added to the compiler
  4898.      command-line with a -T prepended.
  4899.  
  4900. SMARTLINK if SMARTLINK is set to YES then the compiler will output smartlinked
  4901.      units if LIBTYPE is not set to shared.
  4902.  
  4903.  
  4904. E.4 Variables set by makefile.fpc
  4905.  
  4906. All of the following variables are only set by makefile.fpc, if they aren't already
  4907. defined. This means that you can override them by setting them on the make
  4908. command line, or setting them in the makefile you use, BEFORE makefile.fpc is
  4909. included. The following sets of variables are defined:
  4910.  
  4911. Directory variables
  4912.  
  4913. Program names
  4914.  
  4915. File extensions item[Target files]
  4916.  
  4917. Each of these sets is discussed in the subsequent:
  4918.  
  4919.  
  4920. Directory variables
  4921. The following directories are defined by the makefile:
  4922.  
  4923. BASEDIR is set to the current directory if the pwd command is available. If not,
  4924.      it is set to '.'.
  4925.  
  4926. BASEINSTALLDIR is the base for all directories where units are installed. On
  4927.      linux, this is set to $(PREFIXINSTALLDIR)/lib/fpc/$(RELEASEVER).
  4928.      On other systems, it is set to $(PREFIXINSTALLDIR)
  4929.  
  4930.  
  4931.  
  4932.                                            86
  4933.  
  4934.  
  4935.  
  4936. APPENDIX E. USING MAKEFILE.FPC
  4937.                                       E.4. VARIABLES SET BY MAKEFILE.FPC
  4938.  
  4939.  
  4940. BININSTALLDIR is set to $(BASEINSTALLDIR)/bin on linux, and
  4941.      $(BASEINSTALLDIR)/bin/$(OS TARGET) on other systems. This is the place
  4942.      where binaries are installed.
  4943.  
  4944. GCCLIBDIR (linux only) is set to the directory where libgcc.a is.
  4945.  
  4946. LIBINSTALLDIR is set to $(BASEINSTALLDIR) on linux,
  4947.      and $(BASEINSTALLDIR)/lib on other systems.
  4948.  
  4949. OTHERLIBDIR (linux only) is set to the full set of paths in /etc/ld.so.conf
  4950.  
  4951. PREFIXINSTALLDIR is set to /usr on linux, /pp on dos or Windows NT.
  4952.  
  4953. SHARED LIBINSTALLDIR is where shared libraries are installed. This equals
  4954.      $(PREFIXINSTALLDIR)/lib on linux, and SHARED UNITINSTALLDIR on other
  4955.      systems.
  4956.  
  4957. SHARED UNITINSTALLDIR is where units from libraries are installed. This
  4958.      equals $(UNITINSTALLDIR)/shared
  4959.  
  4960. STATIC LIBINSTALLDIR is where static libraries will be installed. By de-
  4961.      fault, it equals $(STATIC UNITINSTALLDIR).
  4962.  
  4963. STATIC UNITINSTALLDIR is where static, smartlinked units will be installed.
  4964.      It equals $(UNITINSTALLDIR)/static.
  4965.  
  4966. UNITINSTALLDIR is where units will be installed. This is set to
  4967.      $(BASEINSTALLDIR)/$(UNITPREFIX)
  4968.      on linux. On other systems, it is set to
  4969.      $(BASEINSTALLDIR)/$(UNITPREFIX)/$(OS TARGET).
  4970.  
  4971.  
  4972. Program names
  4973. The following variables are program names, used in makefile targets.
  4974.  
  4975. AS The assembler. Default set to as.
  4976.  
  4977. COPY a file copy program. Default set to cp -fp.
  4978.  
  4979. CMP a program to compare files. Default set to cmp.
  4980.  
  4981. DEL a file removal program. Default set to rm -f.
  4982.  
  4983. DELTREE a directory removal program. Default set to rm -rf.
  4984.  
  4985. DATE a program to display the date.
  4986.  
  4987. DIFF a program to produce di  files.
  4988.  
  4989. ECHO an echo program.
  4990.  
  4991. INSTALL a program to install files. Default set to install -m 644 on linux.
  4992.  
  4993. INSTALLEXE a program to install executable files. Default set to install -m 755
  4994.      on linux.
  4995.  
  4996. LD The linker. Default set to ld.
  4997.  
  4998. LDCONFIG (linux only) the program used to update the loader cache.
  4999.  
  5000.  
  5001.                                         87
  5002.  
  5003.  
  5004.  
  5005. APPENDIX E. USING MAKEFILE.FPC
  5006.                                       E.4. VARIABLES SET BY MAKEFILE.FPC
  5007.  
  5008.  
  5009. MKDIR a program to create directories if they don't exist yet. Default set to
  5010.      install -m 755 -d
  5011.  
  5012. MOVE a file move program. Default set to mv -f
  5013.  
  5014. PP the Free Pascal compiler executable. Default set to ppc386.exe
  5015.  
  5016. PPAS the name of the shell script created by the compiler if the -s option is
  5017.      specified. This command will be executed after compilation, if the -s option
  5018.      was detected among the options.
  5019.  
  5020. PPUMOVE the program to move units into one big unit library.
  5021.  
  5022. SED a stream-line editor program. Default set to sed.
  5023.  
  5024. UPX an executable packer to compress your executables into self-extracting com-
  5025.      pressed executables.
  5026.  
  5027. ZIPEXE a zip program to compress files. zip targets are made with this program
  5028.  
  5029.  
  5030. File extensions
  5031. The following variables denote extensions of files. These variables include the .
  5032. (dot) of the extension. They are appended to object names.
  5033.  
  5034. ASMEXT is the extension of assembler files produced by the compiler.
  5035.  
  5036. LOADEREXT is the extension of the assembler files that make up the executable
  5037.      startup code.
  5038.  
  5039. OEXT is the extension of the object files that the compiler creates.
  5040.  
  5041. PACKAGESUFFIX is a su x that is appended to package names in zip targets.
  5042.      This serves so packages can be made for di erent OSes.
  5043.  
  5044. PASEXT is the extension of pascal files used in the compile rules. It is determined
  5045.      by looking at the first EXEOBJECTS source file or the first UNITOBJECTS files.
  5046.  
  5047. PPLEXT is the extension of shared library unit files.
  5048.  
  5049. PPUEXT is the extension of default units.
  5050.  
  5051. SHAREDLIBEXT is the extension of shared libraries.
  5052.  
  5053. SMARTEXT is the extension of smartlinked unit assembler files.
  5054.  
  5055. STATICLIBEXT is the extension of static libraries.
  5056.  
  5057.  
  5058. Target files
  5059. The following variables are defined to make targets and rules easier:
  5060.  
  5061. COMPILER is the complete compiler commandline, with all options added, after
  5062.      all Makefile variables have been examined.
  5063.  
  5064. DATESTR contains the date.
  5065.  
  5066. EXEFILES is a list of executables that will be created by the makefile.
  5067.  
  5068.  
  5069.                                         88
  5070.  
  5071.  
  5072.  
  5073. APPENDIX E. USING
  5074.                    E.5. MAKEFILE.FPC
  5075.                          RULES AND TARGETS CREATED BY MAKEFILE.FPC
  5076.  
  5077.  
  5078. EXEOFILES is a list of executable object files that will be created by the makefile.
  5079.  
  5080. LOADEROFILES is a list of object files that will be made from the loader as-
  5081.      sembler files. This is mainly for use in the compiler's RTL sources.
  5082.  
  5083. UNITFILES a list of unit files that will be made. This is just the list of unit
  5084.      objects, with the correct unit extension appended.
  5085.  
  5086. UNITOFILES a list of unit object files that will be made. This is just the list of
  5087.      unit objects, with the correct object file extension appended.
  5088.  
  5089.  
  5090. E.5 Rules and targets created by makefile.fpc
  5091.  
  5092. The makefile.fpc defines a series of targets, which can be called by your own
  5093. targets. They have names that resemble default names (such as 'all', 'clean'), only
  5094. they have fpc prepended.
  5095.  
  5096.  
  5097. Pattern rules
  5098. The makefile makes the following pattern rules:
  5099.  
  5100. units how to make a pascal unit form a pascal source file.
  5101.  
  5102. executables how to make an executable from a pascal source file.
  5103.  
  5104. object file how to make an object file from an assembler file.
  5105.  
  5106.  
  5107. Build rules
  5108. The following build targets are defined:
  5109.  
  5110. fpc all target that builds all units and executables as well as loaders. If DEFAULTUNITS
  5111.      is defined, executables are excluded from the targets.
  5112.  
  5113. fpc exes target to make all executables in EXEOBJECTS.
  5114.  
  5115. fpc loaders target to make all files in LOADEROBJECTS.
  5116.  
  5117. fpc sharedlib target that makes all units as dynamic libraries.
  5118.  
  5119. fpc staticlib target that makes all units as smartlinked units.
  5120.  
  5121. fpc units target to make all units in UNITOBJECTS.
  5122.  
  5123.  
  5124. Cleaning rules
  5125. The following cleaning targets are defined:
  5126.  
  5127. fpc clean cleans all files that result when fpc all was made.
  5128.  
  5129. fpc libsclean is the same as fpc clean, but also removes any shared or dynamic
  5130.      libraries that may have been built.
  5131.  
  5132. fpc cleanall is the same as both previous target commands, but also deletes all
  5133.      object, unit and assembler files that are present.
  5134.  
  5135.  
  5136.                                             89
  5137.  
  5138.  
  5139.  
  5140. APPENDIX E. USING MAKEFILE.FPC
  5141.                                           E.6. USING THE PROVIDED TEMPLATE
  5142.  
  5143.  
  5144. archiving rules
  5145. The following archiving targets are defined:
  5146.  
  5147. fpc zipinstalladd will add to a (possibibly existing) archive file (it's name is taken
  5148.       from $(ZIPNAME).
  5149.  
  5150. fpc zipinstall is the same, only the archive is cleared first.
  5151.  
  5152. The zip is made uzing the ZIPEXE program. Under linux, a .tar.gz file is created.
  5153.  
  5154.  
  5155. Informative rules
  5156. The following targets produce information about the makefile:
  5157.  
  5158. fpc cfginfo gives general configuration information: the location of the makefile,
  5159.       the compiler version, target OS, CPU.
  5160.  
  5161. fpc dirinfo gives the directories, used by the compiler.
  5162.  
  5163. fpc info executes all other info targets.
  5164.  
  5165. fpc installinfo gives all directories where files will be installed.
  5166.  
  5167. fpc objectinfo lists all objects that will be made.
  5168.  
  5169. fpc toolsinfo lists all defined tools.
  5170.  
  5171.  
  5172. E.6 Using the provided template
  5173.  
  5174. The template makefile that comes with Free Pascal does nothing other than of-
  5175. fering you some variables to be set for the makefile.fpc. After that it loads the
  5176. makefile.fpc in the indicated places.
  5177. Finally it declares a set of default targets:
  5178.  
  5179. all calls fpc all.
  5180.  
  5181. clean calls fpc clean.
  5182.  
  5183. install calls fpc install.
  5184.  
  5185. info calls fpc info.
  5186.  
  5187. staticlib calls fpc staticlib.
  5188.  
  5189. sharedlib calls fpc sharedlib.
  5190.  
  5191. libsclean calls fpc libsclean.
  5192.  
  5193. staticinstall calls fpc staticinstall.
  5194.  
  5195. sharedinstall calls fpc sharedinstall.
  5196.  
  5197. libinstall calls fpc libinstall.
  5198.  
  5199. You can override each of these targets to suit your setup.
  5200. If you just have to compile some units and programs, you only need to set the
  5201. following variables:
  5202.  
  5203.                                             90
  5204.  
  5205.  
  5206.  
  5207. APPENDIX E. USING MAKEFILE.FPC
  5208.                                         E.6. USING THE PROVIDED TEMPLATE
  5209.  
  5210.  
  5211. UNITOBJECTS names of units you wish to be built.
  5212.  
  5213. EXEOBJECTS names of executables you wish to be built.
  5214.  
  5215. You may want to set some of the following variables:
  5216.  
  5217. INC,PROCINC or OSINC To indicate where include files can be found.
  5218.  
  5219. NEEDOPT additional options added to the compile command.
  5220.  
  5221. NEEDUNITDIR space-separated list of directories where units that you need
  5222.       are located.
  5223.  
  5224. TARGETDIR,UNITTARGETDIR where do you want executables and units
  5225.       to be written. Be aware that setting this variable may interfere with make,
  5226.       since it will not find the target files.
  5227.  
  5228. DEFAULTUNITS if you define this variable (to whatever value you want) then
  5229.       the all target will by default only make the units.
  5230.  
  5231. You may also set any of the variables that appear in the previous sections, to
  5232. override default behaviour of the makefile.
  5233. After having set these variables, you can run 'make info' to see whether all variables
  5234. are set to you satisfaction. If the makefile.fpc is not found, this command will inform
  5235. you of this.
  5236. After that, a simple 'make all' will make all units and executables.
  5237.  
  5238.  
  5239.  
  5240.  
  5241.  
  5242.  
  5243.  
  5244.  
  5245.  
  5246.  
  5247.  
  5248.  
  5249.  
  5250.  
  5251.  
  5252.  
  5253.  
  5254.  
  5255.  
  5256.  
  5257.  
  5258.  
  5259.  
  5260.  
  5261.  
  5262.  
  5263.  
  5264.  
  5265.                                             91
  5266.  
  5267.  
  5268.  
  5269. Appendix F
  5270.  
  5271. Compiling the compiler
  5272. yourself
  5273.  
  5274. F.1 Introduction
  5275.  
  5276. The Free Pascal team releases at intervals a completely prepared package, with
  5277. compiler and units all ready to use, the so-called releases. After a release, work
  5278. on the compiler continues, bugs are fixed and features are added. The Free Pascal
  5279. team doesn't make a new release whenever they change something in the compiler,
  5280. instead the sources are available for anyone to use and compile. Compiled versions
  5281. of RTL and compiler are also made daily, and put on the web.
  5282. There are, nevertheless, circumstances when you'll want to compile the compiler
  5283. yourself. For instance if you made changes to compiler code, or when you download
  5284. the compiler via CVS.
  5285. There are essentially 2 ways of recompiling the compiler: by hand, or using the
  5286. makefiles. Each of these methods will be discussed.
  5287.  
  5288.  
  5289. F.2 Before you begin
  5290.  
  5291. To compile the compiler easily, it is best to keep the following directory structure
  5292. (a base directory of /pp/src is supposed, but that may be di erent):
  5293.  
  5294. /pp/src/Makefile
  5295.         /makefile.fpc
  5296.         /rtl/linux
  5297.              /inc
  5298.              /i386
  5299.              /...
  5300.         /compiler
  5301.  
  5302. If you want to use the makefiles, you must use the above directory tree.
  5303. The compiler and rtl source are zipped in such a way that if you unzip both files in
  5304. the same directory (/pp/src in the above) the above directory tree results.
  5305. The makefile.fpc and Makefile come from the base.zip file on the ftp site. If you
  5306. compile manually, you don't need them.
  5307.  
  5308.  
  5309.                                           92
  5310.  
  5311.  
  5312.  
  5313. APPENDIX F. COMPILING THE COMPILER YOURSELF
  5314.                                                   F.3. COMPILING USING MAKE
  5315.  
  5316.  
  5317. There are 2 ways to start compiling the compiler and RTL. Both ways must be
  5318. used, depending on the situation. Usually, the RTL must be compiled first, before
  5319. compiling the compiler, after which the compiler is compiled using the current com-
  5320. piler. In some special cases the compiler must be compiled first, with a previously
  5321. compiled RTL.
  5322. How to decide which should be compiled first? In general, the answer is that you
  5323. should compile the RTL first. There are 2 exceptions to this rule:
  5324.  
  5325.   1. The first case is when some of the internal routines in the RTL have changed,
  5326.      or if new internal routines appeared. Since the OLD compiler doesn't know
  5327.      about these changed internal routines, it will emit function calls that are based
  5328.      on the old compiled RTL, and hence are not correct. Either the result will
  5329.      not link, or the binary will give errors.
  5330.   2. The second case is when something is added to the RTL that the compiler
  5331.      needs to know about (a new default assembler mechanism, for example).
  5332.  
  5333. How to know if one of these things has occurred ? There is no way to know, except
  5334. by mailing the Free Pascal team. If you cannot recompile the compiler when you
  5335. first compile the RTL, then try the other way.
  5336.  
  5337.  
  5338. F.3 Compiling using make
  5339.  
  5340. When compiling with make it is necessary to have the above directory structure.
  5341. Compiling the compiler is achieved with the target cycle.
  5342. Under normal circumstances, recompiling the compiler is limited to the following
  5343. instructions (assuming you start in directory /pp/src):
  5344.  
  5345. cd compiler
  5346. make cycle
  5347.  
  5348. This will work only if the makefile.fpc is installed correctly and if the needed tools
  5349. are present in the PATH. Which tools must be installed can be found in appendix E.
  5350. The above instructions will do the following:
  5351.  
  5352.   1. Using the current compiler, the RTL is compiled in the correct directory,
  5353.      which is determined by the OS you are under. e.g. under linux, the RTL is
  5354.      compiled in directory rtl/linux.
  5355.   2. The compiler is compiled using the newly compiled RTL. If successful, the
  5356.      newly compiled compiler executable is copied to a temporary executable.
  5357.   3. Using the temporary executable from the previous step, the RTL is re-compiled.
  5358.   4. Using the temporary executable and the newly compiled RTL from the last
  5359.      step, the compiler is compiled again.
  5360.  
  5361. The last two steps are repeated 3 times, until three passes have been made or until
  5362. the generated compiler binary is equal to the binary it was compiled with. This
  5363. process ensures that the compiler binary is correct.
  5364. Compiling for another target: When you want to compile the compiler for another
  5365. target, you must specify the OS TARGET makefile variable. It can be set to the
  5366. following values: win32, go32v2, os2 and linux. As an example, cross-compilation
  5367. for the go32v2 target from the win32 target is chosen:
  5368.  
  5369.                                          93
  5370.  
  5371.  
  5372.  
  5373.   APPENDIX F. COMPILING THE COMPILER YOURSELF
  5374.                                                          F.4. COMPILING BY HAND
  5375.  
  5376.  
  5377.   cd compiler
  5378.   make cycle OS_TARGET=go32v2
  5379.  
  5380.   This will compile the go32v2 RTL, and compile a go32v2 compiler.
  5381.   If you want to compile a new compiler, but you want the compiler to be compiled
  5382.   first using an existing compiled RTL, you should specify the all target, and specify
  5383.   another RTL directory than the default (which is the ../rtl/$(OS TARGET) direc-
  5384.   tory). For instance, assuming that the compiled RTL units are in /pp/rtl, you
  5385.   could type
  5386.  
  5387.   cd compiler
  5388.   make clean
  5389.   make all UNITDIR=/pp/rtl
  5390.  
  5391.   This will then compile the compiler using the RTL units in /pp/rtl. After this has
  5392.   been done, you can do the 'make cycle', starting with this compiler:
  5393.  
  5394.   make cycle PP=./ppc386
  5395.  
  5396.   This will do the make cycle from above, but will start with the compiler that was
  5397.   generated by the make all instruction.
  5398.   In all cases, many options can be passed to make to influence the compile process.
  5399.   In general, the makefiles add any needed compiler options to the command-line, so
  5400.   that the RTL and compiler can be compiled. You can specify additional options
  5401.   (e.g. optimization options) by passing them in OPT.
  5402.  
  5403.  
  5404.   F.4 Compiling by hand
  5405.  
  5406.   Compiling by hand is di cult and tedious, but can be done. We'll treat the com-
  5407.   pilation of RTL and compiler separately.
  5408.  
  5409.  
  5410.   Compiling the RTL
  5411.   To recompile the RTL, so a new compiler can be built, at least the following units
  5412.   must be built, in the order specified:
  5413.  
  5414. loaders the program stubs, that are the startup code for each pascal program. These
  5415.        files have the .as extension, because they are written in assembler. They must
  5416.        be assembled with the gnu as assembler. These stubs are in the OS-dependent
  5417.        directory, except for linux, where they are in a processor dependent subdi-
  5418.        rectory of the linux directory (i386 or m68k).
  5419.  
  5420. system the system unit. This unit is named di erently on di erent systems:
  5421.  
  5422.           * Only on GO32v2, it's called system.
  5423.           * For linux it's called syslinux.
  5424.           * For Windows NT it's called syswin32.
  5425.           * For os/2 it's called sysos2
  5426.  
  5427.        This unit resides in the OS-dependent subdirectories of the RTL.
  5428.  
  5429. strings The strings unit. This unit resides in the inc subdirectory of the RTL.
  5430.  
  5431.                                                94
  5432.  
  5433.  
  5434.  
  5435.   APPENDIX F. COMPILING THE COMPILER YOURSELF
  5436.                                                        F.4. COMPILING BY HAND
  5437.  
  5438.  
  5439.    dos The dos unit. It resides in the OS-dependent subdirectory of the RTL. Possibly
  5440.         other units will be compiled as a consequence of trying to compile this unit
  5441.         (e.g. on linux, the linux unit will be compiled, on go32, the go32 unit will be
  5442.         compiled).
  5443.  
  5444. objects the objects unit. It resides in the inc subdirectory of the RTL.
  5445.  
  5446.   To compile these units on a i386, the following statements will do:
  5447.  
  5448.   ppc386 -Tlinux -b- -Fi../inc -Fi../i386 -FE. -di386 -Us -Sg syslinux.pp
  5449.   ppc386 -Tlinux -b- -Fi../inc -Fi../i386 -FE. -di386 ../inc/strings.pp
  5450.   ppc386 -Tlinux -b- -Fi../inc -Fi../i386 -FE. -di386 dos.pp
  5451.   ppc386 -Tlinux -b- -Fi../inc -Fi../i386 -FE. -di386 ../inc/objects.pp
  5452.  
  5453.   These are the minimum command-line options, needed to compile the RTL.
  5454.   For another processor, you should change the i386 into the appropriate proces-
  5455.   sor. For another operating system (target) you should change the syslinux in the
  5456.   appropriate system unit file, and you should change the target OS setting (-T).
  5457.   Depending on the target OS there are other units that you may wish to compile,
  5458.   but which are not strictly needed to recompile the compiler. The following units
  5459.   are available for all plaforms:
  5460.  
  5461.   objpas Needed for Delphi mode. Needs -S2 as an option. Resides in the objpas
  5462.         subdirectory.
  5463.  
  5464.   sysutils many utility functions, like in Delphi. Resides in the objpas directory, and
  5465.         needs -S2 to compile.
  5466.  
  5467.   typinfo functions to access RTTI information, like Delphi. Resides in the objpas
  5468.         directory.
  5469.  
  5470.   math math functions like in Delphi. Resides in the objpas directory.
  5471.  
  5472.   mmx extensions for MMX class Intel processors. Resides in in the i386 directory.
  5473.  
  5474.   getopts a GNU compatible getopts unit. resides in the inc directory.
  5475.  
  5476.   heaptrc to debug the heap. resides in the inc directory.
  5477.  
  5478.  
  5479.   Compiling the compiler
  5480.   Compiling the compiler can be done with one statement. It's always best to remove
  5481.   all units from the compiler directory first, so something like
  5482.  
  5483.   rm *.ppu *.o
  5484.  
  5485.   on linux, and on dos
  5486.  
  5487.   del *.ppu
  5488.   del *.o
  5489.  
  5490.   After this, the compiler can be compiled with the following command-line:
  5491.  
  5492.   ppc386 -Tlinux -Fu../rtl/linux -di386 -dGDB pp.pas
  5493.  
  5494.   So, the minimum options are:
  5495.  
  5496.                                            95
  5497.  
  5498.  
  5499.  
  5500. APPENDIX F. COMPILING THE COMPILER YOURSELF
  5501.                                                            F.4. COMPILING BY HAND
  5502.  
  5503.  
  5504.  
  5505.                     Table F.1: Possible defines when compiling FPC
  5506.  
  5507.  Define                   does what
  5508.  USE RHIDE                Generates errors and warnings in a format recognized
  5509.                           by RHIDE.
  5510.  TP                       Needed to compile the compiler with Turbo or Borland Pascal.
  5511.  Delphi                   Needed to compile the compiler with Delphi from Borland.
  5512.  GDB                      Support of the GNU Debugger.
  5513.  I386                     Generate a compiler for the Intel i386+ processor family.
  5514.  M68K                     Generate a compiler for the M68000 processor family.
  5515.  USEOVERLAY               Compiles a TP version which uses overlays.
  5516.  EXTDEBUG                 Some extra debug code is executed.
  5517.  SUPPORT MMX only i386: enables the compiler switch MMX which
  5518.                           allows the compiler to generate MMX instructions.
  5519.  EXTERN MSG               Don't compile the msgfiles in the compiler, always use
  5520.                           external messagefiles (default for TP).
  5521.  NOAG386INT               no Intel Assembler output.
  5522.  NOAG386NSM               no NASM output.
  5523.  NOAG386BIN               leaves out the binary writer.
  5524.  
  5525.  
  5526.    1. The target OS. Can be skipped if you're compiling for the same target as the
  5527.          compiler you're using.
  5528.  
  5529.    2. A path to an RTL. Can be skipped if a correct ppc386.cfg configuration is on
  5530.          your system. If you want to compile with the RTL you compiled first, this
  5531.          should be ../rtl/OS (replace the OS with the appropriate operating system
  5532.          subdirectory of the RTL).
  5533.  
  5534.    3. A define with the processor you're compiling for. Required.
  5535.  
  5536.    4. -dGDB is not strictly needed, but is better to add since otherwise you won't
  5537.          be able to compile with debug information.
  5538.  
  5539.    5. -Sg is needed, some parts of the compiler use goto statements (to be specific:
  5540.          the scanner).
  5541.  
  5542. So the absolute minimal command line is
  5543.  
  5544. ppc386 -di386 -Sg pp.pas
  5545.  
  5546. You can define some other command-line options, but the above are the minimum.
  5547. A list of recognised options can be found in table (F.1).
  5548. This list may be subject to change, the source file pp.pas always contains an up-to-
  5549. date list.
  5550.  
  5551.  
  5552.  
  5553.  
  5554.  
  5555.  
  5556.  
  5557.  
  5558.  
  5559.                                              96
  5560.  
  5561.  
  5562.  
  5563.