Knowledge base

This document gives last minute information regarding the compiler.
Furthermore, it answers frequently asked questions and gives solutions to
common problems found with Free Pascal. The information presented herein
always supersedes those found in the Free Pascal documentation.

For more comprehensive information on the pascal language, and the runtime
library calls, consult the Free Pascal manuals. Topics covered in this
document :

  1. General information
       1. What is Free Pascal (FPC)?
       2. Which versions exist, and which one should I use?
       3. Free Pascal and GNU Pascal - a comparison
       4. License and copyright information
       5. Getting the compiler
       6. Free Pascal installation hints
       7. Why do i have to supply a user name and password to get Free
          Pascal ?
       8. Access denied error when connecting to the Free Pascal FTP site
       9. Where can I find a text mode IDE?
      10. I want a new version NOW
      11. Installing a snapshot
      12. Known bugs / Reporting bugs
      13. I have to write a program for homework. Can you help?
      14. Getting more information when an application crashes
      15. Increasing the heap size
      16. Compiler seems to skip files in directories -Fu points to
      17. Why are the generated binaries so big?
      18. Configuration file problems (fpc.cfg or ppc386.cfg)
      19. Runtime errors
      20. Standard units
      21. How does the compiler work internally?
      22. Debugging smartlinked code does not fully work
      23. Debugging shared library (dynamic linked library) code does not
          fully work
      24. PPU files binary compatibility between versions
      25. Can't compile a program using a binary only version of a unit
  2. Pascal language related information
       1. Considerations in porting code to other processors
       2. Considerations in porting code to other operating systems
       3. Compiling Delphi code using Free Pascal
       4. Building a unit
       5. Compiling the system unit
       6. How does function overloading work?
       7. Calling C functions
       8. Integrated Assembler syntax
       9. Unit system, syslinux, sysos2 or syswin32 not found errors
  3. Runtime library related information
       1. Using the graph unit with Free Pascal
       2. Why do I get wrong colors when using the graph unit?
       3. File sharing and file locks
       4. Accessing huge files using standard I/O routines
       5. File denied errors when opening files with reset
       6. Turbo Vision libraries
  4. DOS related information
       1. Releasing software generated by the DOS compiler
       2. Debugging
       3. Dynamic libraries
       4. Profiling
       5. Running Free Pascal without a math coprocessor
       6. Applications created with Free Pascal crash on 80386 systems
       7. The mouse cursor is not visible in graphics screens
       8. Accessing I/O ports
       9. Accessing DOS memory / Doing graphics programming
      10. Changing the default stack size
      11. Using OS/2 generated applications under DOS
  5. Windows related information
       1. Releasing software generated by the windows compiler
       2. Debugging
       3. Dynamic libraries
       4. Profiling
       5. Graph and problems with keyboard, mouse and "dummy dos windows"
       6. Makefile problems on Win2000 (and NT)
       7. Using the DOS compiler under Windows 95
       8. Using OS/2 generated applications under Windows
       9. Using DOS generated applications under windows
      10. The mouse cursor does not respond in the Windows IDE
      11. INSTALL.EXE of version 1.0.6 returns errors under some version of
          Windows
  6. UNIX related information
       1. Releasing software generated by the unix compilers
       2. Debugging
       3. Dynamic libraries
       4. Profiling
       5. Why can't the linker find "vga"?
       6. Compiler indicates missing as and ld
  7. OS/2 related information
       1. Releasing software generated by the OS/2 compiler
       2. Debugging
       3. Dynamic libraries
       4. Profiling
       5. Using DOS generated applications under OS/2
       6. INSTALL.EXE of version 1.0.6 or below returns an unknown error
          (-1) under OS/2
          or
          INSTALL.EXE of version 1.0.6 or above complains about missing TZ
          variable under OS/2
  8. BeOS related information
       1. Releasing software generated by the BeOS compiler
       2. Debugging
       3. Dynamic libraries
       4. Profiling
  9. Amiga related information
       1. Releasing software generated by the Amiga compiler
       2. Debugging
       3. Dynamic libraries
       4. Profiling
 10. PalmOS related information
       1. Releasing software generated by the PalmOS compiler
       2. Debugging
       3. Dynamic libraries

  1. General information

       1. What is Free Pascal (FPC)?

          Originally named FPK-Pascal, the Free Pascal compiler is a 32 bit
          Turbo Pascal and Delphi compatible Pascal compiler for DOS,
          Linux, Win32, OS/2 and (based on an older version) the AmigaOS.
          More operating systems (BeOS and FreeBSD/ELF are in advanced
          stages of development) are in the works. A beta release for the
          PalmOS is available as well.

          The compiler is written in Pascal and is able to compile its own
          sources. The source files are included.

          Free Pascal is modest regarding its minimal system requirements
          (386-25 Mhz for the Intel version and ideally a 68020 processor
          for the Motorola version). At least 2 megabytes of RAM are
          required. To remake the compiler more than 16MB is recommended.

          Short history:
             + 06/1993: project start
             + 10/1993: first little programs work
             + 03/1995: the compiler compiles the own sources
             + 03/1996: released to the internet
             + 07/2000: 1.0 version
             + 12/2000: 1.0.4 version
             + 4/2002: 1.0.6 version
             + 7/2003: 1.0.10 version

       2. Which versions exist, and which one should I use?

          FPC's version numbering changed a few times over the years.
          Versions before 0.99.5 are considered archaic. After the release
          of 0.99.5 a system in version numbering was introduced, and that
          system was changed slightly changed after the 1.0 release.

          Versioning for versions 0.99.5 - 1.0

          Compilers with an even last number are release versions (e.g.
          0.99.8, 0.99.10, 0.99.12, 0.99.14 1.0.0)
          Compilers and packages with an odd last number are development
          versions (e.g. 0.99.9, 0.99.11, 0.99.13, 0.99.15)

          0.99.5 is an exception to this rule, since 0.99.5 IS a release (a
          release prior to the introduction of this odd/even system).

          Letters behind the version number (0.99.12b, 0.99.5d) indicate
          release versions with some bugs and problems in the original
          release (respectively 0.99.12 and 0.99.5) fixed.

          Versioning after 1.0

          Together with the release of 1.0 the version numbering has been
          slightly changed, and a system in versioning resembling the Linux
          kernel's has been introduced. The main difference is that the
          difference between a release version is now in the second number
          (1.0.x vs 1.1.x) instead of the third number (0.99.14 vs
          0.99.15), and the third number now becomes the patch level,
          replacing the postfixed letter in the old system.

             + Releases that only fix bugs in version 1.0 will be numbered
               1.0.x
             + New development (the so called snapshots) have version
               number 1.1.x. The meaning of the third version number x in
               the new development branch is not defined yet, it could be
               used for test releases or to signal major changes.
             + Eventually the 1.1.x versions, when stabilized will be
               released as version 1.2. Fixes on the 1.2 release will be
               numbered 1.2.x
             + The new development after the 1.2 release will be numbered
               1.3.x and so on
             + When really big changes are implemented, the version will be
               updated in the major number. This could be case with e.g. a
               codegenerator rewrite with support for other processors

          Normally you would want to use a release. Releases are considered
          stable, and easier to support (the bugs, quirks and unintended
          "features" are well known after a period of time, and workarounds
          exist).

          Development snapshots (which are generated daily) reflect the
          current status of the compiler. Development versions probably
          have new features and larger bugs fixed since the last release,
          but might have some temporary stability drawbacks (which are
          usually fixed by the next day).

          Development snapshots are often quite useful for certain
          categories of users. Ask in the maillists if it is worth the
          trouble in your case if you're not sure.

          We advise all users to upgrade to the newest version for their
          target. (1.0.10)

       3. Free Pascal and GNU Pascal - a comparison

          Aim:
               Free Pascal tries to implement a Borland compatible pascal
               compiler on as many platforms as possible. GNU Pascal tries
               to implement a portable pascal compiler based on POSIX.
          Version:
               Currently, Free Pascal is at version 1.0.10. GNU Pascal is at
               version 2.8.1 (but this numbering is not really an
               indication, it follows the GNU C numbering, since it is a
               derivation of it)
          Operating systems:
               Free Pascal runs on a limited number of systems : DOS,
               Win32, Linux, FreeBSD, NetBSD, OS/2, BeOS and AmigaOS and is
               for the moment limited to the Intel and Motorola
               architectures. GNU Pascal runs basically on any system that
               can run GNU C.
          Sources:
               Free Pascal is entirely written in Pascal (about 6 Mb of
               source code), while GNU Pascal is written in C (it's an
               adaptation of the GNU C compiler: 2.8 Mb code + 8 MB of GNU
               C code)
          Language:
               Free Pascal supports the Borland Pascal dialect Borland, and
               implements the Delphi Object Pascal language. GNU Pascal
               supports ISO 7185, ISO 10206, (most of) Borland Pascal 7.0
          Extensions:
               Free Pascal implements method, function and operator
               overloading. GNU Pascal implements operator overloading.
          License:
               Both compilers come under the GNU GPL.
          Author:
               Free Pascal was started by Florian Klaempfl, Germany
               (florian@freepascal.org), GNU Pascal was started by Jukka
               Virtanen, Finland (jtv@hut.fi).

       4. License and copyright information

          Applications created by the compiler and using the runtime
          library come under a modified library gnu public license (LGPL),
          which permit no restriction on the type of license the
          application has. It is therefore possible to create closed source
          or proprietary software using Free Pascal.

          The compiler source code, on the other hand, comes under the GNU
          Public license, which means that any usage of the compiler source
          can only be used in software projects which have the same
          license.

       5. Getting the compiler

          The latest official stable Free Pascal release is available for
          download from all official mirrors

       6. Free Pascal installation hints

             + Do not install the compiler in a directory which contains
               spaces in its name, since some of the compiler tools do not
               like these

       7. Why do i have to supply a user name and password to get Free
          Pascal ?

          You are trying to login in to an ftp site. You must use the login
          name: anonymous and as your password, you should put your e-mail
          address.

       8. Access denied error when connecting to the Free Pascal FTP site

          The Free Pascal main ftp site can only accept a maximum number of
          simultaneous connections. If this error occurs, it is because
          this limit has been reached. The solution is either to wait and
          retry later, or better still use one of the Free Pascal mirror
          sites.

       9. Where can I find a text mode IDE?

          The development of the IDE (integrated development environment)
          is not yet finished. However a working test version of the IDE is
          included with version 1.0.x and higher of the compiler. There
          might be problems running the DOS IDE under Windows NT and
          Windows 2000 (especially the debugger), in that case it is
          suggested to use the native Windows version.

      10. I want a new version NOW

          In the time between the release of new official versions, you can
          have a look at and test developer versions (so-called
          "snapshots"). Be warned though: this is work under progress, so
          in addition to old bugs fixed and new features added, this may
          also contain new bugs.

          Snapshots are generated automatically each night from the current
          source at that moment. Sometimes this may fail due to bigger
          changes not yet fully implemented. If your version doesn't work,
          try again one or two days later. You're advised not to download
          the GO32v1 version for Dos, since it's not supported any more.

          The latest snapshot can always be downloaded from the web page.

      11. Installing a snapshot

          To install a snapshot, extract the zip archive into the existing
          program directory of the last official version of Free Pascal
          (after making a backup of the original of course). You can also
          extract it into an empty directory and then move the files to the
          program directory, overwriting existing files.

          Make sure that you extract the ZIP archive such that the included
          directory structure remains intact. For example if you use
          PKUNZIP, use "pkunzip -d" instead of just "pkunzip". Note that
          snapshots also contain a new RTL which most likely can't be used
          with the previous release version, so backup your old RTL as
          well.

      12. Known bugs / Reporting bugs

          Go to the bugs page.

          If you wish to know the bugs for a specific Free Pascal version,
          go to the bugs page, display the bug database. At the end of the
          page you should see an option to view only specific bugs. Choose
          "With Version" with the version you want to get information about
          and "With Status" choose "Unfixed". This should display all bugs
          which are present in the specific version of the compiler you
          requested.

      13. I have to write a program for homework. Can you help?

          No. Please, don't send us mail about homework, we are no
          teachers. The Free Pascal development team tries to give good
          support for the Free Pascal compiler and are trying to always
          reply to emails. If we get emails like this, this becomes harder
          and harder.

      14. Getting more information when an application crashes

            1. The easiest possibility is to recompile your program with
               -gl debugging option. This way unit LineInfo is
               automatically linked in, and the printout after a program
               crash then contains source line numbers in addition to
               addresses of the crash. To see runtime library (RTL)
               functions in the backtrace with their real name, you have to
               recompile the RTL with -gl too.
            2. For more comprehensive checking, compile the program with
               debugging information (use the -g command line option)
            3. Load the program in the debugger

               gdb(pas)(w) --directory=<src dirs> myprog.exe

               Notes:
                  + Under UNIX systems (Linux, the BSD's), don't add the
                    ".exe" after myprog
                  + "src dirs" is a list of directories containing the
                    source code files of myprog and the units it uses
                    seperated by semi-colons (";"). The current directory
                    is automatically included.
            4. Once inside the debugger, you can (optionally) set the
               command line options that will be passed to your program
               using the command "set args <option1 option2 ...>"
            5. To start the program, type "run" and press enter
            6. After the program has crashed, the address of the
               instruction where the crash occurred will be shown. The
               debugger will try to display the source code line
               corresponding with this address. Note that this can be
               inside a procedure of the RTL, so the source may not always
               be available and most likely the RTL wasn't compiled with
               debugging information.
            7. If you then type "bt" (BackTrace), the addreses in the call
               stack will be shown (the addresses of the procedures which
               were called before the program got to the current address).
               You can see which source code lines these present using the
               command

               info line *<address>

               For example:

               info line *0x05bd8

      15. Increasing the heap size

          By default Free Pascal allocates a small part of RAM for your
          application as heap memory. If it just allocated all it could
          get, people running Windows would have problems as Windows would
          increase the swap file size to give the program more memory on
          and on, until the swap file drive would be full.

          You can specify the size of the heap with -Chxxxx.

          However, the heap size doesn't really matter, since the Heap is
          able to grow: if you've used all the available heap space, the
          program will try to get more memory from the Operating system
          (OS), so the heap is limited to the maximum amount of free memory
          provided by the OS.

          It is only handy if you know you will need at least a certain
          amount of memory. You can then specify this value using the -Ch
          parameter, so your program will allocate it at once on startup.
          This is slightly faster than growing the heap a number of times.

      16. Compiler seems to skip files in directories that -Fu points to

          This sometimes happens with installation/compilation scripts if
          the copying command doesn't preserve dates. The object files get
          older than the PPU file, and the compiler tries to recompile
          them. A simple touch will solve it.

      17. Why are the generated binaries so big?

          There are several reasons and remedies for this:

            1. You can create smartlinked applications. To turn on the
               generation of smartlinkable units, use the -Cx command line
               option when compiling your units. To turn on the linking of
               previously generated smarlinkable units, use the -XX (-XS in
               0.99.12 and earlier) command line option when compiling a
               program.

            2. Normally, all symbol information is included in the
               resulting program (for easier debugging). You can remove
               this by using the -Xs command line option when compiling
               your program (it won't do anything when compiling units)
            3. You can use UPX to pack the .EXEs (just like e.g. pklite)
               for Dos (GO32v2) and Windows targets. Look here for more
               info.
            4. You can use LXLITE for packing EMX binaries, but you won't
               be able to run them under DOS (with extender) any more then.
               It might even not be possible to use them on lower OS/2
               versions (like 2.x) depending on chosen type of compression.
               LXLITE can be found e.g. on Hobbes, search for LXLITE.
            5. Turn on optimalisations, both for supplied packages (RTL,
               FV, FCL) and for your own code, this will also decrease the
               code size.

      18. Configuration file problems (fpc.cfg or ppc386.cfg)

          Starting from version 1.0.6 of Free Pascal, the configuration
          file is now called fpc.cfg instead of ppc386.cfg. For backward
          compatibility , ppc386.cfg is still searched first and, if found,
          is used instead of fpc.cfg

          Versions prior to Free Pascal 1.0.6 do not recognize fpc.cfg, so
          if you wish to use an earlier version of the compiler using the
          same configuration file used with FPC version 1.0.6 (or later),
          the configuration file should be renamed to ppc386.cfg

          .
      19. Runtime errors

          When there is abnormal termination of an application generated by
          Free Pascal, it is very probable that a runtime error will be
          generated. These errors have the form :

          Runtime error 201 at 0x00010F86
          0x00010F86  main,  line 7 of testr.pas
          0x0000206D

          The 201 in this case indicates the runtime error number. The
          definition of the different runtime error numbers is described in
          the Free Pascal user's manual, Appendix D. The hexadecimal
          numbers represent the call stack when the error occured.

      20. Standard units

          To see the list of base units supplied with Free Pascal, and on
          which platform they are supported, consult the Free Pascal user's
          manual. There is also a short description of what each unit does
          in the same section of the manual.

      21. How does the compiler work internally?

          A draft document describing the internals of the FreePascal
          compiler is available here.

      22. Debugging smartlinked code does not fully work

          Debugging smart linked code might not work correctly. This is due
          to the fact that no type information is emitted for smartlinked
          code. If this would not be done, the files would become enormous.

          While debugging, it is not recommended to use the smartlinking
          option.

      23. Debugging shared library (dynamic linked library) code does not
          fully work

          Debugging shared libraries (or dynamic linked libraries) produced
          by the Free Pascal compiler is not officially supported.

      24. PPU files binary compatibility between versions

          Can't compile a program using a binary only version of a unit

          Sometimes, even though there is a binary version of a module
          (unit file and object file) available, the compiler still gives
          compilation errors. This can be caused either by an
          incompatibility in the PPU file format (which should change only
          between major versions of the compiler), or by a change in one of
          the units of the RTL which has changed in between releases.

          To get more information, compile the code using the -va (show all
          information) compiler switch, and the unit loading phase will be
          displayed. You might discover that the unit being loaded requires
          to be recompiled because one of the unit it uses has changed.

          So if you plan on distributing a module without the source code,
          the binaries should be compiled and made available for all
          versions of the compiler you wish to support, otherwise
          compilation errors are bound to occur.

          In other words, the unit (PPU) file format does not change
          significantly in between minor releases of the compiler (for
          exemple : from 1.0.4 and 1.0.6) which means they are binary
          compatible, but because the interface of the units of the RTL
          certainly changes between versions, recompilation will be
          required for each version anyways.

      25. File denied errors when opening files with reset

          Trying to open files using reset on non-text files might cause a
          Runtime Error 5 (Access denied).

          All files opened using the above system unit routine use the
          current filemode value to determine how the file is opened. By
          default, filemode is set to 2 (Read/Write access).

          So, a call to reset on non-text files does not indicate that the
          file will be opened read-only. So, trying to open a file using
          reset with the defaults will fail on read-only files. filemode
          should be set to 0 (Real-only access) before calling reset to
          solve this problem. A sample solution is shown below.

          const
          { possible values for filemode }
          READ ONLY = 0;
          WRITE ONLY = 1;
          READ WRITE = 2;
          var
          oldfilemode : byte;
          f: file;
          begin
          assign(f,'myfile.txt');
          oldfilemode := filemode;
          { reset will open read-only }
          filemode := READ ONLY;
          reset(f,1);
          { restore file mode value }
          filemode := oldfilemode;
          ...
          close(f);
          end;

          For more information, consult the Free Pascal reference manual

  2. Pascal language related information

       1. Considerations in porting to other processors

          Because the compiler now supports processors other than the
          Intel, it is important to take a few precautions so that your
          code will execute correctly on all processors.

             + Limit your use of asm statements unless it is time critical
               code
             + Try not to rely on the endian of the specific machines when
               doing arithmetic operations. Furthermore, reading and
               writing of binary data to/from files will probably require
               byte swaps across different endian machines (swap is your
               friend in this case). This is even more important if you
               write binary data to files.
             + Try limiting your local variables in subroutines to 32K, as
               this is the limit of some processors, use dynamic allocation
               instead.
             + Try limiting the size of parameters passed to subroutines to
               32K, as this is the limit of some processors, use const or
               var parameters instead.
             + The integer and cardinal types may have a different sizes
               and ranges depending on the compiler mode, and the target
               processor.

       2. Considerations in porting code to other operating systems

          Because the compiler supports several different operating
          systems, is important to take a few precautions so that your code
          will execute correctly on all systems.

             + File sharing is implemented differently on different
               operating systems, so opening already opened files may fail
               on some operating systems (such as Windows). The only
               correct way to make sure to have the same file sharing
               behavior is to use the I/O routines furnished in sysutils.
             + Clean up at the end of your program, i.e. close all files on
               exit, and release all allocated heap memory, as some
               operating systems don't like it when some things are left
               allocated or opened.
             + Some operating systems limit the local stack space which can
               be allocated, therefore it is important to limit subroutine
               nesting, and the amount of local variables. Limiting total
               stack space usage at a given moment to at most 256 KBytes
               while make porting easier.
             + Do not hard code paths to files, try to use relative paths
               instead
             + Use the following constants (defined in the system unit) to
               get information on files, line endings, and to build paths:
                  + LineEnding : Indicates the characters which end a text
                    line
                  + LFNSupport : Indicates if long filenames are supported
                    (more then 8.3 characters)
                  + DirectorySeparator : The character or characters which
                    separate path components
                  + DriveSeparator : The character which separate the drive
                    specification from the rest of the path
                  + PathSeparator : The character which separates
                    directories in the search path environment
                  + FileNameCaseSensitive : Boolean indicating if the
                    filenames for this system are case-sensitive or not
               It is also possible to use the PathDelim, PathSep and
               DriveDelim constants defined in sysutils.

       3. Compiling Delphi code using Free Pascal

          The compiler supports the Delphi classes. Make sure you use the
          -S2 or -Sd switches (see the manuals for the meaning of these
          switches). For a list of Delphi incompabilities also check the
          manual.

       4. Building a unit

          It works like in Turbo Pascal. The first keyword in the file must
          be UNIT (not case sensitive). The compiler will generate two
          files: XXX.PPU and XXX.O. The PPU file contains the interface
          information for the compiler and the O-file the machine code (an
          object file, whose precise structure depends on the assembler you
          used). To use this unit in another unit or program, you must
          include its name in the USES clause of your program.

       5. Compiling the system unit

          To recompile the system unit, it is recommended to have GNU make
          installed. typing 'make' in the rtl source directory will then
          recompile all RTL units including the system unit. You may choose
          to descend into the directory of your OS (e.g. rtl/go32v2) and do
          a 'make' there.

          It is possible to do all this manually, but you need more
          detailed knowledge of the RTL tree structure for that.

       6. How does function overloading work?

          function overloading is implemented, like in C++:

          procedure a(i : integer);
          begin
          end;
          procedure a(s : string);
          begin
          end;
          begin
          a('asdfdasf');
          a(1234);
          end.

          You must be careful. If one of your overloaded functions is in
          the interface part of your unit, then all overloaded functions
          must be in the interface part. If you leave one out, the compiler
          will complain with a 'This overloaded function can't be local'
          message. Overloaded functions must differ in their parameters,
          it's not enough if their return types are different.

       7. Calling C functions

          It is possible to call functions coded in C, which were compiled
          with the GNU C compiler (GCC). Versions which have been tested
          are version 2.7.2 through 2.95.2 of GCC. For calling the C
          function strcmp declare the following:

          function strcmp(s1 : pchar;s2 : pchar) : integer;cdecl;external;

       8. Integrated Assembler syntax

          The default assembler syntax (AT&T style) is different from the
          one in Borland Pascal (Intel style).

          However, as of version 0.99.0, the compiler supports Intel style
          assembly syntax. See the documentation for more info on how to
          use different assembler styles.

          A description of the AT&T syntax can be found in the GNU
          Assembler documentation.

       9. Unit system, syslinux, sysos2 or syswin32 not found errors

          System (syslinux - not the bootloader, sysos2 or syswin32,
          depending on platform) is Pascal's base unit which is implicitely
          used in all programs. This unit defines several standard
          procedures and structures, and must be found to be able to
          compile any pascal program by FPC.

          The location of the system.ppu and syslinux.o files are
          determined by the -Fu switch which can be specified commandline,
          but is usually in the ppc386.cfg or fpc.cfg configuration file.

          If the compiler can't find this unit there are three possible
          causes:

            1. The ppc386.cfg or fpc.cfg isn't in the same path as the
               compiler executable (go32v2, win32 and OS/2) or can't be
               found as "/etc/fpc.cfg" or ".fpc.cfg" in your homedirectory
               (Linux).
            2. The fpc.cfg or ppc386.cfg doesn't contain the -Fu line, or a
               wrong one. See the make cycle faq, especially the chapters
               about the fpc.cfg and the directory structure.
            3. The files ARE found but the wrong version or platform.
               Correct ppc386.cfg or fpc.cfg to point to the right versions
               or reinstall the right versions (this can happen if you try
               to use a snapshot compiler while the -Fu statement in the
               used fpc.cfg still points to the RTL that came with the
               official release compiler).

          A handy trick can be executing "ppc386 programname -vt", this
          shows where the compiler is currently looking for the system
          unit's files. You might want to pipe this through more (Dos,
          OS/2, Windows) or less (Linux), since it can generate more than
          one screen information:

          Dos, OS/2, Windows: ppc386 programname -vt |more

          unix, linux: ppc386 programname -vt |less

  3. Runtime library related information

       1. Using the graph unit with Free Pascal

          Since version 1.0, we have a completely platform independent way
          of selecting resolutions and bitdepths. You are strongly
          encouraged to use it, because other ways will probably fail on
          one or other platform. See the documentation of the graph unit
          for more information.

       2. Why do I get wrong colors when using the graph unit?

          If you use detect as graphdriver, you will end up with the
          highest supported bitdepth. Since the graph unit currently only
          supports up to 16 bits per pixel modes and since this bitdepth is
          supported by all graphics cards made in at least the last 5
          years, you will most likely get a 16 bit mode.

          The main problem is that in 16 (and 15, 24, 32, ...) bit modes,
          the colors aren't set anymore using an index in a palette (the
          palettized way is called "indexed color"). In these modes, the
          color number itself determines what color you get on screen and
          you can't change this color. The color is encoded as follows (for
          most graphics cards on PC's at least):

             + 15 bit color: lower 5 bits are blue intensity, next come 5
               bits of green and then 5 bits of red. The highest bit of the
               word is ignored.
             + 16 bit color: lower 5 bits are blue intensite, next come *6*
               bits of green and then 5 bits of red.

          This means that either you have to rewrite your program so it can
          work with this so-called "direct color" scheme, or that you have
          to use D8BIT as graphdriver and DetectMode as graphmode. This
          will ensure that you end up with a 256 (indexed) color mode. If
          there are no 256 color modes supported, then graphresult will
          contain the value GrNotDetected after you called InitGraph and
          you can retry with graphdriver D4BIT. Make sure you use the
          constant names (D8BIT, D4BIT, ...) and not their actual numeric
          values, because those values can change with the next release!
          That is the very reason why such symbolic constants exist.

       3. File sharing and file locks

          The standard runtime library file I/O routines open files in the
          default sharing mode of the operating system (system, objects
          units). Because of this, you might get problems if the file is
          opened more than once either by another process or the same
          process.

          Generally the behaviors for the different operating systems are
          as follows :

             + UNIX systems : There is no verification at all.
             + Windows : An access denied error will be reported.
             + Amiga : An access denied error will be reported.
             + DOS / OS/2 : If the file is opened more than once by the
               same process, no errors will occur, otherwise an access
               denied error will be reported.

          There are two ways to solve this problem:

             + Use specific operating system calls (such as file locking on
               UNIX and Amiga systems) to get the correct behavior.
             + Use the sysutils unit or the Free Component Library
               TFileStream File I/O routines, which try to simulate, as
               much as possible, file sharing mechanisms.

       4. Accessing huge files using standard I/O routines

          The runtime library currently limits access to files which have
          file sizes which fit into a 32-bit signed integer (longint).

          Therefore accessing files which have file sizes greater than 2
          Gigabytes will produce unpredictable behavior. Application
          accessing such files will have to use direct operating systems
          calls (if the OS supports such files) to workaround the problem.

       5. Turbo vision libraries

          A Turbo Vision port, called Free Vision, has progressed nicely
          lately. It's already very usable, we are even writing an IDE in
          it. When it will be in a more stable state it will be included in
          the standard runtime library.

  4. DOS related information

       1. Releasing software generated by the DOS compiler

             + If your program uses floating point code (which is very
               probable), make sure to read "Applications created with Free
               Pascal crash on 80386 systems" regarding special issues
               which might occur. Math coprocessor emulation software is
               then required (wmemu387.dxe should be redistributed with
               your software)
             + The target system must have a DPMI server. To avoid
               problems, the file cwsdpmi.exe should always be
               redistributed with your application
             + The target system must have DOS 3.3 or later
             + The default heap size is 2 Megabytes. Automatic growing of
               the heap is supported
             + The default stack size is 256 Kbytes. See also "Changing the
               default stack size"
             + The stack checking option is available on this platform.

       2. Debugging

          The GNU debugger v4.16 and later have been tested, and generally
          work as they should. Because the GNU debugger is C oriented, some
          pascal types might not be represented as they should. It is
          suggested to use gdbpas or the text mode IDE instead of GDB,
          which are both available for the DOS target.

       3. Dynamic Libraries

          Creation or use of shared libraries (also called dynamic link
          libraries) is not supported under this platform.

       4. Profiling

          Profiling with gprof is supported for this platform.

       5. Running Free Pascal without a math coprocessor?

          On the Intel version the emulator is automatically loaded by the
          compiler if you add the following commands to your autoexec.bat:

          SET 387=N
          SET EMU387=C:\PP\BIN\GO32V2\WEMU387.DXE

          (don't forget to replace the C:\PP with the directory where you
          installed FPC)

       6. Applications created with Free Pascal crash on 80386 systems

             + Trying to run an application which does floating point
               operations on a 386 system without a math co-processor will
               crash unless the emu387 unit is used, as this unit loads the
               math co-processor emulator (called wmemu387.dxe). You can
               add the unit as follows:

               program myprog;
               uses emu387, ...

               When the application is released, the software package
               should also include the wmemu387.dxe redistributable file to
               avoid problems.

               .
             + Some 80386 systems have a hardware bug which corrupt the
               accumulator register EAX if it is used in a MOV instruction
               just after a POPAL instruction. Prior to version 1.0.5, the
               compiler and runtime library could generate such code
               sequences. This is now fixed and should no longer cause
               problems

       7. The mouse cursor is not visible in graphics screens

          A lot of DOS mouse drivers don't support mouse cursors in VESA
          modes properly. Logitech is said to have a decent mouse driver,
          which can be found here

       8. Accessing I/O ports

          With versions before 0.99.10: if you're under DOS you can use the
          outport* and inport* procedures of the go32 unit.

          Since version 0.99.8, the Port array is supported like in TP, as
          long as you use the ports unit in your program (not available
          under Win32).

          I/O port access is possible under Linux, but that requires root
          privileges. Check the manuals for the IOPerm, ReadPort and
          WritePort procedures. (Unit Linux)

       9. Accessing DOS memory / Doing graphics programming

          You can do like in Turbo Pascal, via absolute or mem[]. For
          larger memory blocks use the dosmemput/dosmemget routines in the
          Go32 unit.

      10. Changing the default stack size

          Under the DOS (GO32V2) target, the default stack size to 256
          bKbytes. This can be modified with a special DJGPP utility called
          stubedit. It is to note that the stack may also be changed with
          some compiler switches, this stack size, if greater then the
          default stack size will be used instead, otherwise the default
          stack size is used.

      11. Using OS/2 generated applications under DOS

          OS/2 applications (including the compiler) should work correctly
          under vanilla DOS, since it is based on EMX (versions prior to
          1.0.5 had big problems with EMX under DOS, this is now fixed). It
          is important to note that the compiled applications require the
          EMX runtime files (emx.exe) to execute properly. It may be
          necessary to distribute these files with the generated
          application.

  5. Windows related information

       1. Releasing software generated by the windows compiler

          There is no special requirements for releasing software for the
          windows platform, it will work directly out of the box. The
          following are default for the Windows platform:

             + The default heap size is 256 Kbytes. Automatic growing of
               the heap is supported. It is to note that Windows 95,
               Windows 98 and Windows Me limit the heap to 256 Mbytes (this
               is a limitation of those Operating systems, not of Free
               Pascal, consult MSDN article Q198959 for more information).
             + Stack size is unlimited
             + The stack checking option is not available on this platform.

       2. Debugging

          The GNU debugger v4.16 and later have been tested, and generally
          work as they should. Because the GNU debugger is C oriented, some
          pascal types might not be represented as they should. It is
          suggested to use gdbpas or the text mode IDE instead of GDB,
          which are both available for windows targets.

       3. Dynamic libraries

          Creation and use of shared libraries (also called dynamic link
          libraries) is fully supported by the compiler. Refer to the
          Programmer's Reference Manual for more information on shared
          library creation and use.

       4. Profiling

          Profiling is supported using gprof, starting with version 1.0.7.
          It requires mingw to be installed, and that fpc.cfg point to the
          correct library paths.

       5. Graph and problems with keyboard, mouse and "dummy dos windows"

          Problem:
             + If you use the Graph unit under Win32, you can't use the API
               mouse unit for mouse support or use the win32 Crt unit to
               get keyboard data. The reason for this is that the window
               popped up is a GUI window, and not a console one.
          Solution:
             + Use units WinMouse and WinCrt instead.

          Problem:
             + When you follow the above advice, and you run your purely
               Graph based win32 program from the RUN menu in windows, a
               dummy dos window is opened.
          Solution:
             + Set the application type to GUI:

               {$apptype GUI}

               and put this line before your programs InitGraph statement:

               ShowWindow(GetActiveWindow,0);

               This will hide the dos window window.

          Some of the demos (like fpctris) use these techniques

       6. Makefile problems on Win2000 (and NT)

          After the 1.0.4 release, some problems with the mingw win32 build
          tools (make.exe and friends) were discovered. A patched version
          of these tools has been released. Automatically building large
          parts of the sources under Windows 2000 and Windows NT is now a
          lot easier.

            1. Download makew32.zip from the ftp site or a mirror.
            2. Unzip it to your pp directory. (the archive already contains
               the bin/win32/ directories)
            3. Properties of "My Computer", (system properties), tab
               "advanced", "Environment Variables".
            4. In the bottom box, select the "Path" entry, and then "Edit"
            5. In the top field of this dialog, change "Path" to "PATH",
               and click OK.
            6. Close and Reopen dosboxes to apply changes.

          Alternatively, if changing the case of the "Path" variable leads
          to problems, you could run the following batchfile in each dosbox
          prior to working with FPC:

          set a=%PATH%
          set Path=
          set PATH=%A%
          set a=

          A lot, if not all, makefile trouble is now probably gone. If you
          still have problems try getting the makent.zip utilities from the
          ftp site or a mirror. It should be installed just like
          makew32.zip.

          Note: The win32 version of make is case sensitive with respect to
          filenames (paths?) and environment variables

       7. Using the DOS compiler under Windows 95

          There is a problem with the DOS (GO32V2) compiler and Windows 95
          on computers with less than 16 Megabytes of RAM. First set in the
          properties of the DOS box the DPMI memory size to max value. Now
          try to start a demo program in the DOS box, e.g. HELLO (starting
          may take some time). If this works you will be able to get the
          compiler to work by recompiling it with a smaller heap size,
          perhaps 2 or 4 MB (option -Chxxxx).

       8. Using OS/2 generated applications under Windows

          Normally OS/2 applications (including the compiler) should work
          under Windows, since it is based on EMX. You need the RSX
          extender (rsx.exe) to do this. There have been problems reported
          while trying to run EMX applications under NT / 2000 / XP systems
          though. This seems to be a problem with EMX (RSX) itself. It is
          not recommended to use Free Pascal OS/2 compiled programs under
          NT / 2000 and XP, as it might produce unexpected results.

       9. Using DOS generated applications under windows

          Several problems have been found running DOS software under
          certain versions of Windows (NT / 2000 / XP). These seem to be
          problems with the DOS emulation layers (emulated DPMI services).
          These problems may not occur with all software generated by FPC.
          Either applications should be tested on these systems before
          being released, or Windows versions should be generated instead.

      10. The mouse cursor does not respond in the Windows IDE

          In windowed mode, the mouse cursor might not respond to mouse
          moves and clicks. Just change the properties of the console, and
          remove the quick edit mode option. This should solve the mouse
          response problems.

      11. INSTALL.EXE of version 1.0.6 returns errors under some version of
          Windows

          The original 1.0.6 installer gave errors under Win95/98/Me in
          some circumstances. A new installer (INSTALL.EXE) was included
          after the 10th July 2002 which fixed the problem.with version
          1.0.6. If you downloaded Free Pascal for Windows before this
          date, you should upgrade to the latest version of FreePascal.

  6. UNIX related information

     This section also applies to most unix variants, such as linux,
     freebsd and netbsd.

       1. Releasing software generated by the unix compilers

             + The default heap size is 256 Kbytes for the intel version,
               and 128 Kb for the m68k versions. Automatic growing of the
               heap is supported.
             + There is no stack space usage limit.
             + Under Solaris and QNX, stack checking is simulated.
             + Minimal operating system versions :
                  + Linux : Kernel v1.1.x or later.
                  + FreeBSD : version 4.x or later.
                  + NetBSD : version 1.5 or later.
                  + Solaris : version 5.7 of SunOS or later (should work
                    with earlier versions, but untested).

       2. Debugging

          The GNU debugger v4.16 and later have been tested, and generally
          work as they should. Because the GNU debugger is C oriented, some
          pascal types might not be represented as they should. For FreeBSD
          a recent GDB (v5) CVS snapshot is recommended for Pascal support
          and ease of building

       3. Dynamic libraries

          These operating systems do support shared libraries (also called
          dynamic link libraries), Free Pascal currently does not emit
          position independant code (PIC), as required for the creation of
          shared libraries.

          Therefore, even though the linux compiler target permits creating
          shared libraries, the usage of that shared library may result in
          undefined behavior, especially if accessing global variables in
          the library. Creation of shared libraries is not recommended with
          the current version of the compiler.

          Importing code from shared libraries does work as expected
          though, since it does not require usage of position independant
          code.

       4. Profiling

          Profiling is supported using gprof under linux, FreeBSD and
          NetBSD, the latter two only since 1.0.8. On other other unix-like
          operating systems, profiling is currently not supported.

       5. Why can't the linker find "vga"?

          This error typically looks like this:

          Free Pascal Compiler version 1.0.x [xxxx/yy/zz] for i386
          Copyright (c) 1993-2000 by Florian Klaempfl
          Target OS: Linux for i386
          Compiling test.pp
          Assembling test
          Linking test
          /usr/bin/ld: cannot find -lvga
          test.pp(6,4) Warning: Error while linking Closing script ppas.sh 5 Lines
          compiled, 0.2 sec

          This error is not an error in the installation of FPC or FPC
          itself, but a missing Svgalib library in your unix install.
          Please install the required library using your favourite package
          manager tool

       6. Compiler indicates missing as and ld

          Normally unix systems have the assembler (as) and linker (ld)
          pre-installed and already in the search path. That is the reason
          why these tools are not supplied with the compiler.

          If the compiler cannot find these tools, either they are not in
          your search path, or they are not installed. You should either
          add the path where the tools are located to your search path, and
          / or you should install these tools.

          It is to note that the Solaris version of FPC contains these
          tools.

  7. OS/2 related information

       1. Releasing software generated by the OS/2 compiler

          The OS/2 compiler is based on EMX, therefore it should work both
          on OS/2 and on vanilla DOS systems.

             + All applications generated for the OS/2 (EMX) target require
               the EMX 0.9d (or later) runtime files to run. These files
               should be redistributed with your software. All the files
               which should be redistributed are included in emxrt.zip
             + Under OS/2, LIBPATH should be modified to add the EMX DLL
               paths. Otherwise, programs will not run and will abort with
               an error 'Cannot find EMX.dll'.
             + The default heap size is 256 Kbytes. Automatic growing of
               the heap is supported.
             + Stack can grow up to 256 Kbytes by default. This can be
               changed by the user or developper using the emxstack or
               emxbind utilities.

       2. Debugging

          The GNU debugger v4.16 (EMX port) has been tested (including its
          PM add-on, pmgdb.exe) and generally works as it should. Because
          the GNU debugger is C oriented, some pascal types might not be
          represented correctly.

       3. Dynamic libraries

          Even though this operating system permits the creation and usage
          of shared libraries (also called dynamic link libraries), the
          compiler currently only permits importing routines from dynamic
          libraries (creation of dynamic libraries is unsupported).

       4. Profiling

          Profiling is currently not supported for this platform.

       5. Using DOS generated applications under OS/2

          It has been reported that some DOS (GO32V2) applications
          (including the DOS compiler itself) generated by the compiler
          fail on some OS/2 installations. This is due to problems in the
          OS/2 DPMI server.

          You should use native OS/2 applications under OS/2 (including the
          native OS/2 compiler) or try installing a new OS/2 fixpack to see
          if it solves the problem.

       6. INSTALL.EXE of version 1.0.6 or below fails with an unknown error
          (-1) under OS/2

          or

          INSTALL.EXE of version 1.0.6 or above complains about missing TZ
          variable under OS/2

          You are most probably using an older version of OS/2 (like OS/2
          Warp 3.0) and don't have TZ variable in your environment. The
          easiest solution is to add "SET TZ=..." (e.g. "SET
          TZ=CET-1CEST,3,-1,0,7200,10,-1,0,10800,3600" for most of western
          and central Europe) line to your CONFIG.SYS, and restart OS/2.
          The proper setting for you can be found e.g. using the TZCALC
          tool from TIME868 package.

  8. BeOS related information

       1. Releasing software generated by the BeOS compiler

          Software generated for the BeOS target will only work on the
          intel based version of BeOS.

             + The target system must have at least BeOS v4.0 or later
               (BeOS 5.1d 'Dano' is not supported)
             + The default heap size is 256 Kbytes. Automatic growing of
               the heap is supported
             + Stack size is set to 256 Kbytes. This cannot be changed

       2. Debugging

          This operating system uses DWARF debugging information, and Free
          Pascal does not support emitting DWARF debugging information. It
          is currently impossible to debug applications under BeOS

       3. Dynamic libraries

          Even though this operating system permits the creation and usage
          of shared libraries (also called dynamic link libraries), the
          compiler currently only permits importing routines from dynamic
          libraries (creation of dynamic libraries is unsupported).

       4. Profiling

          Profiling is currently not supported for this platform.

  9. Amiga related information

       1. Releasing software generated by the Amiga compiler

             + The target system must have AmigaOS v2.04 or higher
             + The default heap size is 128 Kbytes. Automatic growing of
               the heap is supported.
             + Stack size is not set by the compiler, but by the stack
               command on the CLI. Because of this, and because default
               stack sizes for this target are small, it is recommended to
               always compile software with stack checking enabled.
             + By default, the compiler generates code for the 68020+
               processor. The code generated will not work on 68000 and
               68010 systems unless the -O0 compiler switch is used, and
               there is no runtime checking. It is up to you to implement
               CPU verification at program startup. The standard runtime
               libraries have been compiled for the 68000 target, and
               should not cause any problems.
             + All floating point operations are simulated, and use the
               single floating point type. You will need to recompile all
               standard runtime libraries and your application, with the
               software floating point option off, if you wish to use
               hardware floating point.

       2. Debugging

          Source level debugging is not supported for the Amiga target.
          Assembler target debugging is possible though, using the
          excellent Barfly debugger.

       3. Dynamic libraries

          Even though this operating system permits the creation and usage
          of shared libraries (also called dynamic link libraries), the
          compiler does not support either the importing or creation of
          shared libraries. Importing must be done manually in assembler.

       4. Profiling

          Profiling is currently not supported for this platform.

 10. PalmOS related information

       1. Releasing software generated by the PalmOS compiler

       2. Debugging

       3. Dynamic libraries
