# 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
   - 4/2003: 1.0.8 versuin

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.8)

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.8. 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