FAQ / 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. I want a new version NOW
    10. Installing a snapshot
    11. I have to write a program for homework. Can you help?
    12. How do I make a real Windows application with windows and menu bars?
    13. How do I make a game with Free Pascal? Can I make a game like Doom 3?
    14. Getting more information when an application crashes
    15. Compiler seems to skip files in directories -Fu points to
    16. Why are the generated binaries so big?
    17. Runtime errors
    18. Standard units
    19. Debugging smartlinked code does not fully work
    20. Cannot compile a program using a binary-only version of a unit
    21. Will you support ISO Extended Pascal?
    22. What about .NET?
 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 not found errors
    10. There is a new language extension that would be really useful. Will you
        include it?
 3. Runtime library related information
     1. Why do I get wrong colors when using the graph unit?
     2. File sharing and file locks
     3. File denied errors when opening files with reset
 4. 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. Cygwin binary directory in your path sometimes causes builds to fail
     7. Using the DOS compiler under Windows 95
     8. Using DOS generated applications under windows
     9. The mouse cursor does not respond in the Windows IDE
 5. UNIX-related information
     1. Releasing software generated by the UNIX compilers
     2. Debugging
     3. Dynamic libraries
     4. Profiling
     5. Libc is missing on platforms other than i386
     6. Why can't the linker find "vga"?
     7. Compiler indicates missing as and ld
     8. An error occurred while linking, or "did you forget -T?"
 6. 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 complains about a missing TZ variable under OS/2
     7. OS/2 compiler not working after upgrading to 1.9.6 or newer
     8. Compilation under OS/2 fails with error "Can't call the assembler"
 7. 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

 1. General information

     1. What is Free Pascal (FPC)?

        Originally named FPK-Pascal, the Free Pascal compiler is a 16,32 and 64
        bit Turbo Pascal and Delphi compatible Pascal compiler for Linux,
        Windows, OS/2, FreeBSD, Mac OS X, DOS and several other platforms (the
        number of supported targets grows all the time, although not all of
        them are on the same level as the main ones).

        The Free Pascal compiler is available for several architectures: x86
        (16,32 and 64 bit), ARM, PowerPC (32 and 64 bit), SPARC (v8, v9), Java
        Virtual Machine (under development) and MIPS (little and big endian,
        under development). An older version (the 1.0 series) and current
        development versions also supported m68k.

        The compiler is written in Pascal and is able to compile its own
        sources. The source files are distributed under the GPLv2+ and
        included.

        Short history:
          ☆ 06/1993: project start
          ☆ 10/1993: first small programs work
          ☆ 03/1995: the compiler compiles its own sources
          ☆ 03/1996: released on the Internet
          ☆ 07/2000: 1.0 released
          ☆ 12/2000: 1.0.4 released
          ☆ 04/2002: 1.0.6 released
          ☆ 07/2003: 1.0.10 released
          ☆ 05/2005: 2.0.0 released
          ☆ 12/2005: 2.0.2 released
          ☆ 08/2006: 2.0.4 released
          ☆ 09/2007: 2.2.0 released
          ☆ 08/2008: 2.2.2 released
          ☆ 04/2009: 2.2.4 released
          ☆ 12/2009: 2.4.0 released
          ☆ 11/2010: 2.4.2 released
          ☆ 05/2011: 2.4.4 released
          ☆ 01/2012: 2.6.0 released
          ☆ 02/2013: 2.6.2 released
          ☆ 03/2014: 2.6.4 released
          ☆ 01/2015: 3.0.0 released
          ☆ 02/2017: 3.0.2 released 
          ☆ 11/2017: 3.0.4 released
          ☆ 04/2020: 3.2.0 released
     2. Which versions exist, and which one should I use?

        The latest official version is 3.2.0, the first release in the 3.2.x
        series. New development is performed in the 3.3.x series, which will
        eventually be released as 3.4.0 or 4.0.0, depending on milestones
        achieved.

        Historic versions

        FPC's version numbering changed a few times over the years. Pre-1.0
        versioning information has been moved to the Wiki 1.0 versioning
        article.

        Modern versioning

        With the release of 1.0, the version numbering was slightly changed to
        a system resembling one used for the Linux kernels.

          ☆ Releases that only fix bugs in version 1.0 are numbered 1.0.x.
          ☆ Post-1.0 development (the so called snapshots) have version number
            1.1.x.
          ☆ Eventually the 1.1.x versions, when stabilized, were released as
            the 2.0.x series, preceded by betas marked as 1.9.x. Fixes to the
            2.0 release were numbered 2.0.x, fixes to the 2.2 release 2.2.x,
            fixes to the 2.4 release as 2.4.x etc
          ☆ The new development version after the 2.4.0 release was numbered
            2.5.x and so on.
          ☆ Repackagings that affect sources are indicated with a single letter
            as suffix (e.g. 2.0.4a). This is usually the case for platforms
            that weren't part of the original release round.
          ☆ The stable branch (currently fixes_3_2, previously fixes_3_0)
            always has an odd last number (3.0.1, 3.0.3 and 3.2.1). Compilers
            with such versions are snapshots, and e.g. a snapshot with 3.0.3
            can be anywhere between 3.0.2 and the moment 3.0.4 branched off.
            After 3.2.0, the stable branch's number was updated to 3.2.1 etc.

        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 on the mailing lists if it is worth the trouble in your case
        if you are not sure.

        Snapshots of the stable branch (fixes_3_2) are meant to test release
        engineering. They are mainly interesting in the months before a release
        to extensively test the branch from which the release is created.

        We advise all users to upgrade to the newest version for their target
        (preferably the new stable 3.2.x series).

        A graphical timeline of the FPC project plus its near future would be:
        [timeline]
     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 3.2.0 (April 2020). GNU
            Pascal is stopped version 2.1 (from 2002, which can be built with
            several different GCC's as backend; their Mac OS X version is an
            exception though, as it follows the GCC version number).
        Tracking:
            Between releases, development versions of FPC are available through
            daily snapshots and the source via SVN. GPC issues a set of patches
            to the last version a few times a year, and there are regular
            snapshot for OS X and Windows, made by users.
        Operating systems:
            Free Pascal runs on a large number of platforms, inlcuding DOS (16/
            32-bit), Win32 (no UNIX porting layer needed), Linux, FreeBSD,
            NetBSD, OS/2, BeOS, Mac OS X, on the following architectures: x86
            (32 and 64 bit), SPARC, PowerPC (32 and 64 bit), ARM, Java Virtual
            Machine (under development), and MIPS (under development). GNU
            Pascal runs basically on any system that supported by GCC, and for
            which the build process was verified.
        Bootstrapping:
            FPC requires a suitable set of binutils (AS, AR, LD) on some
            platforms, GNU make and a command line bootstrap compiler. New
            architectures/OSes are cross-compiled. GPC bootstraps via a
            suitable version of GCC, and requires a full set of binutils, flex,
            bison, gmake, a POSIX shell and libtool
        Sources:
            Free Pascal is entirely written in Pascal, while GNU Pascal is
            written in C (it's an adaptation of the GNU C compiler)
        Language:
            Free Pascal supports the Borland Pascal dialect, implements the
            Delphi Object Pascal language, Objective-Pascal and has some
            support for ISO 7185 Pascal and Mac Pascal extensions. GNU Pascal
            supports ISO 7185, ISO 10206 and (most of) Borland Pascal 7.0
        Extensions:
            Free Pascal implements method, function and operator overloading
            (later Delphi versions have also added these, so strictly they are
            not extensions anymore). GNU Pascal implements operator overloading.
        License:
            Both compilers come under the GNU GPL.
        Author:
            Free Pascal was started by Florian Klämpfl, 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
        (RTL) come under a modified Library GNU Public License (LGPL). This
        license does not impose any kind of license on the created
        applications. It is therefore possible to create closed source or
        proprietary software using the Free Pascal Compiler.

        The following exception has been added to the LGPL variant that applies
        to the FPC RTL:

        As a special exception, the copyright holders of this library give you
        permission to link this library with independent modules to produce an
        executable, regardless of the license terms of these independent
        modules, and to copy and distribute the resulting executable under
        terms of your choice, provided that you also meet, for each linked
        independent module, the terms and conditions of the license of that
        module. An independent module is a module which is not derived from or
        based on this library. If you modify this library, you may extend this
        exception to your version of the library, but you not obligated to do
        so. If you do not wish to do so, delete this exception statement from
        your version.

        Please note that you still have to comply to the LGPL as far as sources
        of the runtime library itself are concerned. This, for example,
        requires you to provide the source code of the runtime library if a
        recipient of your application asks for it. If you want to write
        proprietary closed source software, please comply with the following
        terms:
          ☆ Most people can satisfy the source code requirement by mentioning
            that the RTL source code can be downloaded at the Free Pascal web
            site: if you did not modify the rtl this is considered adequate to
            satisfy the LGPL requirement of providing source code.
          ☆ If you made modifications to the runtime library, you cannot keep
            them for yourself, you must make them available if requested by
            recipients of your application.
          ☆ Distribute the modified LGPL license with your product, indicating
            to which parts of your application it applies (the FPC RTL).

        The compiler source code, on the other hand, comes under the GNU
        General Public License, which means that the compiler source can only
        be used in software projects that are distributed under a compatible
        license (or that are not distributed at all).
     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 that has 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 to an ftp site. You have to use the login name
        "anonymous" and your e-mail address as your password.
     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. 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 in 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 does not work, try again one
        or two days later.

        The latest snapshot can always be downloaded from the development web
        page.
    10. 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.
    11. 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.
    12. How do I make a real Windows application with windows and menu bars?

        The easiest way is to download Lazarus. It won't be just a Windows
        application, it will also work under Linux, FreeBSD and Mac OS X.
    13. How do I make a game with Free Pascal? Can I make a game like Doom 3?

        Yes, you can make games with Free Pascal and if you are really good you
        can make a game like Doom 3. Making games is difficult, you need to be
        an experienced programmer to make them. The web site
        www.pascalgamedevelopment.com is a community of people who program
        games in Free Pascal and Delphi.

        If you want a start, please start to study JEDI-SDL or PTCPas. Also you
        can try to study an existing game, for example The Sheep Killer is a
        very simple game and it should not be very hard to understand its code.
    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 --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
                (";") on Windows, or colons (":") on UNIX platforms. 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 on 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. 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.

        Also note that FPC, contrary to Turbo Pascal keeps track of include
        files. Modified include files or duplicate names can trigger an attempt
        to recompile.
    16. 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 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 will not do
            anything when compiling units)
         3. Turn on optimisations, both for supplied packages (RTL, FV, FCL)
            and for your own code, this will also decrease the code size.
        Generally Free Pascal generates smaller binaries than modern competing
        compilers, however, it does not hide code in large dynamic libraries.
        Free Pascal generates larger binaries than compilers from long ago do.
        Large framework libraries result in larger executables. See also the
        Size Matters wiki entry.
    17. Runtime errors

        When an application generated by FPC terminates in an abnormal way, it
        is very likely that a runtime error will be generated. These errors
        have the form :

                    Runtime error 201 at $00010F86
                      $00010F86  main,  line 7 of testr.pas
                      $0000206D


        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
        addresses on the call stack when the error occured.
    18. 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.
    19. 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.
    20. Cannot 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 claims it cannot find the unit
        This can be caused either by an incompatibility in the PPU file format
        (which can change across compiler versions), or by a change in one of
        the units of the RTL that has changed in between releases.

        To get more information, compile the code using the -vtu (show tried
        and used unit 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.

        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.
    21. Will you support ISO Extended Pascal?

        FPC's primary goal is to be a Turbo Pascal and Delphi-compatible
        compiler, and it also supports a subset of the Mac-Pascal dialect and
        of Standard ISO Pascal. While in theory it would be possible to add a
        complete ISO Standard or Extended Pascal modes, until now no people
        interested in such functionality have stepped up to work on such
        features.

        GNU-Pascal is however a modern compiler that can compile ISO Extended
        Pascal. If you have any need for the ISO Extended Pascal dialect, we
        recommend you to take a look at this compiler.
    22. What about .NET?

        Occasionally, users ask about a FPC that supports .NET, or our plans in
        that direction.

        Mainly the users are either interested because of .NET's portability
        aspects (Mono is quoted over and over again), or because it is supposed
        to be the next big thing in Windows programming, and they think Windows
        programming will not be possible in the future.

        While the FPC core developpers are somewhat interested out of academic
        curiousity (mainly because it could be a pilot for a generalized
        backend creating bytecode) there are however several problems with .NET
        in combination with FPC:
         1. Pascal is a language that uses pointers, and existing codebases can
            only be unmanaged. Unmanaged code is not portable under .NET, so
            that already kills most possible benefits. This also means that
            existing FPC and Delphi code won't run on .NET. There are more such
            little language problems.
         2. FPC's libraries are not based on .NET classes and data models (and
            cannot be changed to do so without effectively rewriting them),
            moreover the libraries could only be unmanaged too, or they would
            be incompatible
         3. There is nothing practical known yet about how portable an average
            .NET program will be. Little experiments with hello world level
            code mean nothing, that kind of code works with nearly any
            language. A good test would be to see existing non trivial
            codebases run unmodified under mono, that were not designed with
            mono in mind. Just like we try to do for Delphi
         4. The fact that on Windows 80% of the .NET code seems to be ASP.NET
            does not help either. This makes porting existing code less useful
            (since ASP.NET is tied to IIS), and new codebases of portable code
            can be set in nearly every language
         5. Operating System dependant code would not work anymore, since the
            Win32/64 interface is unmanaged.

        So effectively this means that for FPC to benefit from .NET you would
        have to significantly adapt the language (thus compiler) and libraries,
        and be incompatible with the existing native sourcecode. Moreover that
        also means that existing apps would have to be rewritten for .NET,
        since it would take more than a simple recompile with a FPC/.NET
        compiler.

        While unmanaged code has some uses (easier integration with managed
        code inside Windows), this still requires writing a code generator and
        defining interfaces and libraries. This means a lot of work and since
        .NET take-up is not really high, this might not be worth it.

        However if a FPC user does the bulk of the work (e.g. a bytecode
        codegenerator, and maybe some base libraries) and if the work is
        suitable for inclusion in FPC (a very big if), we will of course
        include it.

        Since support for generating JVM bytecode has been added to the
        compiler, such a project may be more realistic now than it has been in
        the past. Many of the caveats mentioned above still hold though:
        language compatibility is not 100% and most standard units will have to
        be reimplemented.

 2. Pascal language related information

     1. Considerations in porting to other processors

        Because the compiler supports multiple processor architectures, 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 endianness of the specific machines when
            performing operations depending on data layout. In particular,
            reading and writing binary data to/from files will probably require
            byte swaps across different endianness machines (swapendian is your
            friend in this case). Freepascal defines FPC_LITTLE_ENDIAN or
            FPC_BIG_ENDIAN to indicate the target endianness.
          ☆ 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 where appropriate.
          ☆ CPU16,CPU32 or CPU64 is defined indicating whether the target is a
            16,32-bit or 64-bit cpu. This can help with incorporating 16,32-bit
            and 64-bit specific code.
          ☆ Use the ptruint type when declaring an ordinal that will store a
            pointer, since pointers can be either 32-bit or 64-bit depending on
            the processor and operating system. For 16-bit it is memory model
            dependent.

     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
            provided by the sysutils unit.
          ☆ 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 do
            not like it when some things are left allocated or opened.
          ☆ Some operating systems limit the stack space that can be allocated,
            therefore it is important to limit subroutine nesting, and the
            number of local variables. Limiting total stack space usage at a
            given moment to at most 256 KBytes will make porting easier.
          ☆ Do not hardcode 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
                than 8.3 characters)
              ○ DirectorySeparator : The character or characters that separate
                path components
              ○ DriveSeparator : The character that separates the drive
                specification from the rest of the path
              ○ PathSeparator : The character that separates directories in the
                path lists (such as the search path)
              ○ FileNameCaseSensitive : Boolean indicating if the filenames for
                this system may be case-sensitive or not
              ○ AllFilesMask : String containing a wildcard expression for all
                files
            It is also possible to use the PathDelim, PathSep and DriveDelim
            constants defined in the sysutils unit.

     3. Compiling Delphi code using Free Pascal

        The compiler supports Delphi-style classes. Make sure you use the -S2
        or -Sd command line switches (see the manuals for the meaning of these
        switches), or add {$mode objfpc} or {$mode delphi} to your source code.
        For a list of Delphi incompatibilities 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/linux) 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 procedure overloading work?

        Here is a procedure overloading example in FPC or ObjFPC mode:

                            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 is not enough if only
        their return types are different.
     7. Calling C functions

        It is possible to call functions written in C and compiled by the GNU C
        compiler (GCC). E.g., for calling the C function strcmp, declare the
        following (the cint type is declared in the ctypes unit):

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

     8. Integrated Assembler syntax

        The default assembler syntax (AT&T style) is different from the one in
        Borland Pascal (Intel style). FPC however supports both styles. 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 not found errors

        System is Pascal's base unit and is implicitly used by 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 and other unit files is passed on to the
        compiler by the -Fu switch. This switch can be specified on the command
        line, but is usually located in the fpc.cfg configuration file.

        If the compiler cannot find this unit, there are three possible causes:
         1. The fpc.cfg file is not in the same directory as the compiler
            executable (msdos,go32v2, win32 and OS/2) or cannot be found as "/
            etc/fpc.cfg" or ".fpc.cfg" in your homedirectory (UNIX platforms).
         2. The fpc.cfg file does not contain the -Fu parameter, or a wrong
            one. See the build faq (PDF), especially the chapters about the
            fpc.cfg and the directory structure.
         3. The unit files ARE found, but are the wrong version or for a
            different platform. Correct fpc.cfg to point to the right versions
            or reinstall the right versions (this can e.g. 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 "fpc programname -vtu". This will show
        where the compiler is currently looking for the unit files. You might
        want to pipe this through more (Dos, OS/2, Windows) or less (UNIX),
        since it can generate more than one screen information:

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

                            UNIX, Linux: fpc programname -vt |less



    10. There is a new language extension that would be really useful. Will you
        include it?

        Occasionally somebody asks for a new language extension on the
        maillist, and the discussions that follow have a recurring pattern. An
        extension is quite a big deal for the FPC team, and there are some
        criteria that are used to select if an extension is "worth" the
        trouble. The most important pre-selection criteria are:
         1. Compatibility must not be compromised in any way. Existing
            codebases on at least the Pascal level must keep running. This is
            often more difficult than most people think.
         2. The extension must have real value. Anything that is only a shorter
            notation does not apply, unless it is out of compatibility with an
            existing Pascal/Delphi codebase. Practically it means it must make
            something possible that cannot be done otherwise or be a
            compatibility item
         3. The change must fit in with the scope of the project: implementing
            a Pascal compiler with support for RAD and a generic DB system.
            This excludes features like inline SQL, and large garbage collected
            object frameworks.
        Exceptions to the second rule are sometimes made for platform-specific
        reasons (e.g. interfacing to some other language or OS). The first rule
        is often a problem, because issues are not easily recognizable unless
        one has tried to make extensions before. Best is to make a thoroughly
        written proposal that the developers can review, including
          ☆ an explanation of the feature
          ☆ why it is needed, what does it make possible?
          ☆ how you would implement it?
          ☆ many examples of typical use, and tests for possible problem cases
        Try to be verbose and really try to view this from the viewpoint of
        somebody who has to implement it, and try to make examples that span
        multiple units and procedures, and review what happens. Be critical,
        try to punch holes in your own reasoning and find possible problematic
        cases, and document them.

        Besides these pre-selection rules and documentation, the other
        important question is who is going to do the work. Keep in mind that
        the FPC developers are volunteers with todo-lists that are booked till
        the next decade. You cannot expect they will drop everything from their
        hands and implement the feature because you need it urgently, or think
        it is nice. If you are not willing to implement it yourself, submit
        patches and maintain it in the future, chances are slim. Remarks as
        "this will attract a lot of users because..." are considered with a lot
        of scepsis, since that applies to any new development.
 3. Runtime library related information

     1. Why do I get wrong colours 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
        virtually all graphics cards, you will most likely get a 16 bit mode.

        The main problem is that in 16 (and 15, 24, 32, ...) bit modes, the
        colors are not 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 not 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 intensity, 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.
     2. 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.
          ☆ 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
            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.
     3. 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
 4. 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:
          ☆ Stack size is unlimited
          ☆ The stack checking option is not available on this platform.

     2. Debugging

        The GNU debugger v6.4 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 the
        text mode IDE instead of GDB, which is 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. It requires mingw to be installed,
        and that fpc.cfg points 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 cannot 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 created window 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. Cygwin binary directory in your path sometimes causes strange problems

        The mingw make tool seems to look for a "sh.exe", which it finds when
        the cygwin binary directory is in the path. The way directories are
        searched changes, and the build process dies.

        Solution: do not put cygwin in your global path for now, only add it
        when needed. Efforts are made to work around this.

        Possible untested workaround: add mingw sh.exe to a directory before
        the cygwin binary directory in the path
     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 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 or the Go32 extender).
        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.
     9. The mouse cursor does not respond in the Windows IDE

        In windowed mode, the IDE 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.
 5. UNIX-related information

    This section also applies to most UNIX variants, such as Linux, FreeBSD and
    Mac OS X.
     1. Releasing software generated by the UNIX compilers

          ☆ There is no stack space usage limit.
          ☆ Stack checking is simulated.
          ☆ Minimal operating system versions :
              ○ Linux : Kernel v2.4.x or later.
              ○ FreeBSD : version 5.x or later. (4.x can be made to work with
                minor work)
              ○ NetBSD : version 1.5 or later.
              ○ Solaris : version 5.7 of SunOS or later (should work with
                earlier versions, but untested).
              ○ Mac OS X : version 10.4 or later (Intel), or 10.3.9 or later
                (PowerPC)

     2. Debugging

        The GNU debugger v6.5 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.

     3. Dynamic libraries

        Creating dynamic libraries under UNIX-like operating systems is
        supported.

        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. Libc is missing on platforms other than Linux/i386

        Libc is a Kylix compatibility unit. Because it contains many i386
        specific code and features structures from legacy kernels, it has not
        been made available on other platforms.

        To access UNIX functionality, please use units like baseunix and unix.
     6. Why can't the linker find "vga"?

        This error typically looks like this:

                         Free Pascal Compiler version 3.2.x [xxxx/yy/zz] for i386
                         Copyright (c) 1993-2008 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
     7. 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.
     8. An error occurred while linking, or "did you forget -T?"

        There is a bug in GNU LD 2.19 and 2.19.1 that causes it to crash when
        processing FPC-generated linker scripts. This bug has been fixed in the
        mean time.

        At the same time, LD has been modified to emit a warning of the form

                       /usr/bin/ld: warning: link.res contains output sections; did you forget -T?


        This warning is benign, and FPC intentionally does not pass -T to LD.
        The reason is that if -T is used, LD's internal linker script is
        ignored and only FPC's linker script is used. Such linker scripts also
        contain paths to libraries however, and if we would ignore the internal
        linker script then LD would no longer find libraries in
        distribution-specific directories.

 6. OS/2-related information

     1. Releasing software generated by the OS/2 compiler

        The OS/2 compiler version 1.0.x and before is based on EMX, therefore
        it should work both on OS/2 and on vanilla DOS systems. In version
        1.9.x and above this functionality is preserved in newly added target
        EMX, whereas binaries for target OS2 can only run under real OS/2. The
        following notes apply to OS2 target in 1.0.x and EMX in 1.9.x and
        above:
          ☆ 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'.
          ☆ 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 complains about a missing TZ variable under OS/2

        You are most probably using an older version of OS/2 (like OS/2 Warp
        3.0) and do not 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.
     7. OS/2 compiler not working after upgrading to 1.9.6 or newer

        An updated version of GNU assembler (as.exe) is packaged with release
        1.9.6 (newer version was necessary to get support for features of
        modern CPUs). This version of the GNU tool was created with Innotek
        port of GNU C and relies on its libc. This results in higher
        limitations regarding supported configurations, because this libc needs
        recent version of OS/2 Unicode support libraries (LIBUNI.DLL and
        UCONV.DLL) not available in base OS/2 Warp 3.0 and OS/2 Warp 4.0. The
        updated versions were distributed by IBM in corrective packages
        (fixpaks) - see e.g. WarpUpdates site for information about OS/2
        fixpaks and links for downloading them. This issue isn't valid for
        WarpServer for e-Business, MCP and eComStation - these already have the
        correct version.
     8. Compilation under OS/2 fails with error "Can't call the assembler"

        Apart from the point mentioned above, there is at least one more
        potential reason for issues with executing the assembler and resulting
        in error message "Can't call the assembler, error 2 switching to
        external assembling". This error may be result of the OS/2 system not
        being able to find DLLs required for the assembler. Make sure that you
        installed FPC completely (these DLLs are part of file asldos2.zip) and
        that you have set LIBPATH according to instructions in README.TXT (and
        restarted afterwards). If in doubts, running the assembler directly
        from the command line (e.g. "as --version" to show the installed as.exe
        version) may be helpful to see name of the missing dynamic library or
        other details about the problem.
 7. 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)
          ☆ Stack size is set to 256 Kbytes. This cannot be changed

     2. Debugging

        Debugging works with the system-supplied gdb version.

     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. BeOS Linking problems

        It has been reported that certain versions of the linker that shipped
        with some versions of BeOS are broken. If you get an error when linking
        fpc applications, try updating your version of ld from the following
        site.

 8. 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 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
        the text mode IDE instead of GDB, which is 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


        (do not 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 performs 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

        Many DOS mouse drivers do not properly support mouse cursors in VESA
        modes. Logitech is said to have a decent mouse driver, which can be
        found here
     8. Accessing I/O ports

        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.