Free Pascal : User’s Guide User’s Guide for Free Pascal, Version 2.4.2 Document version 2.4 November 2010 Michaël Van Canneyt Florian Klämpfl Contents 1 Introduction7 1.1 About this document..................................7 1.2 About the compiler...................................7 1.3 Getting more information................................8 2 Installing the compiler 10 2.1 Before Installation : Requirements........................... 10 2.1.1 Hardware requirements............................. 10 2.1.2 Software requirements............................. 10 Under DOS................................... 10 Under UNIX.................................. 10 Under Windows................................ 11 Under OS/2................................... 11 Under Mac OS X................................ 11 2.2 Installing the compiler.................................. 11 2.2.1 Installing under Windows........................... 11 2.2.2 Installing under DOS or OS/2......................... 11 Mandatory installation steps........................... 11 Optional Installation: The coprocessor emulation............... 13 2.2.3 Installing under Linux............................. 13 Mandatory installation steps........................... 13 2.3 Optional configuration steps.............................. 14 2.4 Before compiling.................................... 15 2.5 Testing the compiler.................................. 15 3 Compiler usage 16 3.1 File searching...................................... 16 3.1.1 Command line files............................... 16 3.1.2 Unit files.................................... 16 3.1.3 Include files................................... 19 3.1.4 Object files................................... 19 1 CONTENTS 3.1.5 Configuration file................................ 20 3.1.6 About long filenames.............................. 20 3.2 Compiling a program.................................. 20 3.3 Compiling a unit.................................... 21 3.4 Units, libraries and smartlinking............................ 21 3.5 Reducing the size of your program........................... 21 4 Compiling problems 23 4.1 General problems.................................... 23 4.2 Problems you may encounter under DOS....................... 23 5 Compiler configuration 24 5.1 Using the command line options............................ 24 5.1.1 General options................................. 24 5.1.2 Options for getting feedback.......................... 25 5.1.3 Options concerning files and directories.................... 26 5.1.4 Options controlling the kind of output...................... 27 5.1.5 Options concerning the sources (language options).............. 31 5.2 Using the configuration file............................... 33 5.2.1 #IFDEF..................................... 34 5.2.2 #IFNDEF.................................... 34 5.2.3 #ELSE..................................... 34 5.2.4 #ENDIF..................................... 35 5.2.5 #DEFINE.................................... 35 5.2.6 #UNDEF.................................... 35 5.2.7 #WRITE.................................... 35 5.2.8 #INCLUDE................................... 36 5.2.9 #SECTION................................... 36 5.3 Variable substitution in paths.............................. 36 6 The IDE 38 6.1 First steps with the IDE................................. 38 6.1.1 Starting the IDE................................ 38 6.1.2 IDE command line options........................... 38 6.1.3 The IDE screen................................. 39 6.2 Navigating in the IDE.................................. 40 6.2.1 Using the keyboard............................... 40 6.2.2 Using the mouse................................ 40 6.2.3 Navigating in dialogs.............................. 41 6.3 Windows........................................ 41 6.3.1 Window basics................................. 41 2 CONTENTS 6.3.2 Sizing and moving windows.......................... 42 6.3.3 Working with multiple windows........................ 43 6.3.4 Dialog windows................................ 43 6.4 The Menu........................................ 43 6.4.1 Accessing the menu.............................. 43 6.4.2 The File menu................................. 44 6.4.3 The Edit menu................................. 45 6.4.4 The Search menu................................ 46 6.4.5 The Run menu................................. 46 6.4.6 The Compile menu............................... 47 6.4.7 The Debug menu................................ 47 6.4.8 The Tools menu................................. 48 6.4.9 The Options menu............................... 48 6.4.10 The Window menu............................... 49 6.4.11 The Help menu................................. 50 6.5 Editing text....................................... 50 6.5.1 Insert modes.................................. 50 6.5.2 Blocks..................................... 50 6.5.3 Setting bookmarks............................... 51 6.5.4 Jumping to a source line............................ 51 6.5.5 Syntax highlighting............................... 52 6.5.6 Code Completion................................ 52 6.5.7 Code Templates................................. 53 6.6 Searching and replacing................................. 54 6.7 The symbol browser................................... 56 6.8 Running programs................................... 57 6.9 Debugging programs.................................. 58 6.9.1 Using breakpoints............................... 58 6.9.2 Using watches................................. 60 6.9.3 The call stack.................................. 61 6.9.4 The GDB window............................... 61 6.10 Using Tools....................................... 62 6.10.1 The messages window............................. 62 6.10.2 Grep....................................... 63 6.10.3 The ASCII table................................ 63 6.10.4 The calculator.................................. 64 6.10.5 Adding new tools................................ 65 6.10.6 Meta parameters................................ 66 6.10.7 Building a command line dialog box...................... 68 6.11 Project management and compiler options....................... 70 3 CONTENTS 6.11.1 The primary file................................. 70 6.11.2 The directory dialog.............................. 71 6.11.3 The target operating system.......................... 71 6.11.4 Compiler options................................ 72 6.11.5 Linker options................................. 77 6.11.6 Memory sizes.................................. 78 6.11.7 Debug options................................. 79 6.11.8 The switches mode............................... 80 6.12 Customizing the IDE.................................. 80 6.12.1 Preferences................................... 81 6.12.2 The desktop................................... 82 6.12.3 The Editor................................... 83 6.12.4 Keyboard & Mouse............................... 85 6.13 The help system..................................... 86 6.13.1 Navigating in the help system......................... 86 6.13.2 Working with help files............................. 86 6.13.3 The about dialog................................ 87 6.14 Keyboard shortcuts................................... 88 7 Porting and portable code 92 7.1 Free Pascal compiler modes.............................. 92 7.2 Turbo Pascal....................................... 93 7.2.1 Things that will not work............................ 93 7.2.2 Things which are extra............................. 94 7.2.3 Turbo Pascal compatibility mode........................ 96 7.2.4 A note on long file names under DOS ..................... 98 7.3 Porting Delphi code................................... 98 7.3.1 Missing language constructs.......................... 98 7.3.2 Missing calls / API incompatibilities...................... 99 7.3.3 Delphi compatibility mode........................... 100 7.3.4 Best practices for porting............................ 100 7.4 Writing portable code.................................. 100 8 Utilities that come with Free Pascal 103 8.1 Demo programs and examples............................. 103 8.2 fpcmake......................................... 103 8.3 fpdoc - Pascal Unit documenter............................. 103 8.4 h2pas - C header to Pascal Unit converter....................... 104 8.4.1 Options..................................... 104 8.4.2 Constructs................................... 104 8.5 h2paspp - preprocessor for h2pas............................ 106 4 CONTENTS 8.5.1 Usage...................................... 106 8.5.2 Options..................................... 106 8.6 ppudump program.................................... 106 8.7 ppumove program.................................... 107 8.8 ptop - Pascal source beautifier............................. 108 8.8.1 ptop program.................................. 108 8.8.2 The ptop configuration file........................... 109 8.8.3 ptopu unit.................................... 110 8.9 rstconv program..................................... 111 8.10 unitdiff program..................................... 112 8.10.1 Synopsis.................................... 112 8.10.2 Description and usage............................. 112 8.10.3 Options..................................... 112 9 Units that come with Free Pascal 114 9.1 Standard units...................................... 114 9.2 Under DOS....................................... 115 9.3 Under Windows....................................