File: user.tex

package info (click to toggle)
fpc 2.4.0-2
links: PTS, VCS
area: main
in suites: squeeze
size: 179,708 kB
ctags: 311,888
sloc: pascal: 1,780,013; makefile: 856,684; xml: 126,079; ansic: 9,172; perl: 7,711; asm: 7,655; yacc: 3,721; lex: 2,539; sh: 2,032; php: 451; sql: 246; sed: 132; cpp: 79; csh: 34; tcl: 7
file content (4041 lines) | stat: -rw-r--r-- 168,535 bytes
%
%   $Id: user.tex,v 1.32 2005/05/07 13:12:36 michael Exp $
%   This file is part of the FPC documentation.
%   Copyright (C) 1997, by Michael Van Canneyt
%
%   The FPC documentation is free text; you can redistribute it and/or
%   modify it under the terms of the GNU Library General Public License as
%   published by the Free Software Foundation; either version 2 of the
%   License, or (at your option) any later version.
%
%   The FPC Documentation is distributed in the hope that it will be useful,
%   but WITHOUT ANY WARRANTY; without even the implied warranty of
%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
%   Library General Public License for more details.
%
%   You should have received a copy of the GNU Library General Public
%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
%   Boston, MA 02111-1307, USA.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Preamble.
\input{preamble.inc}
\begin{latexonly}
  \ifpdf
  \pdfinfo{/Author(Michael Van Canneyt)
           /Title(User's Guide)
           /Subject(Free Pascal User's Guide)
           /Keywords(Free Pascal)
           }
  \fi
\end{latexonly}

%
% Settings
%
\makeindex
%
% Start of document.
%
\begin{document}
\title{Free Pascal :\\ User's Guide}
\docdescription{User's Guide for \fpc, Version \fpcversion}
\docversion{2.4}
\input{date.inc}
\author{Micha\"el Van Canneyt\\Florian Kl\"ampfl}
\maketitle
\tableofcontents

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Introduction
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Introduction}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% About this document
\section{About this document}
This is the user's guide for \fpc . It describes the installation and
use of the \fpc compiler on the different supported platforms.
It does not attempt to give an exhaustive list of all supported commands,
nor a definition of the Pascal language. Look at the
\refref for these things. For a description of the possibilities and the 
inner workings of the compiler, see the
\progref . In the appendices of this document you will find lists of
reserved words and compiler error messages (with descriptions).

This document describes the compiler as it is/functions at the time of
writing. First consult the \file{README} and \file{FAQ} files, distributed 
with the compiler. The \file{README} and \file{FAQ} files are, in case of 
conflict with this manual, authoritative.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% About the compiler
\section{About the compiler}
\fpc is a 32- and 64-bit Pascal compiler. The current version (2.2)
can compile code for the following processors:
\begin{itemize}
\item Intel i386 and higher (i486, Pentium family and higher)
\item AMD64/x86\_64
\item PowerPC
\item PowerPC64
\item SPARC
\item ARM
\item The m68K processor is supported by an older version.
\end{itemize}
The compiler and Run-Time Library are available for the following operating systems:
\begin{itemize}
\item \dos
\item \linux % (Intel, AMD64, Arm, SPARC, PPC and m68k)
\item \amiga (version 0.99.5 only)
\item \windows
\item Mac OS X 
\item \ostwo (optionally using the EMX package, so it also works on DOS/Windows)
\item \freebsd
\item \beos 
\item \solaris
\item \netbsd 
\item \netware
\item \openbsd 
\item MorphOS
\item Symbian
\end{itemize}
The complete list is at all times available on the Free Pascal website.

\fpc is designed to be, as much as possible, source compatible with
Turbo Pascal 7.0 and Delphi 7 (although this goal is not yet attained),
but it also enhances these languages with elements like operator overloading.
And, unlike these ancestors, it supports multiple platforms.

It also differs from them in the sense that you cannot use compiled units
from one system for the other, i.e. you cannot use TP compiled units.

Also, there is a text version of an Integrated Development Environment (IDE) 
available for \fpc. Users that prefer a graphical IDE can have a look at the
Lazarus or MSIDE projects.

\fpc consists of several parts :
\begin{enumerate}
\item The compiler program itself.
\item The Run-Time Library (RTL).
\item The packages. This is a collection of many utility units, ranging from
the whole Windows 32 API, through native ZIP/BZIP file handling to the whole GTK-2 interface.
\item The Free Component Library. This is a set of class-based utility units which give
a database framework, image support, web support, XML support and many many more.
\item Utility programs and units.
\end{enumerate}

Of these you only need the first two, in order to be able to use the compiler.
In this document, we describe the use of the compiler and utilities. 
The Pascal Language is described in the \refref, and the available routines
(units) are described in the RTL and FCL Unit reference guides.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Getting more information.
\section{Getting more information.}
If the documentation doesn't give an answer to your questions,
you can obtain more information on the Internet, at the following addresses:
\begin{itemize}
\item
\seeurl{http://www.freepascal.org/}
{http://www.freepascal.org} is the main
site. It contains also useful mail addresses and
links to other places.
It also contains the instructions for subscribing to the
\textit{mailinglist}.

\item
\seeurl{http://community.freepascal.org:10000/}
{http://community.freepascal.org:10000/} is a forum site where
questions can be posted.
\end{itemize}
Other than that, some mirrors exist.

Finally, if you think something should be added to this manual
(entirely possible), please do not hesitate and contact me at
\seeurl{michael@freepascal.org}{mailto:michael@freepascal.org}.
.

Let's get on with something useful.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Installation
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{Installing the compiler}
\label{ch:Installation}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Before Installation : Requirements
\section{Before Installation : Requirements}

%
% System requirements
%
\subsection{Hardware requirements}
The compiler needs at least one of the following processors:
\begin{enumerate}
\item An Intel 80386 or higher processor. A coprocessor 
is not required, although it will slow down your program's performance if you do 
floating point calculations without a coprocessor, since emulation will be used.
\item An AMD64 or EMT64 processor. 
\item A PowerPC processor. 
\item A SPARC processor
\item An ARM processor.
\item Older FPC versions exist for the motorola 68000 processor, 
but these are no longer maintained.
\end{enumerate}


Memory and disk requirements:
\begin{enumerate}
\item 8 Megabytes of free memory. This is sufficient to allow compilation of small programs. 
\item Large programs (such as the compiler itself) will require at least 64 MB. 
of memory, but 128MB is recommended. 
(Note that the compiled programs themselves do not need so much memory.)
\item At least 80 MB free disk space. 
When the sources are installed, another 270 MB are needed.
\end{enumerate}

% Software requirements
\subsection{Software requirements}

\subsubsection{Under DOS}
The \dos distribution contains all the files you need to run the compiler
and compile Pascal programs.

\subsubsection{Under UNIX}
Under \unix systems (such as \linux) you need to have the following programs 
installed :
\begin{enumerate}
\item \gnu \file{as}, the \gnu assembler.
\item \gnu \file{ld}, the \gnu linker.
\item Optionally (but highly recommended) : \gnu \file{make}. For easy
recompiling of the compiler and Run-Time Library, this is needed.
\end{enumerate}

\subsubsection{Under Windows}
The \windows distributions (both 32 and 64 bit) contain all the files you need to run the compiler
and compile Pascal programs. However, it may be a good idea to install
the \file{mingw32} tools or the \var{cygwin} development tools. Links
to both of these tools can be found on \var{http://www.freePascal.org}

\subsubsection{Under OS/2}
While the \fpc distribution comes with all necessary tools, it is a good
idea to install the EMX extender in order to compile and run
programs with the Free Pascal compiler. The EMX extender can be found on:\\
\var{ftp://hobbes.nmsu.edu/pub/os2/dev/emx/v0.9d}

\subsubsection{Under Mac OS X}
Mac OS X 10.1 or higher is required, and the developer tools or XCode 
should be installed.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Installing the compiler.
\section{Installing the compiler.}
The installation of \fpc is easy, but is platform-dependent.
We discuss the process for each platform separately.

% Installing under DOS
\subsection{Installing under Windows}
For \windows, there is a \windows installer, \file{setup.exe}. This is a
normal installation program, which offers the usual options
of selecting a directory, and which parts of the distribution you want
to install. It will, optionally, associate the \file{.pp} or \var{.pas}
extensions with the text mode IDE.

It is not recommended to install the compiler in a directory which
has spaces in it's path name. Some of the external tools do not support
filenames with spaces in them, and you will have problems creating
programs.

\subsection{Installing under DOS or OS/2}
\subsubsection{Mandatory installation steps.}
First, you must get the latest distribution files of \fpc. They come as zip
files, which you must unzip first, or you can download the compiler as a
series of separate files. This is especially useful if you have a slow
connection, but it is also nice if you want to install only some parts of the
compiler distribution.  The distribution zip files for DOS or OS/2 contain an
installation program \file{INSTALL.EXE}. You must run this program to install
the compiler.

The screen of the DOS or OS/2 installation program looks like figure 
\ref{fig:install1}.

\FPCpic{The \dos install program screen}{}{install1}
\FPCpic{}{}{install2}

The program allows you to select:
\begin{itemize}
\item What components you wish to install. e.g do you want the sources or
not, do you want docs or not. Items that you didn't download when
downloading as separate files, will not be enabled, i.e. you can't
select them.

\item Where you want to install (the default location is \verb|C:\PP|).
\end{itemize}

In order to run \fpc from any directory on your system, you must extend
your path variable to contain the \verb|C:\PP\BIN| directory.
Usually this is done in the \file{AUTOEXEC.BAT} file.
It should look something like this :
\begin{verbatim}
  SET PATH=%PATH%;C:\PP\2.2\BIN\i386-DOS
\end{verbatim}
for \dos or 
\begin{verbatim}
  SET PATH=%PATH%;C:\PP\2.2\BIN\i386-OS2
\end{verbatim}
for \ostwo.
(Again, assuming that you installed in the default location).

On \ostwo, \fpc installs some libraries from the EMX package if they
were not yet installed. (The installer will notify you if they should be
installed). They are located in the 
\begin{verbatim}
C:\PP\DLL
\end{verbatim}
directory. The name of this directory should be added to the \var{LIBPATH}
directive in the \file{config.sys} file:
\begin{verbatim}
LIBPATH=XXX;C:\PP\DLL
\end{verbatim}
Obviously, any existing directories in the \var{LIBPATH} directive
(indicated by \var{XXX} in the above example) should be preserved.

\subsubsection{Optional Installation: The coprocessor emulation}
For people who have an older CPU type, without math coprocessor (i387)
it is necessary to install a coprocessor emulation, since \fpc uses the
coprocessor to do all floating point operations.

The installation of the coprocessor emulation is handled by the
installation program (\file{INSTALL.EXE}) under \dos and \windows.

%
% Installing under Linux
%
\subsection{Installing under Linux}
\subsubsection{Mandatory installation steps.}
The \linux distribution of \fpc comes in three forms:
\begin{itemize}
\item a \file{tar.gz} version, also available as separate files.
\item a \file{.rpm} (Red Hat Package Manager) version, and
\item a \file{.deb} (Debian) version.
\end{itemize}

If you use the \file{.rpm} format, installation is limited to
\begin{verbatim}
rpm -i fpc-X.Y.Z-N.ARCH.rpm
\end{verbatim}
Where \var{X.Y.Z} is the version number of the \file{.rpm} file, 
and \var{ARCH} is one of the supported architectures (i386, x86\_64 etc.).

If you use Debian, installation is limited to
\begin{verbatim}
dpkg -i fpc-XXX.deb
\end{verbatim}
Here again, \var{XXX} is the version number of the \file{.deb} file.

You need root access to install these packages. The \file{.tar} file
allows you to do an installation below your home directory if you 
don't have root permissions.

When downloading the \var{.tar} file, or the separate files,
installation is more interactive.

In case you downloaded the \file{.tar} file, you should first untar
the file, in some directory where
you have write permission, using the following command:
\begin{verbatim}
tar -xvf fpc.tar
\end{verbatim}
We supposed here that you downloaded the file \file{fpc.tar} somewhere
from the Internet. (The real filename will have some version number in it,
which we omit here for clarity.)

When the file is untarred, you will be left with more archive files, and
an install program: an installation shell script.

If you downloaded the files as separate files, you should at least download
the \file{install.sh} script, and the libraries (in \file{libs.tar.gz}).

To install \fpc, all that you need to do now is give the following command:
\begin{verbatim}
./install.sh
\end{verbatim}
And then you must answer some questions. They're very simple, they're
mainly concerned with 2 things :
\begin{enumerate}
\item Places where you can install different things.
\item Deciding if you want to install certain components (such as sources
and demo programs).
\end{enumerate}
The script will automatically detect which components are present and can be
installed. It will only offer to install what has been found.
Because of this feature, you must keep the original names when downloading,
since the script expects this.

If you run the installation script as the \var{root} user, you can just accept all installation
defaults. If you don't run as \var{root}, you must take care to supply the
installation program with directory names where you have write permission,
as it will attempt to create the directories you specify.
In principle, you can install it wherever you want, though.

At the end of installation, the installation program will generate a
configuration file (\file{fpc.cfg}) for the \fpc compiler which 
reflects the settings that you chose. It will install this file in 
the \file{/etc} directory or in your home directory (with name
\file{.fpc.cfg}) if you do not have write permission in the \file{/etc}
directory. It will make a copy in the directory where you installed the 
libraries.

The compiler will first look for a file \file{.fpc.cfg} in your home 
directory before looking in the \file{/etc} directory.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Optional configuration
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Optional configuration steps}
On any platform, after installing the compiler you may wish to set
some environment variables. The \fpc compiler recognizes the 
following variables :

\begin{itemize}
\item \verb|PPC_EXEC_PATH| contains the directory where support files for
the compiler can be found.
\item \verb|PPC_CONFIG_PATH| specifies an alternate path to find the \file{fpc.cfg}.
\item \verb|PPC_ERROR_FILE|  specifies the path and name of the error-definition file.
\item \verb|FPCDIR| specifies the root directory of the \fpc installation.
(e.g : \verb|C:\PP\BIN|)
\end{itemize}

These locations are, however, set in the sample configuration file which is
built at the end of the installation process, except for the
\verb|PPC_CONFIG_PATH| variable, which you must set if you didn't install
things in the default places.

\section{Before compiling}

Also distributed in \fpc is a README file. It contains the latest
instructions for installing \fpc, and should always be read first.

Furthermore, platform-specific information and common questions
are addressed in the \var{FAQ}. It should be read before reporting any 
bug.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Testing the compiler
\section{Testing the compiler}

After the installation is completed and the optional environment variables 
are set as described above, your first program can be compiled.

Included in the \fpc distribution are some demonstration programs,
showing what the compiler can do.
You can test if the compiler functions correctly by trying to compile
these programs.

The compiler is called
\begin{itemize}
\item \file{fpc.exe} under \windows, \ostwo and \dos.
\item \file{fpc} under most other operating systems.
\end{itemize}
To compile a program (e.g \verb|demo\text\hello.pp|), copy the program
to your current working directory, and simply type :
\begin{verbatim}
  fpc hello
\end{verbatim}
at the command prompt. If you don't have a configuration file, then you may
need to tell the compiler where it can find the units, for instance as
follows:
\begin{verbatim}
fpc -Fuc:\pp\NNN\units\i386-go32v2\rtl hello
\end{verbatim}
under \dos, and under \linux you could type
\begin{verbatim}
fpc -Fu/usr/lib/fpc/NNN/units/i386-linux/rtl hello
\end{verbatim}
(replace \var{NNN} with the version number of \fpc that you are using).
This is, of course, assuming that you installed under \verb|C:\PP| or
\file{/usr/lib/fpc/NNN}, respectively.

If you got no error messages, the compiler has generated an executable
called \file{hello.exe} under \dos, \ostwo or \windows, or \file{hello} 
(no extension) under \unix and most other operating systems.

To execute the program, simply type :
\begin{verbatim}
  hello
\end{verbatim}
or
\begin{verbatim}
  ./hello
\end{verbatim}
on Unices (where the current directory usually is not in the PATH). 

If all went well, you should see the following friendly greeting:
\begin{verbatim}
Hello world
\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Usage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Compiler usage}
\label{ch:Usage}

Here we describe the essentials to compile a program and a unit.
For more advanced uses of the compiler, see the section on configuring 
the compiler, and the \progref{}.

The examples in this section suppose that you have an \file{fpc.cfg} which
is set up correctly, and which contains at least the path setting for the
RTL units. In principle this file is generated by the installation program.
You may have to check that it is in the correct place. (see section
\ref{se:configfile} for more information on this.)

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Where the compiler looks for its files.
\section{File searching}
Before you start compiling a program or a series of units, it is
important to know where the compiler looks for its source files and other
files. In this section we discuss this, and we indicate how to influence
this.

\begin{remark}
The use of slashes (/) and backslashes (\verb+\+) as directory separators
is irrelevant, the compiler will convert to whatever character is used on
the current operating system. Examples will be given using slashes, since
this avoids problems on \unix systems (such as \linux).
\end{remark}

% Command line files.
\subsection{Command line files}
The file that you specify on the command line, such as in
\begin{verbatim}
fpc foo.pp
\end{verbatim}
will be looked for ONLY in the current directory. If you specify a directory
in the filename, then the compiler will look in that directory:
\begin{verbatim}
fpc subdir/foo.pp
\end{verbatim}
will look for \file{foo.pp} in the subdirectory \file{subdir} of the current
directory.

Under case sensitive file systems (such as \linux and \unix), the name of this 
file is case sensitive; under other operating systems (such as \dos, \windowsnt, \ostwo) 
this is not the case.

% Unit files.
\subsection{Unit files}
\label{se:unitsearching}

When you compile a unit or program that needs other units, the compiler will
look for compiled versions of these units in the following way:
\begin{enumerate}
\item It will look in the current directory.
\item It will look in the directory where the source file resides.
\item It will look in the directory where the compiler binary is.
\item It will look in all the directories specified in the unit search path.
\end{enumerate}

You can add a directory to the unit search path with the (\seeo{Fu})
option. Every occurrence of one of these options will {\em insert}
a directory to the unit search path. i.e. the last path on the command line
will be searched first.

The compiler adds several paths to the unit search path:
\begin{enumerate}
\item The contents of the environment variable \var{XXUNITS}, where \var{XX}
must be replaced with one of the supported targets: \var{GO32V2},
\var{LINUX},\var{WIN32}, \var{OS2}, \var{BEOS}, \var{FREEBSD}, \var{NETBSD}.
\item The standard unit directory. This directory is determined
from the \var{FPCDIR} environment variable. If this variable is not set,
then it is defaulted to the following:
\begin{itemize}
\item On \linux:
\begin{verbatim}
  /usr/local/lib/fpc/FPCVERSION
or
  /usr/lib/fpc/FPCVERSION
\end{verbatim}
whichever is found first.
\item On other OSes: the compiler binary directory, with '../' appended
to it, if it exists. For instance, on Windows, this would mean
\begin{verbatim}
C:\FPC\2.2\units\i386-win32
\end{verbatim}
This is assuming the compiler was installed in the directory
\begin{verbatim}
C:\FPC\2.2
\end{verbatim}
\end{itemize}
After this directory is determined , the following paths are added to the
search path:
\begin{enumerate}
\item FPCDIR/units/FPCTARGET
\item FPCDIR/units/FPCTARGET/rtl
\end{enumerate}
Here target must be replaced by the name of the target you are compiling
for: this is a combination of CPU and OS, so for instance
\begin{verbatim}
/usr/local/lib/fpc/2.2/units/i386-linux/
\end{verbatim}
or, when cross-compiling
\begin{verbatim}
/usr/local/lib/fpc/2.2/units/i386-win32/
\end{verbatim}
\end{enumerate}

The \var{-Fu} option accepts a single \var{*} wildcard, which will be
replaced by all directories found on that location, but {\em not} the
location itself.
For example, given the directories
\begin{verbatim}
rtl/units/i386-linux
fcl/units/i386-linux
packages/base
packages/extra
\end{verbatim}
the command
\begin{verbatim}
fpc -Fu"*/units/i386-linux"
\end{verbatim}
will have the same effect as
\begin{verbatim}
fpc -Furtl/units/i386-linux -Fufcl/units/i386-linux
\end{verbatim}
since both the \file{rtl} and \file{fcl} directories contain further
\file{units/i386-linux} subdirectories. The packages directory will not be
added, since it doesn't contain a \file{units/i386-linux} subdirectory.

The following command
\begin{verbatim}
fpc -Fu"units/i386-linux/*"
\end{verbatim}
will match any directory below the \file{units/i386-linux} directory, 
but will not match the \file{units/i386-linux} directory itself, so
you should add it manually if you want the compiler to look for files
in this directory as well:
\begin{verbatim}
fpc -Fu"units/i386-linux" -Fu"units/i386-linux/*"
\end{verbatim}

Note that (for optimization) the compiler will drop any non-existing paths 
from the search path, i.e. the existence of the path (after wildcard and
environment variable expansion) will be tested.

You can see what paths the compiler will search by giving the compiler
the \var{-vu} option.

On systems where filenames are case sensitive (such as \unix and \linux), 
the compiler will :
\begin{enumerate}
\item Search for the original file name, i.e. preserves case.
\item Search for the filename all lowercased.
\item Search for the filename all uppercased.
\end{enumerate}
This is necessary, since Pascal is case-independent, and the statements 
\var{Uses Unit1;} or \var{uses unit1;} should have the same effect.

It will do this first with the extension \file{.ppu} (the compiled unit),
\file{.pp} and then with the extension \file{.pas}.

For instance, suppose that the file \file{foo.pp} needs the unit
\file{bar}. Then the command
\begin{verbatim}
fpc -Fu.. -Fuunits foo.pp
\end{verbatim}
will tell the compiler to look for the unit \file{bar} in the following
places:
\begin{enumerate}
\item In the current directory.
\item In the directory where the compiler binary is (not under \linux).
\item In the parent directory of the current directory.
\item In the subdirectory \file{units} of the current directory
\item In the standard unit directory.
\end{enumerate}

Also, unit names that are longer than 8 characters will first be looked for
with their full length. If the unit is not found with this name, the name
will be truncated to 8 characters, and the compiler will look again in the
same directories, but with the truncated name.


If the compiler finds the unit it needs, it will look for the source file of
this unit in the same directory where it found the unit.
If it finds the source of the unit, then it will compare the file times.
If the source file was modified more recent than the unit file, the
compiler will attempt to recompile the unit with this source file.

If the compiler doesn't find a compiled version of the unit, or when the
\var{-B} option is specified, then the compiler will look in the same
manner for the unit source file, and attempt to recompile it.

It is recommended to set the unit search path in the configuration file
\file{fpc.cfg}. If you do this, you don't need to specify the unit search
path on the command line every time you want to compile something.

% Include files.
\subsection{Include files}
If you include a file in your source with the \var{\{\$I filename\}}
directive, the compiler will look for it in the following places:

\begin{enumerate}
\item It will look in the path specified in the include file name.
\item It will look in the directory where the current source file is.
\item it will look in all directories specified in the include file search
path.
\end{enumerate}
You can add files to the include file search path with the \seeo{I} or
\seeo{Fi} options.

As an example, consider the following include statement in a file
\file{units/foo.pp}:
\begin{verbatim}

{$i ../bar.inc}

\end{verbatim}
Then the following command :
\begin{verbatim}
fpc -Iincfiles units/foo.pp
\end{verbatim}
will cause the compiler to look in the following directories for
\file{bar.inc}:
\begin{enumerate}
\item The parent directory of the current directory.
\item The \file{units} subdirectory of the current directory.
\item The \file{incfiles} subdirectory of the current directory.
\end{enumerate}

% Object files.
\subsection{Object files}
When you link to object files (using the \var{\{\$L file.o\}} directive,
the compiler will look for this file in the same way as it looks for include
files:

\begin{enumerate}
\item It will look in the path specified in the object file name.
\item It will look in the directory where the current source file is.
\item It will look in all directories specified in the object file search path.
\end{enumerate}
You can add files to the object file search path with the \seeo{Fo} option.

% Configuration file
\subsection{Configuration file}
\label{searchconfig}

Not all options must be given on the compiler command line. The compiler
can use a configuration file which can contain the same options as on the
command line. Unless you specify the \seeo{n} option, the compiler will look
for a configuration file \file{fpc.cfg} in the following places:

\begin{itemize}
\item Under \unix (such as \linux)
\begin{enumerate}
\item The current directory.
\item Your home directory, it looks for \file{.fpc.cfg}.
\item The directory specified in the environment 
variable \var{PPC\_CONFIG\_PATH}, and if it is not set, it will look in the 
\file{etc} directory above the compiler directory. (For instance, if the
compiler is in \file{/usr/local/bin}, it will look in \file{/usr/local/etc})
\item The directory \file{/etc}.
\end{enumerate}
\item Under all other OSes:
\begin{enumerate}
\item The current directory.
\item If it is set, the directory specified in the environment variable
\var{PPC\_CONFIG\_PATH}.
\item The directory where the compiler is.
\end{enumerate}
\end{itemize}

Versions prior to version 1.0.6 of the compiler used a configuration
file \file{ppc386.cfg}. This file is still searched, but its usage 
is considered deprecated. For compatibility, \file{fpc.cfg} will
be searched first, and if not found, the file \file{ppc386.cfg}
will be searched and used.

\begin{remark}
The searching for \file{ppc386.cfg} will be removed from the compiler
in version 2.4.0. To indicate this, the compiler gives a warning as of
version 2.3.1 if it uses a \file{ppc386.cfg} configuration file.
\end{remark}


\subsection{About long filenames}
\fpc can handle long filenames on all platforms, except DOS.
On Windows, it will use support for long filenames if it is available
(which is not always the case on older versions of Windows).

If no support for long filenames is present, it will truncate unit names
to 8 characters.

It is not recommended to put units in directories that contain spaces in
their names, since the external GNU linker doesn't understand such filenames.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Compiling a program
\section{Compiling a program}
Compiling a program is very simple. Assuming that you have a program source
in the file \file{prog.pp}, you can compile this with the following command:
\begin{verbatim}
  fpc [options] prog.pp
\end{verbatim}
The square brackets \var{[\ ]} indicate that what is between them is optional.

If your program file has the \file{.pp} or \file{.pas} extension,
you can omit this on the command line, e.g. in the previous example you
could have typed:
\begin{verbatim}
  fpc [options] prog
\end{verbatim}

If all went well, the compiler will produce an executable file. You can execute 
it straight away; you don't need to do anything else. 

You will notice that there is also another file in your directory, with
extension \file{.o}. This contains the object file for your program.
If you compiled a program, you can delete the object file (\file{.o}),
but don't delete it if you compiled a unit. This is because
the unit object file contains the code of the unit, and will be
linked in any program that uses it.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Compiling a unit
\section{Compiling a unit}

Compiling a unit is not essentially different from compiling a program.
The difference is mainly that the linker isn't called in this case.

To compile a unit in the file \file{foo.pp}, just type :
\begin{verbatim}
  fpc  foo
\end{verbatim}
Recall the remark about file extensions in the previous section.

When all went well, you will be left with 2 (two) unit files:
\begin{enumerate}
\item \file{foo.ppu} - this is the file describing the unit you just
compiled.
\item \file{foo.o} - this file contains the actual code of the unit.
This file will eventually end up in the executables.
\end{enumerate}
Both files are needed if you plan to use the unit for some programs.
So don't delete them. If you want to distribute the unit, you must
provide both the \file{.ppu} and \file{.o} file. One is useless without the
other.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Units libraries and smartlinking
\section{Units, libraries and smartlinking}
The \fpc compiler supports smartlinking and the creation of libraries.
However, the default behaviour is to compile each unit into one big object
file, which will be linked as a whole into your program.
Shared libraries can be created on most platforms, although current level
of FPC support may vary (they are e.g. not supported for GO32v2 and OS2
targets).

It is also possible to take existing units and put them
together in 1 static or shared library (using the \file{ppumove} tool,
\sees{ppumove}).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Reducing the size of your program
\section{Reducing the size of your program}

When you created your program, it is possible to reduce the size of the
resulting executable. This is possible, because the compiler leaves a 
lot of information in the program which, strictly speaking, isn't required 
for the execution of the program. 

The surplus of information can be removed with a small program
called \file{strip}.The usage is simple. Just type
\begin{verbatim}
strip prog
\end{verbatim}
On the command line, and the \file{strip} program will remove all unnecessary
information from your program. This can lead to size reductions of up to
30 \%.

%\begin{remark}
%In the \win version, \file{strip} is called \file{stripw}.
%\end{remark}
You can use the \var{-Xs} switch to let the compiler do this stripping
automatically at program compile time. (The switch has no effect when
compiling units.)

Another technique to reduce the size of a program is to use smartlinking.
Normally, units (including the system unit) are linked in as a whole.
It is however possible to compile units such that they can be smartlinked.
This means that only the functions and procedures that are actually used
are linked in your program, leaving out any unnecessary code. The compiler 
will turn on smartlinking with the \seeo{XX} switch. This technique is 
described in full in the programmers guide. 

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Problems
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Compiling problems}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% General problems
\section{General problems}
\begin{itemize}
\item \textbf{IO-error -2 at ...} : Under \linux you can get this message at
compiler startup. It means typically that the compiler doesn't find the
error definitions file. You can correct this mistake with the \seeo{Fr}
option under \linux.
\item \textbf {Error : File not found : xxx} or \textbf{Error: couldn't compile
unit xxx}: This typically happens when
your unit path isn't set correctly. Remember that the compiler looks for
units only in the current directory, and in the directory where the compiler
itself is. If you want it to look somewhere else too, you must explicitly
tell it to do so using the \seeo{Fu} option. Or you must set up a 
configuration file.
\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Problems you may encounter under DOS
\section{Problems you may encounter under DOS}
\begin{itemize}
\item \textbf{No space in environment}.\\
An error message like this can occur if you call
\verb|SET_PP.BAT| in \file{AUTOEXEC.BAT}.\\
To solve this problem, you must extend your environment memory.
To do this, search a line in \file{CONFIG.SYS} like
\begin{verbatim}
SHELL=C:\DOS\COMMAND.COM
\end{verbatim}
and change it to the following:
\begin{verbatim}
SHELL=C:\DOS\COMMAND.COM /E:1024
\end{verbatim}
You may just need to specify a higher value, if this parameter is already set.
\item \textbf{ Coprocessor missing}\\
If the compiler writes
a message that there is no coprocessor, install
the coprocessor emulation.
\item \textbf{Not enough DPMI memory}\\
If you want to use the compiler with \var{DPMI} you must have at least
7-8 MB free \var{DPMI} memory, but 16 Mb is a more realistic amount.
\end{itemize}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Configuration.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Compiler configuration}
\label{ch:CompilerConfiguration}

The output of the compiler can be controlled in many ways. This can be done
essentially in two distinct ways:
\begin{itemize}
\item Using command line options.
\item Using the configuration file: \file{fpc.cfg}.
\end{itemize}
The compiler first reads the configuration file. Only then are the command line
options checked. This creates the possibility to set some basic options
in the configuration file, and at the same time you can still set some
specific options when compiling some unit or program. First we list the
command line options, and then we explain how to specify the command
line options in the configuration file. When reading this, keep in mind
that the options are case sensitive. 


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Using the command line options
\section{Using the command line options}

The available options for the current version of the compiler are listed by
category. Also, see \seec{commandlineoptions} for a listing as generated by 
the current compiler.

%
% General options
%

\subsection{General options}
\begin{description}
\item[-h] Print a list of all options and exit.
\olabel{h}
\item[-?] Same as \var{-h}, waiting after each screenfull for the enter key.
\item[-i] Print copyright and other information. You can supply a qualifier, 
\olabel{i} as \var{-ixxx} where xxx can be one of the following:
\begin{description}
\item[D] : Returns the compiler date.
\item[V] : Returns the short compiler version.
\item[W] : Return full compiler version.
\item[SO] : Returns the compiler OS.
\item[SP] : Returns the compiler processor.
\item[TO] : Returns the target OS.
\item[TP] : Returns the target processor.
\end{description}
\item[-l]  Print the Free Pascal logo and version number.
\olabel{l}
\item [-n] Ignore the default configuration file.
You can still pass a configuration file with the \var{@} option.
\olabel{n}
\end{description}

%
% Options for getting feedback
%
\subsection{Options for getting feedback}
\label{se:feedbackoptions}
\begin{description}
\item[-vxxx] Be verbose. \var{xxx} is a combination of the following :
\olabel{v}
\begin{itemize}
\item \var{e} : Show errors. This option is on by default.
\item \var{i} : Display some general information.
\item \var{w} : Issue warnings.
\item \var{n} : Issue notes.
\item \var{h} : Issue hints.
\item \var{i} : Issue informational messages.
\item \var{l} : Report number of lines processed (every 100 lines).
\item \var{u} : Show information on units being loaded.
\item \var{t} : Show names of files being opened.
\item \var{p} : Show names of procedures and functions being processed.
\item \var{q} : Show message numbers.
\item \var{c} : Notify on each conditional being processed.
\item \var{mxxx} : \var{xxx} is a comma-separated list of messages numbers which should not be shown.
This option can be specified multiple times.
\item \var{d} : Show additional debugging information.
\item \var{0} : No messages. This is useful for overriding the default
          setting in the configuration file.
\item \var{b} : Show all procedure declarations if an overloaded function
error occurs.
\item \var{x} : Show information about the executable (Win32 platform only).
\item \var{r} : Format errors in RHIDE/GCC compatibility mode.
\item \var{a} : Show all possible information. (this is the same as specifying all options)
\item \var{b} : Tells the compiler to write filenames using the full path.
\item \var{v} : Write copious debugging information to file.
\file{fpcdebug.txt}..
\item \var{s} : Write timestamps.
Mainly for the compiler developers.
%\item \var{p} Write parse tree to file tree.log. (Intended for compiler  developers.)
\end{itemize}
\end{description}
%
% 
The difference between an error/fatal error/hint/warning/note is the severity:
\begin{description}
\item[Fatal] The compiler encountered an error, and can no longer continue
compiling. It will stop at once.
\item[Error] The compiler encountered an error, but can continue to compile
(at most till the end of the current unit).
\item[Warning] if there is a warning, it means there is probably an error,
i.e. something may be wrong in your code.
\item[Hint] Is issued if the compiler thinks the code could be better, but
there is no suspicion of error.
\item[Note] Is some noteworthy information, but again there is no error.
\end{description}
The difference between hints and notes is not really very clear. Both can
be ignored without too much risk, but warnings should always be checked.


%
% Options concerning files and directories
%
\subsection{Options concerning files and directories}
\begin{description}
\item [-exxx] Specify \file{xxx} as the directory containing the
executables for the programs \file{as} (the assembler) and \var{ld} (the linker).
\olabel{e}
\item[-FaXYZ] load units \var{XYZ} after the system unit, but before any other 
unit is loaded. \var{XYZ} is a comma-separated list of unit names. This can only be used
for programs, and has the same effect as if \var{XYZ} were inserted as the
first item in the program's \var{uses} clause.
\item[-FcXXX] Set the input codepage to \var{XXX}. Experimental.
\item[-FCxxx] Set the RC compiler (resource compiler) binary name to \file{xxx}.
\item[-Fd] Disable the compiler's internal directory cache. By default, the compiler caches the
names all files in a directory as soon as it looks for a single file in said directory. This ensures
that the correct case of all file names is used in the debug information and to create compiled
files when compiling on a case-preserving file systems under an OS that also support case-sensitive
file systems, and it can also increase performance. This feature can however cause severe slowdowns
on networked file systems, especially when compiling trivial programs in directories containing many
files, and such slowdowns can be addressed by disabling the cache using this switch.
\item [-FD] Same as \var{-e}.
\item [-Fexxx] Write errors, etc. to the file named \file{xxx}.
\olabel{Fe}
\item [-FExxx] Write the executable and units to directory \file{xxx} 
instead of the current directory. If this option
is followed by a  \var{-o} option \seeo{o}, and this option contains a path 
component, then the \var{-o} path will override the \var{-FE} setting.
\olabel{FE}
\item [-Ffxxx] Add \file{xxx} to the framework path (only for Darwin).
\item [-Fixxx] Add \file{xxx} to the include file search path.
\olabel{Fi}
\item [-Flxxx] Add \file{xxx} to the library search path. (This is also 
passed to the linker.)
\olabel{Fl}
\item[-FLxxx] (\linux only) Use \file{xxx} as the dynamic linker. The default is \file{/lib/ld-linux.so.2}, or
\file{/lib/ld-linux.so.1}, depending on which one is found first.
\olabel{FL}
\item[-Fmxxx] Load the unicode conversion table from file \file{x.txt} in
the directory where the compiler is located. Only used when \var{-Fc} is
also in effect.
\item[-Foxxx] Add \file{xxx} to the object file search path.
This path is used when looking for files that need to be linked in.
\olabel{Fo}
\item [-Frxxx] Specify \file{xxx} as the file which contain the compiler
messages. This will override the compiler's built-in default messages, which
are in english.
\olabel{Fr}
\item[-FRxxx] set the resource (.res) linker to \file{xxx}.
\item [-Fuxxx] Add \file{xxx} to the unit search path.
Units are first searched in the current directory.
If they are not found there then the compiler searches them in the unit path.
You must {\em always} supply the path to the system unit. The \file{xxx}
path can contain a single wildcard (*) which will be expanded to all
possible directory names found at that location. Note that the location
itself is not included in the list. See \sees{unitsearching} for more
information about this option.
\olabel{Fu}
\item [-FUxxx] Write units to directory \var{xxx} instead of the current 
directory. It overrides the \var{-FE} option.
\item [-Ixxx] \olabel{I} Add \file{xxx} to the include file search path.
This option has the same effect as \var{-Fi}.
%\item [-P] uses pipes instead of files when assembling. This may speed up
%the compiler on \ostwo and \linux. Only with assemblers (such as \gnu
%\file{as}) that support piping...
\item[-FWxxx] store generated Whole Program Optimization information in file
\file{xxx}.
\item[-Fwxxx] Read Whole Program Optimization information from file
\file{xxx}.
\end{description}

% Options controlling the kind of output.
\subsection{Options controlling the kind of output.}
\label{se:codegen}
For more information on these options, see \progref.
\begin{description}
\item [-a] \olabel{a} Do not delete the assembler files (not
applicable when using the internal assembler). This also applies
to the (possibly) generated batch script.
\item [-al] \olabel{al} Include the source code lines in the assembler
file as comments.
\item[-an] \olabel{an} Write node information in the
assember file (nodes are the way the compiler represents statements or parts
thereof internally). This is primarily intended for debugging
the code generated by the compiler.
\item[-ap] \olabel{ap} Use pipes instead of creating temporary assembler
files.  This may speed up the compiler on \ostwo and \linux. 
Only with assemblers (such as \gnu %\file{as}) that support piping, and not
if the internal assembler is used.
\item[-ar] \olabel{ar} List register allocation and
release info in the assembler file. This is primarily intended for debugging
the code generated by the compiler.
\item[-at] \olabel{at} List information about
temporary allocations and deallocations in the assembler file.
\item [-Axxx] \olabel{A} specify what kind of assembler should be generated. 
Here \var{xxx} is one of the following :
\begin{description}
\item[default] Use the built-in default.
\item[as] Assemble using \gnu as.
\item[nasmcoff] Coff (Go32v2) file using Nasm.
\item[nasmelf] Elf32 (\linux) file using Nasm.
\item[nasmwin32] \windows 32-bit file using Nasm.
\item[nasmwdosx] \windows 32-bit/DOSX file using Nasm.
\item[nasmobj] Object file using Nasm.
\item[masm] Object file using Masm (Microsoft).
\item[tasm] Object file using Tasm (Borland).
\item[elf] Elf32 (\linux) using internal writer.
\item[coff] Coff object file (Go32v2) using the internal binary object writer.
\item[pecoff] PECoff object file (Win32) using the internal binary object writer.
\end{description}
\item[-B] \olabel{B} Re-compile all used units, even
if the unit sources didn't change since the last compilation.
\item[-b] \olabel{b} Generate browser info. This information can
be used by an Integrated Development Environment (IDE) to provide information
on classes, objects, procedures, types  and variables in a unit.
\item[-bl] \olabel{bl} The same as \var{-b} but also generates
information about local variables, types and procedures.
\item[-Caxxx] Set the ABI (Application Binary Interface) to \file{xxx}. 
The \var{-i} option gives the possible values  for \file{xxx}.
\item[-Cb] Generate big-endian code.
\item[-Cc] Set the default calling convention used by the compiler.
\item [-CD] Create a dynamic library. This is used to transform units into
dynamically linkable libraries on \linux.
\item[-Ce] Emulate floating point operations.
\item[-Cfxxx] Set the used floating point processor to \file{xxx}.
\item[-CFNN] Set the minimal floating point precision to \var{NN}. Possible
values are 32 and 64.
\item[-Cg] Enable generation of PIC code. This should only be necessary when
generating libraries on \linux or other Unices.
\item [-Chxxx] \olabel {Ch} Reserves \var{xxx} bytes heap. \var{xxx} should
be between 1024 and 67107840.
\item [-Ci] \olabel{Ci} Generate Input/Output checking code. In case some
input/output code of your program returns an error status, the program will
exit with a run-time error. Which error is generated depends on the I/O error.
\item [-Cn] \olabel{Cn} Omit the linking stage.
\item [-Co] \olabel{Co} Generate Integer overflow checking code. In case of
integer errors, a run-time error will be generated by your program.
\item [-CO] \olabel{CO} Check for possible overflow of integer operations.
\item [-CpXXX] Set the processor type to \var{XXX}.
\item [-CPX=N] Set the packing for \file{X} to N. X can be \var{PACKSET},
\var{PACKENUM} or \var{PACKRECORD}, and N can be a value of 1,2,4,8 or one
of the keywords \var{DEFAULT} or \var{NORMAL}.
\item [-Cr] \olabel{Cr} Generate Range checking code. If your program
accesses an array element with an invalid index, or if it increases an
enumerated type beyond its scope, a run-time error will be generated.
\item [-CR] \olabel{CR} Generate checks when calling methods to verify
if the virtual method table for that object is valid.
\item [-Csxxx] \olabel{Cs} Set stack size to \var{xxx}.
\item [-Ct] \olabel{Ct} Generate stack checking code. If your program
performs a faulty stack operation, a run-rime error will be generated.
\item [-CX] \olabel{Cx} Create a smartlinked unit when writing a unit.
Smartlinking will only link in the code parts that are actually needed by
the program. All unused code is left out. This can lead to substantially
smaller binaries.
\item [-dxxx] \olabel{d} Define the symbol name \var{xxx}. This can be used
to conditionally compile parts of your code.
\item [-D] Generate a DEF file (for OS/2).
\item [-Dd] Set the description of the executable/library (\windows).
\item [-Dv] Set the version of the executable/library (\windows).
\item [-E] \olabel{E} Same as \var{-Cn}.
\item [-g] \olabel{g} Generate debugging information for debugging with
\file{gdb}.
\item [-gc] Generate checks for pointers. This must be used with the
\var{-gh} command line option. When this options is enabled, it will verify 
that all pointer accesses are within the heap.
%\item [-gd] \olabel{gd} Generate debugging info for \file{dbx}.
\item [-gg] Same as \var{-g}.
\item [-gh] Use the heaptrc unit (see \unitsref). (Produces a report
about heap usage after the program exits)
\item [-gl] Use the lineinfo unit (see \unitsref). (Produces file
name/line number information if the program exits due to an error.)
\item[-goXXX] set debug information options. One of the options is
\var{dwarfsets}: It enables dwarf set debug information (this does not work
with \var{gdb} versions prior to 6.5.
\item [-gp] Preserve case in stabs symbol names. Default is to uppercase all
names.
\item [-gs] Write stabs debug information.
\item [-gt] Trash local variables. This writes a random value to local
variables at procedure start. This can be used to detect uninitialized
variables.
\item [-gv] Emit info for valgrind.
\item [-gw] Emit dwarf debugging info (version 2).
\item [-gw2] Emit dwarf debugging info (version 2).
\item [-gw3] Emit dwarf debugging info (version 3).
\item[-kxxx] Pass \var{xxx} to the linker. 
\item[-Oxxx] \olabel{O} Optimize the compiler's output; \var{xxx} can have one
of the following values :
\begin{description}
\item[aPARAM=VALUE] Specify alignment of structures and code. \var{PARAM}
determines what should be aligned; \var{VALUE} specifies the alignment
boundary. See the Programmer's Guide for a description of the possible
values.
\item[g] Optimize for size, try to generate smaller code.
\item[G] Optimize for time, try to generate faster code (default).
\item[r] Keep certain variables in registers (experimental, use with
caution).
\item[u] Uncertain optimizations
\item[1] Level 1 optimizations (quick optimizations).
\item[2] Level 2 optimizations (\var{-O1} plus some slower optimizations).
\item[3] Level 3 optimizations (\var{-O2} plus \var{-Ou}).
\item[oxxx] Specify  specific optimizations: \var{n} can be one of
\begin{description}
\item[REGVAR] Use register variables
\item[STACKFRAME] Skip stack frames
\item[LOOPUNROLL] unroll (small) loops
\item[TAILREC] change tail recursion to non-recursive loop.
\end{description}
\item[pxxx] select processor \var{xxx} to optimize for. \var{fpc -i} lists
all available processor instruction sets.
\item[Wxxx] Generate Whole-Program-Optimization information for feature \var{xxx}.
\var{fpc -i} will generate a list of possible values.
\item[wxxx] Perform  Whole-Program-Optimization information for feature
\var{xxx}. \var{fpc -i} will generate a list of possible values.
\item[s] Optimize for size rather than speed.
\end{description}
The exact effect of some of these optimizations can be found in the \progref.
\item [-oxxx] \olabel{o} Use \var{xxx} as the name of the output
file (executable). For use only with programs. The output filename can contain a
path, and if it does, it will override any previous \var{-FE} setting. If
the output filename does not contain a path, the \var{-FE} setting is
observed.
\item [-pg] \olabel{gp} Generate profiler code for \file{gprof}. This will
define the symbol \var{FPC\_PROFILE}, which can be used in conditional
defines.
\item [-s] \olabel{s} Do not call the assembler and linker.
Instead, the compiler writes a script, \file{PPAS.BAT} under \dos, or
\file{ppas.sh} under \linux, which can then be executed to produce an
executable. This can be used to speed up the compiling process or to debug
the compiler's output. This option can take an extra parameter, mainly
used for cross-compilation. It can have one of the following values:
\begin{description}
\item[h] Generate script to link on host. The generated script can be run on
the compilation platform (host platform).
\item[t] Generate script to link on target platform. The generated script
can be run on the target platform. (where the binary is intended to be run)
\item[r] Skip register allocation phase (optimizations will be disabled).
\end{description}
\item[-Txxx] \olabel{T} Specify the target operating system. \var{xxx} can be one of
the following:
\begin{itemize}
\item \textbf{emx} : OS/2 via EMX (and DOS via EMX extender).
\item \textbf{freebsd} : FreeBSD.
\item \textbf{go32v2} : \dos and version 2 of the DJ DELORIE extender.
\item \textbf{linux} : \linux.
\item \textbf{netbsd} : NetBSD.
\item \textbf{netware} : Novell Netware Module (clib).
\item \textbf{netwlibc} : Novell Netware Module (libc).
\item \textbf{openbsd} : OpenBSD.
\item \textbf{os2} : OS/2 (2.x) using the \var{EMX} extender.
\item \textbf{sunos} : SunOS/Solaris.
\item \textbf{watcom} : Watcom compatible DOS extender
\item \textbf{wdosx} : WDOSX extender.
\item \textbf{win32} : \windows 32 bit.
\item \textbf{wince} : \windows for handhelds (ARM processor).
\end{itemize}
The available list of targets depends on the actual compiler binary.
Use \var{fpc -i} to get a list of targets supported by the compiler binary.
\item [-uxxx] \olabel{u} Undefine the symbol \var{xxx}. This is the opposite
of the \var{-d} option.
\item [-Ur] \olabel{Ur} Generate release unit files. These files will not be
recompiled, even when the sources are available. This is useful when making
release distributions. This also overrides the \var{-B} option for release 
mode units.
\item[-W] Set some \windows or \ostwo attributes of the generated binary. It
can be one or more of the following
\begin{description}
\item[Bhhh] Set preferred base address to hhh (a hexadecimal address)
\item[C] Generate a console application (+) or a gui application (-).
\item[D] Force use of Def file for exports.
\item[F] Generate a FS application (+) or a console application (-).
\item[G] Generate a GUI application (+) or a console application (-).
\item[N] Do not generate a relocation section.
\item[R] Generate a relocation section.
\item[T] Generate a TOOL application (+) or a console application (-).
\end{description}
\item [-Xx] \olabel{X} Specify executable options. This tells the compiler what
kind of executable should be generated. The parameter \var{x}
can be one of the following:
\begin{itemize}
\item \textbf{c} : (\linux only) Link with the C library. You should only use this when
  you start to port \fpc to another operating system. \olabel{Xe}
\item \textbf{d} Do not use the standard library path. This is needed for
cross-compilation, to avoid linking with the host platform's libraries.
\item \textbf{D} : Link with dynamic libraries (defines the
\var{FPC\_LINK\_DYNAMIC} symbol) \olabel{XD}
\item \textbf{e} use external (GNU) linker.
\item \textbf{g} Create debug information in a separate file and add a debuglink section to executable.
\item \textbf{i} use internal linker.
\item \textbf{MXXX} : Set the name of the program entry routine.
The default is 'main'.
\item \textbf{m} : Generate linker map file.
\item \textbf{PXXX} : Prepend binutils names with  \var{XXX} for cross-compiling.
\item \textbf{rXXX} : Set library path to \var{XXX}.
\item \textbf{Rxxx} Prepend \file{xxx} to all linker search paths. (used for
cross compiling).
\item \textbf{s} : Strip the symbols from the executable. \olabel{Xs}
\item \textbf{S} : Link with static units (defines the \var{FPC\_LINK\_STATIC} symbol).
\olabel{XS}
\item \textbf{t} : Link static (passes the \var{-static} option to the linker). \olabel{Xt}
\item \textbf{X} : Link with smartlinked units (defines the
\var{FPC\_LINK\_SMART} symbol). \olabel{XX}
\end{itemize}
\end{description}

%
%

% Options concerning the sources (language options)

\subsection{Options concerning the sources (language options)}
\label{se:sourceoptions}
For more information on these options, see \progref
\begin{description}
\item[-Mmode] \olabel{M} Set language mode to \var{mode}, which can be one of the
following:
\begin{description}
\item[delphi] Try to be Delphi compatible. This is more strict
than the \var{objfpc} mode, since some \fpc extensions are switched off.
\item[fpc] Free Pascal dialect (default).
%\item[gpc] Try to be gpc compatible.
\item[macpas] Try to be compatible with Macintosh Pascal dialects.
\item[objfpc] Switch on some Delphi extensions. This is different from 
Delphi mode, because some \fpc constructs are still available.
\item[tp] Try to be TP/BP 7.0 compatible. This means no function overloading
etc.
\end{description}
\item[-Mfeature] \olabel{M} Select language feature \var{feature}.
As of FPC version 2.3.1, the \var{-M} command line switch can be used to select individual
language features. In that case, \var{feature} is one of the following keywords:
\begin{description}
\item[CLASS] Use object pascal classes.
\item[OBJPAS] Automatically include the ObjPas unit.
\item[RESULT] Enable the \var{Result} identifier for function results.
\item[PCHARTOSTRING] Allow automatic conversion of null-terminated strings
to strings,
\item[CVAR] Allow the use of the \var{CVAR} keyword.
\item[NESTEDCOMMENTS] Allow use of nested comments.
\item[CLASSICPROCVARS] Use classical procedural variables.
\item[MACPROCVARS] Use mac-style procedural variables.
\item[REPEATFORWARD] Implementation and Forward declaration must match completely.
\item[POINTERTOPROCVAR] Allow silent conversion of pointers to procedural
variables.
\item[AUTODEREF] Automatic (silent) dereferencing of typed pointers.
\item[INITFINAL] Allow use of \var{Initialization} and \var{Finalization}
\item[POINTERARITHMETICS] Allow use of pointer arithmetic.
\item[ANSISTRINGS] Allow use of ansistrings.
\item[OUT] Allow use of the \var{out} parameter type.
\item[DEFAULTPARAMETERS] Allow use of default parameter values.
\item[HINTDIRECTIVE] Support the hint directives (\var{deprecated}, \var{platform} etc.)
\item[DUPLICATELOCALS] ?
\item[PROPERTIES] Allow use of global properties.
\item[ALLOWINLINE] Allow inline procedures.
\item[EXCEPTIONS] Allow the use of exceptions.
\end{description}
The keyword can be followed by a plus or minus sign to enable or disable the
feature.
\item [-Rxxx] \olabel{R} Specify what kind of assembler you use in
your \var{asm} assembler code blocks. Here \var{xxx} is one of the following:
\begin{description}
\item [att\ ] \var{asm} blocks contain AT\&T-style  assembler.
This is the default style.
\item [intel] \var{asm} blocks contain Intel-style assembler.
\item [default] Use the default assembler for the specified target.
\item [direct] \var{asm} blocks should be copied as is in the assembler,
only replacing certain variables. 
\end{description}
\item [-S2] \olabel{Stwo} Switch on Delphi 2 extensions (\var{objfpc} mode). 
Deprecated, use \var{-Mobjfpc} instead.
\item [-Sa] \olabel{Sa} Include assert statements in compiled code. Omitting 
this option will cause assert statements to be ignored.
\item [-Sc] \olabel{Sc} Support C-style operators, i.e. \var{*=, +=, /= and
-=}.
\item [-Sd] \olabel{Sd} Try to be Delphi compatible. Deprecated, use
\var{-Mdelphi} instead. 
\item [-SeN] \olabel{Se} The compiler stops after the N-th error. Normally,
the compiler tries to continue compiling after an error, until 50 errors are
reached, or a fatal error is reached, and then it stops. With this switch,
the compiler will stop after the N-th error (if N is omitted, a default of 1
is assumed). Instead of a number, one of \var{n}, \var{h} or \var{w} can also be
specified. 
In that case the compiler will consider notes, hints or warnings as errors and 
stop when one is encountered.
\item [-Sg] \olabel{Sg} Support the \var{label} and \var{goto} commands. By
default these are not supported. You must also specify this option if you
use labels in assembler statements. (if you use the \var{AT\&T} style
assember)
\item [-Sh] Use ansistrings by default for strings. If this option is
specified, the compiler will interpret the \var{string} keyword as an
ansistring. Otherwise it is supposed to be a shortstring (TP style).
\item [-Si] \olabel{Si} Support \var{C++} style INLINE.
\item [-SIXXX] Set interfaces style to XXX.
\item [-Sk] Load the Kylix compatibility unit (\file{fpcylix}).
\item [-Sm] \olabel{Sm} Support C-style macros.
\item [-So] \olabel{So} Try to be Borland TP 7.0 compatible. Deprecated, use
\var{-Mtp} instead.
%\item [-Sp] \olabel{Sp} Try to be \file{gpc} (\gnu Pascal compiler)
%compatible. Deprecated, use \var{-Mgpc} instead.
\item [-Ss] \olabel{Ss} The name of constructors must be \var{init}, and the
name of destructors should be \var{done}.
\item [-St] \olabel{St} Allow the \var{static} keyword in objects.
\item [-Sx] Enable exception keywords (default in Delphi/Objfpc mode). This
will mark all exception related keywords as keywords, also in \tp or
\file{FPC} mode. This can be used to check for code which should be
mode-neutral as much as possible.
\item [-Un] \olabel{Un} Do not check the unit name. Normally, the unit name
is the same as the filename. This option allows them to be different.
\item [-Us] \olabel{Us} Compile a system unit. This option causes the
compiler to define only some very basic types.
\end{description}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Using the configuration file
\section{Using the configuration file}
\label{se:configfile}
Using the configuration file \file{fpc.cfg} is an alternative to command
line options. When a configuration file is found, it is read, and the lines
in it are treated as if you typed them on the command line. They are treated
before the options that you type on the command line.

You can specify comments in the configuration file with the \var{\#} sign.
Everything from the \var{\#} on will be ignored.

The algorithm to determine which file is used as a configuration file
is decribed in \ref{searchconfig} on page \pageref{searchconfig}.

When the compiler has finished reading the configuration file, it continues
to treat the command line options. 

One of the command line options allows you to specify a second configuration
file: Specifying \file{@foo} on the command line will open file \file{foo},
and read further options from there. When the compiler has finished reading
this file, it continues to process the command line.

The configuration file allows a type of preprocessing. It understands the
following directives, which you should place starting on the first column of a line:
\begin{description}
\item [\#IFDEF]
\item [\#IFNDEF]
\item [\#ELSE]
\item [\#ENDIF]
\item [\#DEFINE]
\item [\#UNDEF]
\item [\#WRITE]
\item [\#INCLUDE]
\item [\#SECTION]
\end{description}
They work the same way as their \{\$...\}  counterparts in Pascal source code. 
All the default defines used to compile source code are also defined while 
processing the configuration file. For example, if the target compiler is an 
intel 80x86 compatible linux platform, both \var{cpu86} and \var{linux} will be 
defined while interpreting the configuration file. For the possible default 
defines when compiling, consult Appendix G of the \progref.


What follows is a description of the different directives.

\subsection{\#IFDEF}
Syntax:
\begin{verbatim}
#IFDEF name
\end{verbatim}
Lines following \var{\#IFDEF} are read only if the keyword \var{name}
following it is defined.

They are read until the keywords \var{\#ELSE} or \var{\#ENDIF} are
encountered, after which normal processing is resumed.

Example :
\begin{verbatim}
#IFDEF VER2_2_0
-Fu/usr/lib/fpc/2.2.0/linuxunits
#ENDIF
\end{verbatim}
In the above example, \file{/usr/lib/fpc/2.2.0/linuxunits} will be added to
the path if you're compiling with version 2.2.0 of the compiler.

\subsection{\#IFNDEF}
Syntax:
\begin{verbatim}
#IFNDEF name
\end{verbatim}
Lines following \var{\#IFNDEF} are read only if the keyword \var{name}
following it is not defined.

They are read until the keywords \var{\#ELSE} or \var{\#ENDIF} are
encountered, after which normal processing is resumed.

Example :
\begin{verbatim}
#IFNDEF VER2_2_0
-Fu/usr/lib/fpc/2.2.0/linuxunits
#ENDIF
\end{verbatim}
In the above example, \file{/usr/lib/fpc/2.2.0/linuxunits} will be added to
the path if you're NOT compiling with version 2.2.0 of the compiler.

\subsection{\#ELSE}
Syntax:
\begin{verbatim}
#ELSE
\end{verbatim}
\var{\#ELSE} can be specified after a \var{\#IFDEF} or \var{\#IFNDEF}
directive as an alternative.
Lines following \var{\#ELSE} are read only if the preceding \var{\#IFDEF}
or \var{\#IFNDEF} was not accepted.

They are skipped until the keyword \var{\#ENDIF} is
encountered, after which normal processing is resumed.

Example :
\begin{verbatim}
#IFDEF VER2_2_2
-Fu/usr/lib/fpc/2.2.2/linuxunits
#ELSE
-Fu/usr/lib/fpc/2.2.0/linuxunits
#ENDIF
\end{verbatim}
In the above example, \file{/usr/lib/fpc/2.2.2/linuxunits} will be added to
the path if you're compiling with version 2.2.2 of the compiler,
otherwise \file{/usr/lib/fpc/2.2.0/linuxunits} will be added to the path.

\subsection{\#ENDIF}
Syntax:
\begin{verbatim}
#ENDIF
\end{verbatim}
\var{\#ENDIF} marks the end of a block that started with \var{\#IF(N)DEF},
possibly with an \var{\#ELSE} between them.

\subsection{\#DEFINE}
Syntax:
\begin{verbatim}
#DEFINE name
\end{verbatim}
\var{\#DEFINE} defines a new keyword. This has the same effect as a
\var{-dname}  command line option.

\subsection{\#UNDEF}
Syntax:
\begin{verbatim}
#UNDEF name
\end{verbatim}
\var{\#UNDEF} un-defines a keyword if it existed.
This has the same effect as a \var{-uname}  command line option.

\subsection{\#WRITE}
Syntax:
\begin{verbatim}
#WRITE Message Text
\end{verbatim}
\var{\#WRITE} writes \var{Message Text} to the screen.
This can be useful to display warnings if certain options are set.

Example:
\begin{verbatim}
#IFDEF DEBUG
#WRITE Setting debugging ON...
-g
#ENDIF
\end{verbatim}
If \var{DEBUG} is defined, this will produce a line
\begin{verbatim}
Setting debugging ON...
\end{verbatim}
and will then switch on debugging information in the compiler.

\subsection{\#INCLUDE}
Syntax:
\begin{verbatim}
#INCLUDE filename
\end{verbatim}
\var{\#INCLUDE} instructs the compiler to read the contents of
\file{filename} before continuing to process options in the current file.

This can be useful if you want to have a particular configuration file
for a project (or, under \linux, in your home directory), but still want to
have the global options that are set in a global configuration file.

Example:
\begin{verbatim}
#IFDEF LINUX
#INCLUDE /etc/fpc.cfg
#ELSE
#IFDEF GO32V2
#INCLUDE c:\pp\bin\fpc.cfg
#ENDIF
#ENDIF
\end{verbatim}
This will include \file{/etc/fpc.cfg} if you're on a \linux machine,
and will include \verb+c:\pp\bin\fpc.cfg+
on a \dos machine.

\subsection{\#SECTION}
Syntax:
\begin{verbatim}
#SECTION name
\end{verbatim}
The \var{\#SECTION} directive acts as a \var{\#IFDEF} directive, only
it doesn't require an \var{\#ENDIF} directive. The special name \var{COMMON}
always exists, i.e. lines following \var{\#SECTION COMMON} are always read.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Variable subsitution in paths
\section{Variable substitution in paths}
To avoid having to edit your configuration files too often,
the compiler allows you to specify the following variables in
the paths that you feed to the compiler:
\begin{description}
\item[FPCFULLVERSION] is replaced by the compiler's version string.
\item[FPCVERSION] is replaced by the compiler's version string.
\item[FPCDATE] is replaced by the compiler's date.
\item[FPCTARGET] is replaced by the compiler's target (combination of CPU-OS)
\item[FPCCPU] is replaced by the compiler's target CPU.
\item[FPCOS] is replaced by the compiler's target OS.
\end{description}
To have these variables subsituted, just insert them with a \var{\$}
prepended, as follows:
\begin{verbatim}
-Fu/usr/lib/fpc/$FPCVERSION/rtl/$FPCOS
\end{verbatim}
This is equivalent to
\begin{verbatim}
-Fu/usr/lib/fpc/2.2.2/rtl/linux
\end{verbatim}
if the compiler version is \var{2.2.2} and the target OS is \linux{}.

These replacements are valid on the command line and also in the
configuration file.

On the linux command line, you must be careful to escape the \var{\$} since
otherwise the shell will attempt to expand the variable for you, which may have
undesired effects.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% IDE.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\input{ide.tex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Porting.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{Porting and portable code}

\section{Free Pascal compiler modes}
The \fpc team tries to create a compiler that can compile as much as
possible code produced for \tp, \delphi{} or the Mac pascal compilers: this
should make sure that porting code that was written for one of these
compilers is as easy as possible.

At the same time, the \fpc developers have introduced a lot of extensions
in the Object Pascal language. To reconcile these different goals, and to
make sure that people can produce code which can still be compiled by
the \tp and \delphi compilers, the compiler has a concepts of 'compiler
modes'. In a certain compiler mode, the compiler has certain functionalities
switched on or off. This allows to introduce a compatibility mode in which
only features supported by the original compiler are supported. Currently,
5 modes are supported:
\begin{description}
\item[FPC] This is the original \fpc compiler mode: here all language
constructs except classes, interfaces and exceptions are supported. 
Objects are supported in this mode. This is the default mode of the
compiler.
\item[OBJFPC] This is the same mode as \var{FPC} mode, but it also includes
classes, interfaces and exceptions.
\item[TP] Turbo Pascal compatibility mode. In this mode, the compiler tries
to mimic the Turbo Pascal compiler as closely as possible. Obviously, only
32-bit or 64-bit code can be compiled.
\item[DELPHI] Delphi compatibility mode. In this mode, the compiler tries
to resemble the Delphi compiler as best as it can: All Delphi 7 features are
implemented. Features that were implemented in the .NET versions of Delphi
are {\em not} implemented.
\item[MACPAS] the Mac Pascal compatibility mode. In this mode, the compiler
attempts to allow all constructs that are implemented in Mac pascal. In
particular, it attempts to compile the universal interfaces.
\end{description}

The compiler mode can be set on a per-unit basis: each unit can have its
own compiler mode, and it is possible to use units which have been compiled
in different modes intertwined. The mode can be set in one of 2 ways:
\begin{enumerate}
\item On the command line, with the -M switch. 
\item In the source file, with the \var{\{\$MODE \}} directive. 
\end{enumerate}
Both ways take the name of the mode as an argument. If the unit or program
source file does not specify a mode, the mode specified on the command-line
is used. If the source file specifies a mode, then it overrides the mode
given on the command-line. 

Thus compiling a unit with the \var{-M} switch as follows:
\begin{verbatim}
fpc -MOBJFPC myunit
\end{verbatim}
is the same as having the following mode directive in the unit:
\begin{verbatim}
{$MODE OBJFPC}
Unit myunit;
\end{verbatim}
The \var{MODE} directive should always be located before the uses clause of the unit
interface or program uses clause, because setting the mode may result in the
loading of an additional unit as the first unit to be loaded.

Note that the \var{\{\$MODE \}} directive is a global directive, i.e. it is
valid for the whole unit; Only one directive can be specified.

The mode has no influence on the availability of units: all available
units can be used, independent of the mode that is used to compile 
the current unit or program.

\section{Turbo Pascal}
\fpc was originally designed to resemble Turbo Pascal as closely as possible. 
There are, of course, restrictions. Some of these are due to the fact that
Turbo Pascal was developed  for 16-bit architectures whereas  \fpc is
a 32-bit/64-bit compiler. Other restrictions result from the fact that \fpc works
on more than one operating system.

In general we can say that if you keep your program code close to ANSI
Pascal, you will have no problems porting from Turbo Pascal, or even Delphi, to
\fpc. To a large extent, the constructs defined by Turbo Pascal are
supported. This is even more so if you use the \var{-Mtp} or \var{-MObjfpc}
switches.

In the following sections we will list the Turbo Pascal and Delphi 
constructs which are not supported in \fpc, and we will list in what
ways \fpc extends Turbo Pascal.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Things that will not work
\subsection{Things that will not work}

Here we give a list of things which are defined/allowed in Turbo Pascal, but
which are not supported by \fpc. Where possible, we indicate the reason.
\begin{enumerate}
\item Duplicate case labels are permitted in Turbo Pascal, but not
in \fpc. This is actually a bug in Turbo Pascal, and so
support for it will not be implemented in Free Pascal.
\item In \tp, parameter lists of previously defined functions and 
procedures did not have to match exactly. In Free Pascal, they must. 
The reason for this is the function overloading mechanism of
\fpc. However, the \seeo{M} option overcomes this restriction.
\item The Turbo Pascal variables \var{MEM, MEMW, MEML} and \var{PORT} for memory and port
access are not available in the system unit. This is due to the operating system. Under
\dos, the extender unit (\file {GO32}) implements the mem constuct.
Under \linux, the \file{ports} unit implements such a construct for the
\var{Ports} variable.
\item Turbo Pascal allows you to create procedure and variable names
using words that are not permitted in that role in Free Pascal.
This is because there are certain words that are reserved in
Free Pascal (and Delphi) that are not reserved in Turbo Pascal, such as:
\var{PROTECTED, PUBLIC, PUBLISHED, TRY, FINALLY, EXCEPT, RAISE}.
Using the \var{-Mtp} switch will solve this problem if
you want to compile Turbo Pascal code that uses these words
(\seec{reserved} for a list of all reserved words).

\item The Turbo Pascal reserved words \var{FAR, NEAR} are ignored. 
This is because their purpose was limited to a 16-bit environment 
and \fpc is a 32-bit/64-bit compiler.
\item The Turbo Pascal \var{INTERRUPT} directive will work only on the \fpc \dos target.
Other operating systems do not allow handling of interrupts by user
programs.
\item By default the \fpc compiler uses  \var{AT\&T} assembler syntax.
This is mainly because \fpc uses \gnu \var{as}. However, other assembler
forms are available. For more information, see the \progref.
\item Turbo Pascal's Turbo Vision is available in \fpc under the name of 
FreeVision, which should be almost 100\% compatible with Turbo Vision.
\item Turbo Pascal's 'overlay' unit is not available. It also isn't necessary, since
\fpc is a 32/64-bit compiler, so program size shouldn't be an issue.
%\item Turbo Pascal has fewer reserved words than Free Pascal. 
%(see appendix \ref{ch:reserved} for a list of all reserved words.)
\item The command line parameters of the compiler are different.
\item Compiler switches and directives are mostly the same, but some extra
exist.
\item Units are not binary compatible. That means that you cannot use a
\file{.tpu} unit file, produced by Turbo Pascal, in a \fpc project.
\item The \fpc \var{TextRec} structure (for internal description of files) is not
binary compatible with TP or Delphi.
\item Sets are by default 4 bytes in Free Pascal; this means that some typecasts
which were possible in Turbo Pascal are no longer possible in Free Pascal.
However, there is a switch to set the set size, see \progref for more
information.
\item A file is opened for output only (using \var{fmOutput}) when it is
opened with \var{Rewrite}. In order to be able to read from it, it should
be reset with \var{Reset}.
\item Turbo Pascal destructors allowed parameters. This is not
permitted in Free Pascal: by default, in \fpc, Destructors cannot have parameters. 
This restriction can be removed by using the \var{-So} switch.
\item Turbo Pascal permits more than one destructor for an object. In \fpc,
there can be only one destructor. This restriction can also be removed by 
using the \var{-So} switch.
\item The order in which expressions are evaluated is not necessarily the
same. In the following expression:
\begin{verbatim}
a := g(2) + f(3);
\end{verbatim}
it is not guaranteed that \var{g(2)} will be evaluated before \var{f(3)}.
\item In \fpc, you need to use the address @ operator when assigning procedural
variables.
\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Things which are extra
\subsection{Things which are extra}
Here we give a list of things which are possible in \fpc, but which
didn't exist in Turbo Pascal or Delphi.
\begin{enumerate}
\item \fpc functions can also return complex types, such as records and arrays.
\item  In \fpc, you can use the function return value in the function itself, as a
variable. For example:
\begin{verbatim}
function a : longint;

begin
   a:=12;
   while a>4 do
     begin
        {...}
     end;
end;
\end{verbatim}
The example above would work with TP, but the compiler would assume
that the \var{a>4} is a recursive call. If a recursive call is actually what
is desired, you must append \var{()} after the function name:
\begin{verbatim}
function a : longint;

begin
   a:=12;
   { this is the recursive call }
   if a()>4 then
     begin
        {...}
     end;
end;
\end{verbatim}
\item In \fpc, there is partial support of Delphi constructs. (See the \progref for
more information on this).
\item The \fpc \var{exit} call accepts a return value for functions.
\begin{verbatim}
function a : longint;

begin
   a:=12;
   if a>4 then
     begin
        exit(a*67); {function result upon exit is a*67 }
     end;
end;
\end{verbatim}
\item \fpc supports function overloading. That is, you can define many
functions with the same name, but with different arguments. For example:
\begin{verbatim}
procedure DoSomething (a : longint);
begin
{...}
end;

procedure DoSomething (a : real);
begin
{...}
end;
\end{verbatim}
You can then call procedure \var{DoSomething} with an argument of type
\var{Longint} or \var{Real}.\\
This feature has the consequence that a previously declared function must
always be defined with the header completely the same:
\begin{verbatim}
procedure x (v : longint); forward;

{...}

procedure x;{ This will overload the previously declared x}
begin
{...}
end;
\end{verbatim}
This construction will generate a compiler error, because the compiler
didn't find a definition of \var{procedure x (v : longint);}. Instead you
should define your procedure x as:
\begin{verbatim}
procedure x (v : longint);
{ This correctly defines the previously declared x}
begin
{...}
end;
\end{verbatim}
The command line option \seeo{So}  disables overloading. When you use it, the above will
compile, as in Turbo Pascal.
\item Operator overloading. \fpc allows operator overloading, e.g. you can
define the '+' operator for matrices.
\item On FAT16 and FAT32 systems, long file names are supported.
\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Turbo Pascal compatibility mode
\subsection{Turbo Pascal compatibility mode}
When you compile a program with the \var{-Mtp} switch, the compiler will
attempt to mimic the Turbo Pascal compiler in the following ways:
\begin{itemize}
\item Assigning a procedural variable doesn't require an @ operator. One of
the differences between Turbo Pascal and \fpc is that the latter requires
you to specify an address operator when assigning a value to a procedural
variable. In Turbo Pascal compatibility mode, this is not required.
\item Procedure overloading is disabled. If procedure overloading is
disabled, the function header doesn't need to repeat the function header.

\item Forward defined procedures don't need the full parameter list when
they are defined. Due to the procedure overloading feature of \fpc, you must
always specify the parameter list of a function when you define it, even
when it was declared earlier with \var{Forward}. In Turbo Pascal
compatibility mode, there is no function overloading; hence you can omit the
parameter list:
\begin{verbatim}
Procedure a (L : Longint); Forward;

...

Procedure a ; { No need to repeat the (L : Longint) }

begin
 ...
end;

\end{verbatim}
\item Recursive function calls are handled differently. Consider the
following example:
\begin{verbatim}
Function expr : Longint;

begin
  ...
  Expr:=L:
  Writeln (Expr);
  ...
end;
\end{verbatim}
In Turbo Pascal compatibility mode, the function will be called recursively
when the \var{writeln} statement is processed. In \fpc, the function result
will be printed. In order to call the function recursively under \fpc, you
need to implement it as follows :
\begin{verbatim}
Function expr : Longint;

begin
  ...
  Expr:=L:
  Writeln (Expr());
  ...
end;
\end{verbatim}
\item Any text after the final \var{End.} statement is ignored. Normally,
this text is processed too.
\item You cannot assign procedural variables to untyped pointers; so the
following is invalid:
\begin{verbatim}
 a: Procedure;
 b: Pointer;
begin
 b := a; // Error will be generated.
\end{verbatim}
\item The @ operator is typed when applied on procedures.
\item You cannot nest comments.
\end{itemize}

\begin{remark}
The \var{MemAvail} and \var{MaxAvail} functions are no longer available in
\fpc as of version 2.0. The reason for this incompatibility follows:

On modern operating systems, \footnote{The DOS extender GO32V2 falls under this 
definition of "modern" because it can use paged memory and run in 
multitasked environments.} the idea of "Available Free Memory" is not valid for an
application.
The reasons are:
\begin{enumerate} 
\item One processor cycle after an application asked the OS how much memory is free,
another application may have allocated everything.
\item It is not clear what "free memory" means: does it include swap memory,
does it include disk cache memory (the disk cache can grow and shrink on
modern OS'es), does it include memory allocated to other applications but
which can be swapped out, etc.
\end{enumerate}

Therefore, programs using \var{MemAvail} and \var{MaxAvail} functions 
should be rewritten so they no longer use these functions, because
it does not make sense any more on modern OS'es. There are 3 possibilities:
\begin{enumerate}
\item Use exceptions to catch out-of-memory errors.
\item Set the global variable "ReturnNilIfGrowHeapFails" to \var{True}
and check after each allocation whether the pointer is different from
\var{Nil}.
\item Don't care and declare a dummy function called \var{MaxAvail} 
which always returns \var{High(LongInt)} (or some other constant).
\end{enumerate}

\end{remark}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% A note about long file names.
\subsection{A note on long file names under \dos}
Under \windows 95 and higher, long filenames are supported. Compiling
for the \windows target ensures that long filenames are supported in all
functions that do file or disk access in any way.

Moreover, \fpc supports the use of long filenames in the system unit and
the \file{Dos} unit also for go32v2 executables. The system unit contains the
boolean variable \var{LFNsupport}. If it is set to \var{True} then all
system unit functions and \file{Dos} unit functions will use long file names
if they are available. This should be so on \windows 95 and 98, but
not on \windows NT or \windows 2000. The system unit will check this 
by calling \dos function \var{71A0h} and checking whether long filenames 
are supported on the \file{C:} drive.

It is possible to disable the long filename support by setting the
\var{LFNSupport} variable to \var{False}; but in general it is recommended
to compile programs that need long filenames as native \windows applications.

\section{Porting Delphi code}

Porting Delphi code should be quite painless. The \var{Delphi} mode of the 
compiler tries to mimic Delphi as closely as possible. 
This mode can be enabled using the \var{-Mdelphi} command line switch, 
or by inserting the following code in the sources before the \var{unit} 
or \var{program} clause:
\begin{verbatim}
{$IFDEF FPC}
{$MODE DELPHI}
{$ENDIF FPC}
\end{verbatim}
This ensures that the code will still compile with both Delphi and FPC.

Nevertheless, there are some things that will not work. 
Delphi compatibility is relatively complete up to Delphi 7. 
New constructs in higher versions of Delphi 
(notably, the versions that work with .NET) are not supported.

\subsection{Missing language constructs}
At the level of language compatibility, FPC is very compatible with Delphi:
it can compile most of FreeCLX, the free Widget library that was shipped 
with Delphi 6, Delphi 7 and Kylix.

Currently, the only missing language constructs are:
\begin{enumerate}
\item \var{Dynamic} methods are actually the same as \var{virtual}.
\item \var{Const} for a parameter to a procedure does not necessarily 
mean that the variable or value is passed by reference.
\item Packages are not supported.
\end{enumerate}

There are some inline assembler constructs which are not supported, 
and since \fpc is designed to be platform independent, it is quite 
unlikely that these constructs will be supported in the future.

Note that the \var{-Mobjfpc} mode switch is to a large degree Delphi 
compatible, but is more strict than Delphi. The most notable differences
are:
\begin{enumerate}
\item Parameters or local variables of methods cannot have the same 
names as properties of the class in which they are implemented.
\item The address operator is needed when assigning procedural variables (or event handlers).
\item AnsiStrings are not switched on by default.
\end{enumerate}

\subsection{Missing calls / API incompatibilities}
Delphi is heavily bound to Windows. Because of this, it introduced a lot of 
Windows-isms in the API (e.g. file searching and opening, loading libraries).

\fpc was designed to be portable, so things that are very Windows 
specific are missing, although the \fpc team tries to minimize this.
The following are the main points that should be considered:

\begin{itemize}
\item By default, \fpc generates console applications. This means that
you must explicitly enable the GUI application type for Windows:
\begin{verbatim}
{$APPTYPE GUI}
\end{verbatim}
\item The \file{Windows} unit provides access to most of the core 
Win32 API. Some calls may have different parameter lists: instead 
of declaring a parameter as passed by reference (var), a pointer 
is used (as in C). For most cases, \fpc provides overloaded versions 
of such calls.
\item Widestrings. Widestring management is not automatic in \fpc, 
since various platforms have different ways of dealing with widestring 
encodings and Multi-Byte Character Sets. 
FPC supports Widestrings, but may not use the same encoding as on Windows.

Note that in order to have correct widestring management, you need to
include the \file{cwstring} unit on Unix/\linux platforms: This unit
initializes the widestring manager with the necessary callbacks which
use the C library to implement all needed widestring functionality.
\item Threads: At this moment, \fpc does not offer native thread 
management on all platforms; on Unix, linking to the C library is 
needed to provide thread management in an FPC application. 
This means that a \file{cthreads} unit must be included to enable 
threads.
\item A much-quoted example is the \var{SetLastOSError} call. 
This is not supported, and will never be supported.
\item Filename Case sensitivity: Pascal is a case-insensitive language,
so the uses clause should also be case insensitive. Free Pascal ensures
case insensitive filenames by also searching for a lowercase version 
of the file. Kylix does not do this, so this could create problems
if two differently cased versions of the same filename are in the path.
\item RTTI is NOT stored in the same way as for Delphi. The format is mostly compatible, but may differ. This should not be a problem if the API of the TypeInfo unit 
is used and no direct access to the RTTI information is attempted.
\item By default, sets are of different size than in Delphi, but set size
can be specified using directives or command line switches.
\item Likewise, by default enumeration types are of different size than in
Delphi. Here again, the size can be specified using directives or command
line switches.
\item In general, one should not make assumptions about the internal
structure of complex types such as records, objects, classes and their
associated structure. For example, the VMT table layout is different, the
alignment of fields in a record may be different, etc. 
\item The same is true for basic types: on other processors the high and low
bytes of a word or integer may not be at the same location as on an Intel
processor (the endianness is different).
\item Names of local variables and method arguments are not allowed to 
match the name of a property or field of the class: this is bad practise,
as there can be confusion as to which of the two is meant.
\end{itemize}

\subsection{Delphi compatibility mode}
Switching on Dephi compatibility mode has the following effect:
\begin{enumerate}
\item Support for Classes, exceptions and threadvars is enabled.
\item The \file{objpas} is loaded as the first unit. This unit redefines
some basic types: \var{Integer} is 32-bit for instance.
\item The address operator (@) is no longer needed to set event handlers
(i.e. assign to procedural variables or properties).
\item Names of local variables and method parameters in classes can match 
the name of properties or field of the class.
\item The \var{String} keyword implies \var{AnsiString} by default. 
\item Operator overloading is switched off.
\end{enumerate}

\subsection{Best practices for porting}

When encountering differences in Delphi/FPC calls, the best thing to 
do is not to insert IFDEF statements whenever a difference is 
encountered, but to create a separate unit which is only used 
when compiling with FPC. The missing/incompatible calls can 
then be implemented in that unit. This will keep the code more 
readable and easier to maintain.

If a language construct difference is found, then the \fpc team 
should be contacted and a bug should be reported.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% writing portable code
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Writing portable code}

\fpc is designed to be cross-platform. This means that the basic RTL 
units are usable on all platforms, and the compiler behaves the same 
on all platforms (as far as possible).  The Object Pascal 
language is the same on all platforms. Nevertheless, FPC comes with a
lot of units that are not portable, but provide access to all 
possibilities that a platform provides.

The following are some guidelines to consider when writing portable code:
\begin{itemize}
\item Avoid system-specific units. The system unit, the objects and 
classes units and the SysUtils unit are guaranteed to work on all 
systems. So is the DOS unit, but that is deprecated. 
\item Avoid direct hardware access. Limited, console-like hardware 
access is available for most platforms in the Video, Mouse and  
Keyboard units.
\item Do not use hard-coded filename conventions. 
See below for more information on this.
\item Make no assumptions on the internal representation of types. Various
processors store information in different ways ('endianness').
\item If system-specific functionality is needed, it is best to 
separate this out in a single unit. Porting efforts will then be 
limited to re-implementing this unit for the new platform.
\item Don't use assembler, unless you have to. Assembler is processor
specific. Some instructions will not work even on the same processor family.
\item Do not assume that pointers and integers have the same size. They do
on an Intel 32-bit processor, but not necessarily on other processors.
The \var{PtrInt} type is an alias for the integer type that has the same
size as a pointer. \var{SizeInt} is used for all size-related issues.
\end{itemize}

The system unit contains some constants which describe file access on a system:
\begin{description}
\item[AllFilesMask] a file mask that will return all files in a directory.
This is \var{*} on Unix-like platforms, and \var{*.*} on dos and windows
like platforms.
\item[LineEnding] A character or string which describes the end-of-line marker 
used on the current platform. Commonly, this is one of \#10, \#13\#10 or \#13.
\item[LFNSupport] A boolean that indicates whether the system supports long filenames
(i.e. is not limited to MS-DOS 8.3 filenames).
\item[DirectorySeparator] The character which acts as a separator between directory parts of a path.
\item[DriveSeparator] For systems that support drive letters, this is the character that
is used to separate the drive indication from the path.
\item[PathSeparator] The character used to separate items in a list (notably, a PATH).
\item[maxExitCode] The maximum value for a process exitcode.
\item[MaxPathLen] The maximum length of a filename, including a path.
\item[FileNameCaseSensitive] A boolean that indicates whether filenames are handled case sensitively.
\item[UnusedHandle] A value used to indicate an unused/invalid file handle.
\item[StdInputHandle] The value of the standard input file handle. 
This is not always 0 (zero), as is commonly the case on Unices.
\item[StdOutputHandle] The value of the standard output file handle. 
This is not always 1, as is commonly the case on Unices.
\item[StdErrorHandle] The value of the standard diagnostics output file handle. 
This is not always 2, as is commonly the case on Unices.
\item[CtrlZMarksEOF] A boolean that indicates whether the \#26 character marks the end of a file
(an old MS-DOS convention).
\end{description}

To ease writing portable filesystem code, the Free Pascal file routines in
the system unit and \file{sysutils} unit treat the common directory separator 
characters (/ and $\backslash$) as equivalent. That means that if you use / on a \windows 
system, it will be transformed to a backslash, and vice versa. 

This feature is controlled by 2 (pre-initialized) variables in the system unit:
\begin{description}
\item[AllowDirectorySeparators] A set of characters which, when used in
filenames, are treated as directory separators. They are transformed to
the \var{DirectorySeparator} character.
\item[AllowDriveSeparators] A set of characters which, when used in
filenames, are treated as drive separator characters. They are transformed
to the \var{DriveSeparator} character.
\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Utilities.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{Utilities that come with Free Pascal}
\label{ch:Utilities}
Besides the compiler and the runtime Library, \fpc comes with some utility
programs and units. Here we list these programs and units.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Demo programs and examples.
\section{Demo programs and examples}
A suite of demonstration programs comes included with the Free
Pascal distribution.
These programs have no other purpose than to demonstrate the capabilities of
\fpc. They are located in the \file{demo} directory of the sources.

All example programs mentioned in the documentation are available. Check out the
directories that are beneath the same directory as the demo directory.
The names of these directories end on \file{ex}.
There you will find all example sources.

\section{fpcmake}

\file{fpcmake} is the \fpc makefile constructor program.

It reads a \file{Makefile.fpc} configuration file and converts it to a
\file{Makefile} suitable for reading by GNU \file{make} to compile
your projects. It is similar in functionality to GNU \file{autoconf}
or \file{Imake} for making X projects.

\file{fpcmake} accepts filenames of makefile description files as its
command line arguments. For each of these files it will create a
\file{Makefile} in the same directory where the file is located,
overwriting any other existing file.

If no options are given, it just attempts to read the file \file{Makefile.fpc}
in the current directory and tries to construct a makefile from it.
Any previously existing \file{Makefile} will be erased.

The format of the \file{fpcmake} configuration file is described in great
detail in the appendices of the \progref.

\section{fpdoc - Pascal Unit documenter}

\file{fpdoc} is a program which generates fully cross-referenced
documentation for a unit. It generates documentation for each 
identifier found in the unit's interface section. The generated 
documentation can be in many formats, for instance HTML, RTF, Text, man
page and LaTeX. 
Unlike other documentation tools, the documentation can be in a separate
file (in XML format), so the sources aren't cluttered with documentation.
Its companion program \file{makeskel} creates an empty XML file with
entries for all identifiers, or it can update an existing XML file, 
adding entries for new identifiers.

\file{fpdoc} and \file{makeskel} are described in the \fpdocref.

\section{h2pas - C header to Pascal Unit converter}
\file{h2pas} attempts to convert a C header file to a Pascal unit. 
it can handle most C constructs that one finds in a C header file,
and attempts to translate them to their Pascal counterparts. 

See below (constructs) for a full description of what the translator can handle.
The unit with Pascal declarations can then be used to access code written in C.

The output of the h2pas program is written to a file with the same name as
the C header file that was used as input, but with the extension \file{.pp}
The output file that h2pas creates can be customized in a number of ways by
means of many options.

\subsection{Options}
The output of  \file{h2pas} can be controlled with the following options:

\begin{description}
\item[-d] Use \var{external;} for all procedure and function declarations.
\item[-D] Use \var{external libname name 'func\_name'} for function and 
procedure declarations.
\item[-e] Emit a series of constants instead of an enumeration type for the 
C \var{enum} construct. 
\item[-i] Create an include file instead of a unit (omits the unit header).
\item[-l] \textbf{libname} specify the library name for external function 
declarations.
\item[-o] \textbf{outfile} Specify the output file name. Default is the input file name with 
the extension replaced by \file{.pp}
\item[-p] Use the letter \var{P} in front of pointer type parameters instead of \^.
\item[-s] Strip comments from the input file. By default comments are converted
to comments, but they may be displaced, since a comment is handled by the
scanner.
\item[-t] Prepend typedef type names with the letter \var{T} (used to follow 
Borland's convention that all types should be defined with T).
\item[-v] Replace pointer parameters with call by reference parameters.
Use with care because some calls can expect a \var{Nil} pointer.
\item[-w] Header file is a win32 header file (adds support for some special macros).
\item[-x] Handle SYS\_TRAP of the PalmOS header files.
\end{description}

\subsection{Constructs}
The following C declarations and statements are recognized:

\begin{description}
\item[defines] 
Defines are changed into Pascal constants if they are simple defines.
Macros are changed - wherever possible - to functions; however the arguments
are all integers, so these must be changed manually. Simple expressions 
in define staments are recognized, as are most arithmetic operators: 
addition, substraction, multiplication, division, logical operators, 
comparison operators, shift operators. The C construct ( A ? B : C)
is also recognized and translated to a Pascal construct with an IF
statement. (This is buggy, however).

\item[preprocessor statements]
The conditional preprocessing commands are recognized and translated into
equivalent Pascal compiler directives. The special 
\begin{verbatim}
#ifdef __cplusplus
\end{verbatim}
is also recognized and removed.
\item[typedef] A typedef statement is changed into a Pascal type statement. 
The following basic types are recognized:
\begin{itemize}
\item \var{char} changed to \var{char}.
\item \var{float} changed to \var{real} (=double in \fpc).
\item \var{int} changed to \var{longint}.
\item \var{long} changed to \var{longint}.
\item \var{long int} changed to \var{longint}.
\item \var{short} changed to \var{integer}. 
\item \var{unsigned} changed to \var{cardinal}.
\item \var{unsigned char} changed to \var{byte}.
\item \var{unsigned int} changed to \var{cardinal}.
\item \var{unsigned long int} changed to \var{cardinal}.
\item \var{unsigned short} changed to \var{word}.
\item \var{void} ignored.
\end{itemize}
These types are also changed if they appear in the arguments of a function
or procedure.
\item[functions and procedures]
Functions and procedures are translated as well. Pointer types may be
changed to call by reference arguments (using the \var{var} argument) 
by using the \var{-p} command line argument. Functions that have a 
variable number of arguments are changed to a function with a \var{cvar}
modifier. (This used to be the \var{array of const} argument.)
\item[specifiers]
The \var{extern} specifier is recognized; however it is ignored. 
The \var{packed} specifier is also recognised and changed with the
\var{PACKRECORDS} directive. The \var{const} specifier is also 
recognized, but is ignored.
\item[modifiers] 
If the \var{-w} option is specified, then the following modifiers are recognized:
\begin{verbatim}
STDCALL
CDECL
CALLBACK
PASCAL
WINAPI
APIENTRY
WINGDIAPI
\end{verbatim}
as defined in the win32 headers. If additionally the \var{-x}
option is specified then the  
\begin{verbatim}
SYS_TRAP
\end{verbatim}
specifier is also recognized.
\item[enums]
Enum constructs are changed into enumeration types. Bear in mind that, in C,
enumeration types can have values assigned to them. Free Pascal also allows
this to a certain degree. If you know that values are assigned to enums, it
is best to use the \var{-e} option to change the enumerations to a series of 
integer  constants.

\item[unions] Unions are changed to variant records. 
\item[structs] Structs are changed to Pascal records, with C packing.
\end{description}

\section{h2paspp - preprocessor for h2pas}
\var{h2paspp} can be used as a simple preprocessor for \file{h2pas}. It
removes some of the constructs that h2pas has difficulties with. 
\file{h2paspp} reads one or more C header files and preprocesses them, writing the result 
to files with the same name as the originals as it goes along. 
It does not accept all preprocesser tokens of C, but takes care of the following 
preprocessor directives:

\begin{description}
\item [\#define symbol] Defines the new symbol \var{symbol}. Note that macros are not supported.
\item [\#if symbol] The text following this directive is included if \var{symbol} is defined.
\item [\#ifdef symbol] The text following this directive is included if \var{symbol} is defined. 
\item [\#ifndef symbol] The text following this directive is included if \var{symbol} is not defined.
\item [\#include filename] Include directives are removed, unless the \var{-I} option was given, 
in which case the include file is included and written to the output file.
\item[\#undef symbol] The symbol \var{symbol} is undefined.
\end{description}

\subsection{Usage}
\file{h2paspp} accepts one or more filenames and preprocesses them. 
It will read the input, and write the output to a file with the same name 
unless the \var{-o} option is given, in which case the file is written 
to the specified file. Note that only one output filename can be given.


\subsection{Options}
\file{h2paspp} has a small number of options to control its behaviour:
\begin{description}
\item[-dsymbol] Define the symbol \var{symbol} before processing is started.
\item[-h] Emit a small helptext.
\item[-I] Include include files instead of dropping the include statement.
\item[-ooutfile] If this option is given, the output will be written to a 
file named \file{outfile}. Note that only one output file can be given.
\end{description}

\section{ppudump program}

\file{ppudump} is a program which shows the contents of a \fpc unit. It
is distributed with the compiler. You can just issue the following command
\begin{verbatim}
  ppudump [options] foo.ppu
\end{verbatim}
to display the contents of the \file{foo.ppu} unit. You can specify multiple
files on the command line.

The options can be used to change the verbosity of the display. By default,
all available information is displayed.
You can set the verbosity level using the \var{-Vxxx} option.
Here, \var{xxx} is a combination of the following
letters:
\begin{description}
\item [h:\ ] Show header info.
\item [i:\ ] Show interface information.
\item [m:\ ] Show implementation information.
\item [d:\ ] Show only (interface) definitions.
\item [s:\ ] Show only (interface) symbols.
\item [b:\ ] Show browser info.
\item [a:\ ] Show everything (default if no -V option is present).
\end{description}


\section{ppumove program}
\label{se:ppumove}

\file{ppumove} is a program to make shared or static libraries from
multiple units. It can be compared with the \file{tpumove} program that
comes with Turbo Pascal.

It is distributed in binary form along with the compiler.

Its usage is very simple:
\begin{verbatim}
ppumove [options] unit1.ppu unit2.ppu ... unitn.ppu
\end{verbatim}
where \var{options} is a combination of:
\begin{description}
\item[-b:\ ] Generate a batch file that will
contain the external linking and archiving commands that must be
executed. The name of this batch file is \file{pmove.sh} on \linux (and Unix
like OSes), and \file{pmove.bat} on \windows and \dos.
\item[-d xxx:\ ] Set the directory in which to place the output files to
\file{xxx}.
\item[-e xxx:\ ] Set the extension of the moved unit files to \file{xxx}.
By default, this is \file{.ppl}. You don't have to specify the dot.
\item[-o xxx:\ ] Set the name of the output file, i.e. the name of the file
containing all the units. This parameter is mandatory when you use multiple
files. On \linux, \file{ppumove} will prepend this name with \file{lib} if it isn't
already there, and will add an extension appropriate to the type of library.
\item [-q:\ ] Operate silently.
\item [-s:\ ] Make a static library instead of a
dynamic one; By default a dynamic library is made on \linux.
\item [-w:\ ] Tell \file{ppumove} that it is working under \windowsnt. This will
change the names of the linker and archiving program to \file{ldw} and
\file{arw}, respectively.
\item[-h or -?:\ ] Display a short help.
\end{description}

The action of the \file{ppumove} program is as follows:
It takes each of the unit files, and modifies it so that the compiler will
know that it should look for the unit code in the library. The new unit
files will have an extension \file{.ppu}; this can be changed with the
\var{-e} option. It will then put together all the object files of the units
into one library, static or dynamic, depending on the presence of the
\var{-s} option.

The name of this library must be set with the \var{-o} option.
If needed, the prefix \file{lib} will be prepended under \linux.
The extension will be set to \file{.a} for static libraries,
for shared libraries, the extensions are \var{.so} on linux, and \var{.dll}
under \windowsnt and \ostwo.

As an example, the following command
\begin{verbatim}
./ppumove -o both -e ppl ppu.ppu timer.ppu
\end{verbatim}
will generate the following output under \linux{}:
\begin{verbatim}
PPU-Mover Version 2.1.1
Copyright (c) 1998-2007 by the Free Pascal Development Team

Processing ppu.ppu... Done.
Processing timer.ppu... Done.
Linking timer.o ppu.o
Done.
\end{verbatim}
And it will produce the following files:
\begin{enumerate}
\item \file{libboth.so} : The shared library containing the code from
\file{ppu.o} and \file{timer.o}. Under \windowsnt, this file would be called
\file{both.dll}.
\item \file{timer.ppl} : The unit file that tells the \fpc compiler to look
for the timer code in the library.
\item \file{ppu.ppl} : The unit file that tells the \fpc compiler to look
for the ppu code in the library.
\end{enumerate}
You could then use or distribute the files \file{libboth.so}, \file{timer.ppl}
and \file{ppu.ppl}.

\section{ptop - Pascal source beautifier}

\subsection{ptop program}
% This section was supplied by Marco Van de voort, for which my thanks.
% I did some cleaning, and added the subsubsection with help on on the
% object. MVC.

\file{ptop} is a source beautifier written by Peter Grogono based on the ancient pretty-printer
by Ledgard, Hueras, and Singer, modernized by the \fpc team (objects, streams, configurability
etc).

This configurability, and the thorough bottom-up design are the advantages of this program over
the diverse Turbo Pascal source beautifiers on e.g. SIMTEL.

The program is quite simple to operate:

ptop "[-v] [-i indent] [-b bufsize ][-c \file{optsfile}] \file{infile} \file{outfile}"

The \file{infile} parameter is the Pascal file to be processed, and will be written
to \file{outfile}, overwriting an existing \file{outfile} if it exists.

Some options modify the behaviour of ptop:

\begin{description}
\item[-h] Write an overview of the possible parameters and command line syntax.
\item[-c \file{ptop.cfg}] Read some configuration data from configuration file instead of using
  the internal defaults then. A config file is not required, the program can
  operate without one. See also -g.
\item[-i ident] Set the number of indent spaces used for BEGIN END; and other blocks.
\item[-b bufsize] Set the streaming buffersize to bufsize. The default is 255; 
0 is considered non-valid and ignored.
\item[-v] Be verbose. Currently only outputs the number of lines read/written and some error messages.
\item[-g \file{ptop.cfg}] Write \file{ptop} configuration defaults to the file
"ptop.cfg". The contents of this file can be changed to your liking, and it
can be used with the -c option.
\end{description}

\subsection{The ptop configuration file}

Creating and distributing a configuration file for ptop is not necessary,
unless you want to modify the standard behaviour of \file{ptop}. The configuration
file is never preloaded, so if you want to use it you should always specify
it with a \var{-c ptop.cfg} parameter.

The structure of a ptop configuration file is a simple building block repeated
several (20-30) times, for each Pascal keyword known to the \file{ptop} program.
(See the default configuration file or \file{ptopu.pp} source to
find out which keywords are known).

The basic building block of the configuration file consists of one or two
lines, describing how \file{ptop} should react on a certain keyword.
First comes a line without square brackets with the following format:

keyword=option1,option2,option3,...

If one of the options is "dindonkey" (see further below), a second line
- with square brackets - is needed:

[keyword]=otherkeyword1,otherkeyword2,otherkeyword3,...

As you can see the block contains two types of identifiers: keywords 
(keyword and otherkeyword1..3 in above example) and options, (option1..3 above).

\var{Keywords} are the built-in valid Pascal structure-identifiers like BEGIN, END, CASE, IF,
THEN, ELSE, IMPLEMENTATION. The default configuration file lists most of these.

Besides the real Pascal keywords, some other codewords are used for operators
and comment expressions as in \seet{keywords}.

\begin{FPCltable}{lll}{Keywords for operators}{keywords}
Name of codeword       &     Operator \\  \hline
casevar                &     : in a case label ( unequal 'colon') \\
becomes                &     := \\
delphicomment          &     // \\
opencomment            &       \{ or (* \\
closecomment           &     \} or *) \\
semicolon              &     ; \\
colon                  &     : \\
equals                 &     = \\
openparen              &     [ \\
closeparen             &     ] \\
period                 &     . \\
\end{FPCltable}

The \textbf{options} codewords define actions to be taken when the keyword before
the equal sign is found, as listed in \seet{ptopoptions}.

\begin{FPCltable}{lll}{Possible options}{ptopoptions}
Option         &     does what \\ \hline
crsupp         &     Suppress CR before the keyword.\\
crbefore       &     Force CR before keyword.\\
               &     (do not use with crsupp.)\\
blinbefore     &     Blank line before keyword.\\
dindonkey      &     De-indent on associated keywords.\\
               &     (see below)\\
dindent        &     Deindent (always)\\
spbef          &     Space before\\
spaft          &     Space after\\
gobsym         &     Print symbols which follow a\\
               &     keyword but which do not\\
               &     affect layout. prints until\\
               &     terminators occur.\\
               &     (terminators are hard-coded in pptop,\\
               &     still needs changing)\\
inbytab        &     Indent by tab.\\
crafter        &     Force CR after keyword.\\
upper          &     Prints keyword all uppercase\\
lower          &     Prints keyword all lowercase\\
capital        &     Capitalizes keyword: 1st letter\\
               &     uppercase, rest lowercase.\\
\end{FPCltable}

The option "dindonkey" given in table \seet{ptopoptions} requires some
further explanation. "dindonkey" is a contraction of "DeINDent ON
associated KEYword". When it is present as an option in the first
line, then a second, square-bracketed, line is required. 
A de-indent will be performed when any of the other keywords listed
in the second line are encountered in the source.

Example: The lines
\begin{verbatim}
else=crbefore,dindonkey,inbytab,upper
[else]=if,then,else
\end{verbatim}

mean the following:

\begin{itemize}
\item The keyword this block is about is \textbf{else} because it's on the LEFT side
of both equal signs.
\item The option \var{crbefore} signals not to allow other code (so just spaces)
before the ELSE keyword on the same line.
\item The option \var{dindonkey} de-indents if the parser finds any of the keywords
 in the square brackets line (if,then,else).
\item The option \var{inbytab} means indent by a tab.
\item The option \var{upper} uppercase the keyword (else or Else becomes ELSE)
\end{itemize}

Try to play with the configfile step by step until you find the effect you desire.
The configurability and possibilities of ptop are quite large. E.g. I like all
keywords uppercased instead of capitalized, so I replaced all capital keywords in
the default file by upper.

\file{ptop} is still development software. So it is wise to visually check the generated
source and try to compile it, to see if \file{ptop} hasn't introduced any errors.

\subsection{ptopu unit}

The source of the \file{PtoP} program is conveniently split in two files:
one is a unit containing an object that does the actual beautifying of the
source, the other is a shell built around this object so it can be used
from the command line. This design makes it possible to include the object
in a program (e.g. an IDE) and use its features to format code.

The object resides in the \file{PtoPU} unit, and is declared as follows
\begin{verbatim}
  TPrettyPrinter=Object(TObject)
      Indent : Integer;    { How many characters to indent ? }
      InS    : PStream;
      OutS   : PStream;
      DiagS  : PStream;
      CfgS : PStream;
      Constructor Create;
      Function PrettyPrint : Boolean;
    end;
\end{verbatim}

Using this object is very simple. The procedure is as follows:
\begin{enumerate}
\item Create the object, using its constructor.
\item Set the \var{InS} stream. This is an open stream, from which Pascal source will be
read. This is a mandatory step.
\item Set the \var{OutS} stream. This is an open stream, to which the
beautified Pascal source will be written. This is a mandatory step.
\item Set the \var{DiagS} stream. Any diagnostics will be written to this
stream. This step is optional. If you don't set this, no diagnostics are
written.
\item Set the \var{CfgS} stream. A configuration is read from this stream.
(see the previous section for more information about configuration). This
step is optional. If you don't set this, a default configuration is used.
\item Set the \var{Indent} variable. This is the number of spaces to use
when indenting. Tab characters are not used in the program. This step is
optional. The indent variable is initialized to 2.
\item Call \var{PrettyPrint}. This will pretty-print the source in \var{InS}
and write the result to \var{OutS}. The function returns \var{True} if no
errors occurred, \var{False} otherwise.
\end{enumerate}

So, a minimal procedure would be:
\begin{verbatim}
Procedure CleanUpCode;

var
  Ins,OutS : PBufStream;
  PPRinter : TPrettyPrinter;

begin
  Ins:=New(PBufStream,Init('ugly.pp',StopenRead,TheBufSize));
  OutS:=New(PBufStream,Init('beauty.pp',StCreate,TheBufSize));
  PPrinter.Create;
  PPrinter.Ins:=Ins;
  PPrinter.outS:=OutS;
  PPrinter.PrettyPrint;
end;
\end{verbatim}

Using memory streams allows very fast formatting of code, and is
particularly suitable for editors.

\section{rstconv program}

The \file{rstconv} program converts the resource string files generated by
the compiler (when you use resource string sections) to \file{.po} files
that can be understood by the GNU \file{msgfmt} program.

Its usage is very easy; it accepts the following options:
\begin{description}
\item[-i file] Use the specified file instead of stdin as input file. This
option is optional.
\item[-o file] Write output to the specified file. This option is required.
\item[-f format] Specify the output format. At the moment, only one output
format is supported: {\em po} for GNU gettext \file{.po} format.
It is the default format.
\end{description}
As an example:
\begin{verbatim}
rstconv -i resdemo.rst -o resdemo.po
\end{verbatim}
will convert the \file{resdemo.rst} file to \file{resdemo.po}.

More information on the \file{rstconv} utility can be found in the \progref,
under the chapter about resource strings.

\section{unitdiff program}

\subsection{Synopsis}
\file{unitdiff} shows the differences between two unit interface sections. 
\begin{verbatim}
unitdiff [--disable-arguments] [--disable-private] [--disable-protected] 
[--help] [--lang=language] [--list] [--output=filename] [--sparse] 
file1 file2
\end{verbatim}

\subsection{Description and usage}

\file{Unitdiff} scans one or two Free Pascal unit source files and either lists all
available identifiers, or describes the differences in identifiers
between the two units.

You can invoke \file{unitdiff} with an input filename as the only required
argument. It will then simply list all available identifiers.

The regular usage is to invoke \file{unitdiff} with two arguments:
\begin{verbatim}
unitdiff input1 input2
\end{verbatim}
Invoked like this, it will show the difference in interface between the two
units, or list the available identifiers in both units. The output of 
\file{unitdiff} will go to standard output by default.

\subsection{Options}
Most of the \file{unitdiff} options are not required. Defaults will be used in most
cases.

\begin{description}
\item[--disable-arguments] Do not check the arguments of functions 
and procedures. The default action is to check them.
\item[--disable-private] Do not check private fields or methods of
classes. The default action is to check them.
\item[--disable-protected] Do not check protected fields or methods of
classes. The default action is to check them.
\item[--help] Emit a short help text and exit.
\item[--lang=language] Set the language for the output file. This will mainly 
set the strings used for the headers in various parts of the documentation files 
(by default they're in English). Currently, valid options are:
\begin{itemize}
\item \var{de}: German.
\item \var{fr}: French.
\item \var{nl}: Dutch.
\end{itemize}
\item[--list] Display just the list of available identifiers for the unit
or units. If only one unit is specified on the command line, this option 
is automatically assumed.
\item[--output=filename] Specify where the output should go. The default
action is to send the output is sent to standard output (the screen).
\item[--sparse] Turn on sparse mode. Output only the identifier names.
Do not output types or type descriptions. By default, type descriptions 
are also written.
\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Supplied units
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Units that come with Free Pascal}
\label{ch:Units}

Here we list the units that come with the \fpc distribution. Since there is
a difference in the supplied units per operating system, we first describe
the generic ones, then describe those which are operating system specific. 

%
% Common units
%
\section{Standard units}

The following units are standard and are meant to be ported to
all platforms supported by \fpc. A brief description of each unit
is also given.

\begin{description}
\item[charset] A unit to provide mapping of character sets.
\item[cmem] Using this unit replaces the Free Pascal memory manager with the 
memory manager of the C library.
\item[crt] This unit is similar to the unit of the same name of
Turbo Pascal. It implements writing to the console in color,  moving the 
text cursor around and reading from the keyboard.
\item[dos] This unit provides basic routines for accessing the operating
system. This includes file searching, environment variables access,
getting the operating system version, getting and setting the
system time. It is to note that some of these routines are duplicated
in functionality in the \var{sysutils} unit.
\item[dynlibs] Provides cross-platform access to loading dynamical libraries.
%\item[errors] returns 
\item[getopts] This unit gives you the \gnu \var{getopts} command line
arguments handling mechanism. It also supports long options.
\item[graph] \emph{This unit is deprecated}. This unit provides basic graphics handling, with routines to
draw lines on the screen, display text etc. It provides the same functions
as the Turbo Pascal unit. 
\item[heaptrc] a unit which debugs the heap usage. When the program exits, it outputs a summary of the used memory, and dumps a summary of unreleased memory blocks (if any).
\item[keyboard] provides basic keyboard handling routines in a platform independent way,
and supports writing custom drivers.
\item[macpas] This unit implements several functions available only in MACPAS mode. 
This unit should not be included; it's automatically included when the MACPAS mode is used.
\item[math] This unit contains common mathematical routines (trigonometric
functions, logarithms, etc.) as well as more complex ones (summations of arrays,
normalization functions, etc.).
\item[matrix] A unit providing matrix manipulation routines.
\item[mmx] This unit provides support for \var{mmx} extensions in your
code. 
\item[mouse] Provides basic mouse handling routines in a platform independent way,
and supports writing custom drivers. 
\item [objects]  This unit provides the base object for standard Turbo Pascal
objects. It also implements File and Memory stream objects, as well as sorted
and non-sorted collections, and string streams.
\item[objpas] Is used for Delphi compatibility. You should never load this
unit explicitly; it is automatically loaded if you request Delphi mode.
\item[printer]  This unit provides all you need for rudimentary access
to the printer using standard I/O routines.
\item[sockets] This gives the programmer access to sockets and TCP/IP 
programming.
\item[strings] This unit provides basic string handling routines for the
\var{pchar} type, comparable to similar routines in standard \var{C}
libraries.
\item[system] This unit is available for all supported platforms. It includes
among others, basic file I/O routines, memory management routines, all compiler 
helper routines, and directory services routines. 
\item[strutils] Offers a lot of extended string handling routines. 
\item[dateutils] Offers a lot of extended date/time handling routines for 
almost any date and time math. 
\item[sysutils] Is an alternative implementation of the sysutils unit of
Delphi. It includes file I/O access routines which takes care of file
locking, date and string handling routines, file search, date and string 
conversion routines.
\item[typinfo] Provides functions to access runtime Type Information, just
like Delphi.
\item[variants] Provides basic variant handling.
\item[video] Provides basic screen handling in a platform independent way,
and supports writing custom drivers.
\end{description}

%
% Under DOS
%
\section{Under DOS}
\begin{description}
\item [emu387] This unit provides support for the coprocessor emulator.
\item [go32] This unit provides access to capabilities of the \var{GO32}
\dos extender.
\item[ports] This implements the various \var{port[]} constructs for low-level
I/O.
\end{description}

%
% Under Windows
%
\section{Under Windows}
\begin{description}
\item[wincrt] This implements a console in a standard GUI window, contrary
to the \var{crt} unit which is for the Windows console only.
\item[Windows] This unit provides access to all Win32 API calls. Effort has
been taken to make sure that it is compatible to the Delphi version of this
unit, so code for Delphi is easily ported to \fpc.
\item[opengl] Provides access to the low-level opengl functions in \windows.
\item[winmouse] Provides access to the mouse in \windows.
\item[ole2] Provides access to the OLE capabilities of \windows.
\item[winsock] Provides access to the \windows sockets API Winsock.
\item[Jedi windows header translations] The units containing the Jedi
translations of the Windows API headers is also distributed with Free
Pascal. The names of these units start with \file{jw}, followed by the 
name of the particular API.
\end{description}

%
% Under Linux
%
\section{Under Linux and BSD-like platforms}
\begin{description}
\item[baseunix] Basic Unix operations, basically a subset of the POSIX specification. 
Using this unit should ensure portability across most unix systems.
\item[clocale] This unit initializes the internationalization settings in
the \file{sysutils} unit with settings obtained through the C library.
\item[cthreads] This unit should be specified as the first or second
unit in the uses clause of your program: it will use the Posix threads
implementation to enable threads in your FPC program.
\item[cwstring] If widestring routines are used, then this unit should 
be inserted as one of the first units in the uses clause of your program:
it will initialize the widestring manager in the system unit with routines
that use C library functions to handle Widestring conversions and other
widestring operations.
\item[errors] Returns a string describing an operating system error code.
\item[Libc] This is the interface to GLibc on a linux I386 system. It will
{\em not} work for other platforms, and is in general provided for Kylix
compatibility. 
\item[oldlinux] \emph{This unit is deprecated}. This unit provides access to the
\linux operating system. It provides most file and I/O handling routines
that you may need. It implements most of the standard \var{C} library constructs
that you will find on a Unix system. It is recommended, however, that you
use the \file{baseunix}, \file{unixtype} and \file{unix} units. They are
more portable.
\item[ports] This implements the various \var{port[]} constructs. These are
provided for compatibility only, and it is not recommended to use them
extensively. Programs using this construct must be run as root or setuid
root, and are a serious security risk on your system.
\item[termio] Terminal control routines, which are compatible to the C
library routines.
\item[unix] Extended Unix operations.
\item[unixtype] All types used commonly on Unix platforms.
\end{description}

\section{Under OS/2}
\begin{description}
\item[doscalls] Interface to \file{doscalls.dll}.
\item[dive] Interface to \file{dive.dll}
\item[emx] Provides access to the EMX extender.
\item[pm*] Interface units for the Presentation Manager (PM) functions (GUI).
\item[viocalls] Interface to \file{viocalls.dll} screen handling library.
\item[moucalls] Interface to \file{moucalls.dll} mouse handling library.
\item[kbdcalls] Interface to \file{kbdcalls.dll} keyboard handling library.
\item[moncalls] Interface to \file{moncalls.dll} monitoring handling library.
\item[winsock] Provides access to the (emulated) \windows sockets API Winsock.
\item[ports] This implements the various \var{port[]} constructs for low-level
I/O.
\end{description}

\section{Unit availability}

Standard unit availability for each of the supported platforms 
is given in the FAQ / Knowledge base. 

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Debugging
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{Debugging your programs}

\fpc supports debug information for the \gnu debugger \var{gdb}, or
its derivatives \file{Insight} on win32 or \file{ddd} on \linux.
It can write 2 kinds of debug information:
\begin{description}
\item[stabs] The old debug information format.
\item[dwarf] The new debug information format.
\end{description}
Both are understood by GDB.

This chapter briefly describes how to use this feature. It doesn't attempt
to describe completely the \gnu debugger, however.
For more information on the workings of the \gnu debugger, see the \var{GDB}
User Manual.

\fpc also suports \var{gprof}, the \gnu profiler. See section \ref{se:gprof}
for more information on profiling.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Compiling your program with debugger support
\section{Compiling your program with debugger support}
First of all, you must be sure that the compiler is compiled with debugging
support. Unfortunately, there is no way to check this at run time, except by
trying to compile a program with debugging support.

To compile a program with debugging support, just specify the \var{-g}
option on the command line, as follows:
\begin{verbatim}
fpc -g hello.pp
\end{verbatim}
This will incorporate debugging information in the executable generated 
from your program source. You will notice that the size of the executable 
increases substantially because of this\footnote{A good reason not to include debug
information in an executable you plan to distribute.}.

Note that the above will only incorporate debug information {\em for the code
that has been generated} when compiling \file{hello.pp}. This means that if
you used some units (the system unit, for instance) which were not compiled
with debugging support, no debugging support will be available for the code
in these units.

There are 2 solutions for this problem.
\begin{enumerate}
\item Recompile all units manually with the \var{-g} option.
\item Specify the 'build' option (\var{-B}) when compiling with debugging
support. This will recompile all units, and insert debugging information in
each of the units.
\end{enumerate}
The second option may have undesirable side effects. It may be that some
units aren't found, or compile incorrectly due to missing conditionals,
etc.

If all went well, the executable now contains the necessary information with
which you can debug it using \gnu \var{gdb}.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Using gdb
\section{Using \var{gdb} to debug your program}
\label{se:usinggdb}

To use gdb to debug your program, you can start the debugger, and give it as
an option the {\em full} name of your program:
\begin{verbatim}
gdb hello
\end{verbatim}
Or, under \dos :
\begin{verbatim}
gdb hello.exe
\end{verbatim}

This starts the debugger, and the debugger immediately loads your program
into memory, but it does not run the program yet. Instead, you are presented
with the following (more or less) message, followed by the \var{gdb} prompt
\var{'(gdb)'}:
\begin{verbatim}
GNU gdb 6.6.50.20070726-cvs
Copyright (C) 2007 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB.  Type "show warranty" for details.
This GDB was configured as "x86_64-suse-linux".
(gdb)
\end{verbatim}
The actual prompt will vary depending on  your operating system and
installed version of gdb, of course.

To start the program you can use the \var{run} command. You can optionally
specify command line parameters, which will then be fed to your program, for
example:
\begin{verbatim}
(gdb) run -option -anotheroption needed_argument
\end{verbatim}
If your program runs without problems, \var{gdb} will inform you of this,
and return the exit code of your program. If the exit code was zero, then
the message \var{'Program exited normally'} is displayed.

If something went wrong (a segmentation fault or such), \var{gdb} will stop
the execution of your program, and inform you of this with an appropriate
message. You can then use the other \var{gdb} commands to see what happened.
Alternatively, you can instruct \var{gdb} to stop at a certain point in your
program, with the \var{break} command.

Here is a short list of \var{gdb} commands, which you are likely to need when
debugging your program:
\begin{description}
\item [quit\ ] Exit the debugger.
\item [kill\ ] Stop a running program.
\item [help\ ] Give help on all \var{gdb} commands.
\item [file\ ] Load a new program into the debugger.
\item [directory\ ] Add a new directory to the search path for source
files.\\
\begin{remark} 
My copy of gdb needs '.' to be added explicitly to the search
path, otherwise it doesn't find the sources.
\end{remark}
\item [list\ ] List the program sources in chunks of 10 lines. As an option you can
specify a line number or function name.
\item [break\ ] Set a breakpoint at a specified line or function.
\item [awatch\ ] Set a watch-point for an expression. A watch-point stops
execution of your program whenever the value of an expression is either
read or written.
\end{description}

In appendix {\ref{ch:GdbIniFile}} a sample init file for
\var{gdb} is presented. It produces good results when debugging \fpc programs.

For more information, refer to the \var{gdb} User Manual, or use the 
\var{'help'} function in \var{gdb}.

The text mode IDE and Lazarus both use GDB as a debugging backend. It may
be preferable to use that, as they hide much of the details of the debugger
in an easy-to-use user interface.

\section{Caveats when debugging with \var{gdb}}

There are some peculiarities of \fpc which you should be aware of when using
\var{gdb}. We list the main ones here:
\begin{enumerate}
\item \fpc generates information for GDB in uppercase letters. This is a
consequence of the fact that Pascal is a case insensitive language. So, when
referring to a variable or function, you need to make its name all
uppercase.

As an example, if you want to watch the value of a loop variable
\var{count}, you should type
\begin{verbatim}
watch COUNT
\end{verbatim}
Or if you want to stop when a certain function (e.g \var{MyFunction}) is called,
type
\begin{verbatim}
break MYFUNCTION
\end{verbatim}

\item \var{gdb} does not know sets.

\item \var{gdb} doesn't know strings. Strings are represented in \var{gdb}
as records with a length field and an array of char containing the string.

You can also use the following user function to print strings:
\begin{verbatim}
define pst
set $pos=&$arg0
set $strlen = {byte}$pos
print {char}&$arg0.st@($strlen+1)
end

document pst
  Print out a Pascal string
end
\end{verbatim}
If you insert it in your \file{gdb.ini} file, you can look at a string with this
function. There is a sample \file{gdb.ini} in appendix \ref{ch:GdbIniFile}.

\item Objects are difficult to handle, mainly because \var{gdb} is oriented
towards C and C++. The workaround implemented in \fpc is that object methods
are represented as functions, with an extra parameter \var{this} (all
lowercase!). The name of this function is a concatenation of the object type
and the function name, separated by two underscore characters.

For example, the method \var{TPoint.Draw} would be converted to
\var{TPOINT\_\_DRAW}, and you could stop at it by using:
\begin{verbatim}
break TPOINT__DRAW
\end{verbatim}

\item Global overloaded functions confuse \var{gdb} because they have the same
name. Thus you cannot set a breakpoint at an overloaded function, unless you
know its line number, in which case you can set a breakpoint at the
starting line number of the function.
\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Using gprof
\section{Support for \var{gprof}, the \gnu profiler}
\label{se:gprof}

You can compile your programs with profiling support. For this, you just
have to use the compiler switch \var{-pg}. The compiler will insert the
necessary stuff for profiling.

When you have done this, you can run your program as you would normally 
run it:
\begin{verbatim}
yourexe
\end{verbatim}
Where \file{yourexe} is the name of your executable.

When your program finishes, a file called gmon.out is generated. Then you can start
the profiler to see the output. You can benefit from redirecting the output to a file,
because it could be quite a lot:
\begin{verbatim}
gprof yourexe > profile.log
\end{verbatim}

Hint: you can use the \var{--flat} option to reduce the amount of output of gprof. It will
then only output the information about the timings.

For more information on the \gnu profiler \var{gprof}, see its manual.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Checking the heap
\section{Detecting heap memory leaks}
\label{se:heaptrc}
\fpc has a built in mechanism to detect memory leaks. There is a plug-in
unit for the memory manager that analyses the memory allocation/deallocation
and prints a memory usage report after the program exits.

The unit that does this is called \file{heaptrc}. If you want to use it,
you should include it as the first unit in your uses clause. Alternatively,
you can supply the \var{-gh} switch to the compiler, and it will include
the unit automatically for you.

After the program exits, you will get a report looking like this:
\begin{verbatim}
Marked memory at 0040FA50 invalid
Wrong size : 128 allocated 64 freed
  0x00408708
  0x0040CB49
  0x0040C481
Call trace for block 0x0040FA50 size 128
  0x0040CB3D
  0x0040C481
\end{verbatim}
The output of the heaptrc unit is customizable by setting some variables.
Output can also be customized using environment variables.

You can find more information about the usage of the \file{heaptrc} unit
in the \unitsref.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Verbose Run-time errors.
\section{Line numbers in run-time error backtraces}
\label{se:lineinfo}

Normally, when a run-time error occurs, you are presented with a list
of addresses that represent the call stack backtrace, i.e. the addresses
of all procedures that were invoked when the run-time error occurred.

This list is not very informative, so there exists a unit that generates
the file names and line numbers of the called procedures using the
addresses of the stack backtrace. This unit is called lineinfo.

You can use this unit by giving the \var{-gl} option to the compiler. The
unit will be automatically included. It is also possible to use the unit
explicitly in your \var{uses} clause, but you must make sure that you
compile your program with debug info.

Here is an example program:
\begin{verbatim}
program testline;

procedure generateerror255;

begin
  runerror(255);
end;

procedure generateanerror;

begin
  generateerror255;
end;

begin
  generateanerror;
end.
\end{verbatim}
When compiled with \var{-gl}, the following output is generated:
\begin{verbatim}
Runtime error 255 at 0x0040BDE5
  0x0040BDE5  GENERATEERROR255,  line 6 of testline.pp
  0x0040BDF0  GENERATEANERROR,  line 13 of testline.pp
  0x0040BE0C  main,  line 17 of testline.pp
  0x0040B7B1
\end{verbatim}
This is more understandable than the normal message. Make sure that all
units you use are compiled with debug info, because if they are not, no
line number and filename can be found.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Combining heaptrc and lineinfo
\section{Combining \file{heaptrc} and \file{lineinfo}}

If you combine the lineinfo and the heaptrc information, then the output
of the \file{heaptrc} unit will contain the names of the files and line
numbers of the procedures that occur in the stack backtrace.

In such a case, the output will look something like this:
\begin{verbatim}
Marked memory at 00410DA0 invalid
Wrong size : 128 allocated 64 freed
  0x004094B8
  0x0040D8F9  main,  line 25 of heapex.pp
  0x0040D231
Call trace for block 0x00410DA0 size 128
  0x0040D8ED  main,  line 23 of heapex.pp
  0x0040D231
\end{verbatim}
If lines without filename / line number occur, this means there is a unit which
has no debug info included (in the above case, the getmem call itself).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% APPENDICES.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\appendix
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% APPENDIX A.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{Alphabetical listing of command line options}
\label{ch:commandlineoptions}
The following is an alphabetical listing of all command line options, as
generated by the compiler:
\input{comphelp.inc}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% APPENDIX B.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{Alphabetical list of reserved words}
\label{ch:reserved}
\begin{multicols}{3}
\input{reserved.tex}
\end{multicols}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% APPENDIX C.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{Compiler messages}
\label{ch:ErrorMessages}
This appendix is meant to list all the compiler messages. The list of
messages is generated from he compiler source itself, and should be fairly
complete. At this point, only assembler errors are not in the list.

For an explanation of how to control the messages, \sees{feedbackoptions}.

% Message file is generated with msg2inc.
\input {messages.inc}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Assembler reader errors
\section{Assembler reader errors.}

This section lists the errors that are generated by the inline assembler reader.
They are {\em not} the messages of the assembler itself.

% General assembler errors.
\subsection{General assembler errors}
\begin{description}
\item [Divide by zero in asm evaluator]
This fatal error is reported when a constant assembler expression
performs a division by zero.

\item [Evaluator stack overflow, Evaluator stack underflow]
These fatal error is reported when a constant assembler expression
is too big to be evaluated by the constant parser. Try reducing the
number of terms.

\item [Invalid numeric format in asm evaluator]
This fatal error is reported when a non-numeric value is detected
by the constant parser. Normally this error should never occur.

\item [Invalid Operator in asm evaluator]
This fatal error is reported when a mathematical operator is detected
by the constant parser. Normally this error should never occur.

\item [Unknown error in asm evaluator]
This fatal error is reported when an internal error is detected
by the constant parser. Normally this error should never occur.

\item [Invalid numeric value]
This warning is emitted when a conversion from octal, binary 
or hexadecimal to decimal is outside of the supported range.

\item [Escape sequence ignored]
This error is emitted when a non ANSI C escape sequence is detected in
a C string.

\item [Asm syntax error - Prefix not found]
This occurs when trying to use a non-valid prefix instruction.

\item [Asm syntax error - Trying to add more than one prefix]
This occurs when you try to add more than one prefix instruction.

\item [Asm syntax error - Opcode not found]
You have tried to use an unsupported or unknown opcode.

\item [Constant value out of bounds]
This error is reported when the constant parser determines that the
value you are using is out of bounds, either with the opcode or with
the constant declaration used.

\item [Non-label pattern contains @]
This only applied to the m68k and Intel styled assembler. 
This is reported when you try to use a non-label identifier with an '@' prefix.
\item [Internal error in Findtype()]
\item [Internal Error in ConcatOpcode()]
\item [Internal Errror converting binary]
\item [Internal Errror converting hexadecimal]
\item [Internal Errror converting octal]
\item [Internal Error in BuildScaling()]
\item [Internal Error in BuildConstant()]
\item [internal error in BuildReference()]
\item [internal error in HandleExtend()]
\item [Internal error in ConcatLabeledInstr()]
\label{InternalError}
These errors should never occur. If they do then you have found
a new bug in the assembler parsers. Please contact one of the
developers.
\item [Opcode not in table, operands not checked]
This warning only occurs when compiling the system unit, or related
files. No checking is performed on the operands of the opcodes.

\item [@CODE and @DATA not supported]
This Turbo Pascal construct is not supported.
\item [SEG and OFFSET not supported]
This Turbo Pascal construct is not supported.
\item [Modulo not supported]
Modulo constant operation is not supported.
\item [Floating point binary representation ignored]
\item [Floating point hexadecimal representation ignored]
\item [Floating point octal representation ignored]
These warnings occur when a floating point constant is declared in
a base other than decimal. No conversion can be done on these formats.
You should use a decimal representation instead.
\item [Identifier supposed external]
This warning occurs when a symbol is not found in the symbol table. 
It is therefore considered external.
\item [Functions with void return value can't return any value in asm code]
Only routines with a return value can have a return value set.

\item [Error in binary constant]
\item [Error in octal constant]
\item [Error in hexadecimal constant]
\item [Error in integer constant]
\label{ErrorConst}
These errors are reported when you tried using a constant
expression that is invalid or whose value is out of range.

\item [Invalid labeled opcode]
\item [Asm syntax error - error in reference]
\item [Invalid Opcode]
\item [Invalid combination of opcode and operands]
\item [Invalid size in reference]
\item [Invalid middle sized operand]
\item [Invalid three operand opcode]
\item [Assembler syntax error]
\item [Invalid operand type]
You tried using an invalid combination of opcode and operands. Check the syntax
and if you are sure it is correct, please contact one of the developers.

\item [Unknown identifier]
The identifier you are trying to access does not exist, or is not within the
current scope.

\item [Trying to define an index register more than once]
\item [Trying to define a segment register twice]
\item [Trying to define a base register twice]
You are trying to define an index/segment register more than once.

\item [Invalid field specifier]
The record or object field you are trying to access does not exist, or
is incorrect.

\item [Invalid scaling factor]
\item [Invalid scaling value]
\item [Scaling value only allowed with index]
Allowed scaling values are 1,2,4 or 8.


\item [Cannot use SELF outside a method]
You are trying to access the SELF identifier for objects outside a method.


\item [Invalid combination of prefix and opcode]
This opcode cannot be prefixed by this instruction.

\item [Invalid combination of override and opcode]
This opcode cannot be overriden by this combination.

\item [Too many operands on line]
At most three operand instructions exist on the m68k, and i386, you
are probably trying to use an invalid syntax for this opcode.

\item [Duplicate local symbol]
You are trying to redefine a local symbol, such as a local label.

\item [Unknown label identifer]
\item [Undefined local symbol]
\item [local symbol not found inside asm statement]
This label does not seem to have been defined in the current scope.


\item [Assemble node syntax error]
\item [Not a directive or local symbol]
The assembler statement is invalid, or you are not using a recognized
directive.

\end{description}

% I386 specific errors
\subsection{I386 specific errors}

\begin{description}
\item [repeat prefix and a segment override on \var{<=} i386 ...]
A problem with interrupts and a prefix instruction may occur and may cause
false results on 386 and earlier computers.

\item [Fwait can cause emulation problems with emu387]
This warning is reported when using the FWAIT instruction. It can
cause emulation problems on systems which use the em387.dxe emulator.

\item [You need GNU as version >= 2.81 to compile this MMX code]
MMX assembler code can only be compiled using GAS v2.8.1 or later.

\item [NEAR ignored]
\item [FAR ignored]
\label{FarIgnored}
\var{NEAR} and \var{FAR} are ignored in the Intel assemblers, but 
are still accepted for compatiblity with the 16-bit code model.

\item [Invalid size for MOVSX/MOVZX]

\item [16-bit base in 32-bit segment]
\item [16-bit index in 32-bit segment]
16-bit addressing is not supported. You must use 32-bit addressing.


\item [Constant reference not allowed]
It is not allowed to try to address a constant memory address in protected
mode.

\item [Segment overrides not supported]
Intel style (eg: rep ds stosb) segment overrides are not supported by
the assembler parser.

\item [{Expressions of the form [sreg:reg...] are currently not supported}]
To access a memory operand in a different segment, you should use the
sreg:[reg...] snytax instead of [sreg:reg...]

\item [Size suffix and destination register do not match]
In intel AT\&T syntax, you are using a register size which does
not concord with the operand size specified.

\item [Invalid assembler syntax. No ref with brackets]
\item [ Trying to use a negative index register ]
\item [ Local symbols not allowed as references ]
\item [ Invalid operand in bracket expression ]
\item [ Invalid symbol name:  ]
\item [ Invalid Reference syntax ]
\item [ Invalid string as opcode operand: ]
\item [ Null label references are not allowed ]
\item [ Using a defined name as a local label ]
\item [ Invalid constant symbol  ]
\item [ Invalid constant expression ]
\item [ / at beginning of line not allowed ]
\item [ NOR not supported ]
\item [ Invalid floating point register name ]
\item [ Invalid floating point constant:  ]
\item [ Asm syntax error - Should start with bracket ]
\item [ Asm syntax error - register:  ]
\item [ Asm syntax error - in opcode operand ]
\item [ Invalid String expression ]
\item [ Constant expression out of bounds ]
\item [ Invalid or missing opcode ]
\item [ Invalid real constant expression ]
\item [ Parenthesis are not allowed ]
\item [ Invalid Reference ]
\item [ Cannot use \_\_SELF outside a method ]
\item [ Cannot use \_\_OLDEBP outside a nested procedure ]
\item [ Invalid segment override expression ]
\item [ Strings not allowed as constants ]
\item [ Switching sections is not allowed in an assembler block ]
\item [ Invalid global definition ]
\item [ Line separator expected ]
\item [ Invalid local common definition ]
\item [ Invalid global common definition ]
\item [ assembler code not returned to text ]
\item [ invalid opcode size ]
\item [ Invalid character: < ]
\item [ Invalid character: > ]
\item [ Unsupported opcode ]
\item [ Invalid suffix for intel assembler ]
\item [ Extended not supported in this mode ]
\item [ Comp not supported in this mode ]
\item [ Invalid Operand: ]
\item [ Override operator not supported ]
\end{description}

% m68k specific errors
\subsection{m68k specific errors.}
\begin{description}
\item [Increment and Decrement mode not allowed together]
You are trying to use dec/inc mode together.

\item [Invalid Register list in movem/fmovem]
The register list is invalid. Normally a range of registers should
be separated by - and individual registers should be separated by
a slash.
\item [Invalid Register list for opcode]
\item [68020+ mode required to assemble]
\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Runtime errors listing
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Run-time errors}

Applications generated  by \fpc might generate run-time errors when certain 
abnormal conditions are detected in the application. This appendix lists the 
possible run-time errors and gives information on why they might be produced.

\begin{description}
\item [1  Invalid function number]
An invalid operating system call was attempted.

\item [2  File not found]
Reported when trying to erase, rename or open a non-existent
file.

\item [3  Path not found]
Reported by the directory handling routines when a path does not 
exist or is invalid. Also reported when trying to access a 
non-existent file.

\item [4  Too many open files]
The maximum number of files currently opened by your process
has been reached. Certain operating systems limit the number
of files which can be opened concurrently, and this error
can occur when this limit has been reached.

\item [5  File access denied]
Permission to access the file is denied. This error might
be caused by one of several reasons:
\begin{itemize}
\item Trying to open for writing a file which is
read-only, or which is actually a directory.
\item File is currently locked or used by another process.
\item Trying to create a new file, or directory while a 
file or directory of the same name already exists.
\item Trying to read from a file which was opened in write-only mode.
\item Trying to write from a file which was opened in read-only mode.
\item Trying to remove a directory or file while it is not possible.
\item No permission to access the file or directory.        
\end{itemize}

\item [6  Invalid file handle]
If this happens, the file variable you are using is trashed; it
indicates that your memory is corrupted.

\item [12  Invalid file access code]
Reported when a reset or rewrite is called with an invalid \var{FileMode}
value.

\item [15  Invalid drive number]
The number given to the \var{Getdir} or \var{ChDir} function specifies a 
non-existent disk.

\item [16  Cannot remove current directory]
Reported when trying to remove the currently active directory.

\item [17  Cannot rename across drives]
You cannot rename a file such that it would end up on another disk or
partition.

\item [100  Disk read error]
An error occurred when reading from disk. Typically happens when you try
to read past the end of a file.

\item [101  Disk write error]
Reported when the disk is full, and you're trying to write to it.

\item [102  File not assigned]
This is reported by \var{Reset}, \var{Rewrite}, \var{Append}, 
\var{Rename} and \var{Erase}, if you call
them with an unassigned file as a parameter.

\item [103  File not open]
Reported by the following functions : \var{Close, Read, Write, Seek,
EOf, FilePos, FileSize, Flush, BlockRead,} and \var{BlockWrite} if the 
file is not open.

\item [104  File not open for input]
Reported by \var{Read, BlockRead, Eof, Eoln, SeekEof} or \var{SeekEoln} if 
the file is not opened with \var{Reset}.

\item [105  File not open for output]
Reported by write if a text file isn't opened with \var{Rewrite}.

\item [106  Invalid numeric format]
Reported when a non-numeric value is read from a text file, and a numeric
value was expected.

\item [150  Disk is write-protected]
(Critical error)
\item [151  Bad drive request struct length]
(Critical error)
\item [152  Drive not ready]
(Critical error)
\item [154  CRC error in data]
(Critical error)
\item [156  Disk seek error]
(Critical error)
\item [157  Unknown media type]
(Critical error)
\item [158  Sector Not Found]
(Critical error)
\item [159  Printer out of paper]
(Critical error)
\item [160  Device write fault]
(Critical error)
\item [161  Device read fault]
(Critical error)
\item [162  Hardware failure]
(Critical error)
\item [200  Division by zero]
The application attempted to divide a number by zero.
\item [201  Range check error]
If you compiled your program with range checking on, then you can get this
error in the following cases:
\begin{enumerate}
\item An array was accessed with an index outside its declared range.
\item Trying to assign a value to a variable outside its range (for
instance an enumerated type).
\end{enumerate}
\item [202  Stack overflow error]
The stack has grown beyond its maximum size (in which case the size of 
local variables should be reduced to avoid this error), or the stack has 
become corrupt. This error is only reported when stack checking is enabled.
\item [203  Heap overflow error]
The heap has grown beyond its boundaries. This is caused when trying to allocate
memory explicitly with \var{New}, \var{GetMem} or \var{ReallocMem}, or when
a class or object instance is created and no memory is left. Please note 
that, by default, \fpc provides a growing heap, i.e. the heap will
try to allocate more memory if needed. However, if the heap has reached the
maximum size allowed by the operating system or hardware, then you will get
this error.
\item [204  Invalid pointer operation]
You will get this if you call \var{Dispose} or \var{Freemem} with an invalid 
pointer (notably, \var{Nil}).
\item [205  Floating point overflow]
You are trying to use or produce real numbers that are too large.
\item [206  Floating point underflow]
You are trying to use or produce real numbers that are too small.
\item [207  Invalid floating point operation]
Can occur if you try to calculate the square root or logarithm of a negative
number.
\item [210  Object not initialized]
When compiled with range checking on, a program will report this error if
you call a virtual method without having called its object's constructor.
\item [211  Call to abstract method]
Your program tried to execute an abstract virtual method. Abstract methods
should be overridden, and the overriding method should be called.
\item [212  Stream registration error]
This occurs when an invalid type is registered in the objects unit.
\item [213  Collection index out of range]
You are trying to access a collection item with an invalid index
(\var{objects} unit).
\item [214  Collection overflow error]
The collection has reached its maximal size, and you are trying to add
another element (\var{objects} unit).
\item[215 Arithmetic overflow error]
This error is reported when the result of an arithmetic operation
is outside of its supported range. Contrary to Turbo Pascal, this error
is only reported for 32-bit or 64-bit arithmetic overflows. This is due
to the fact that everything is converted to 32-bit or 64-bit before
doing the actual arithmetic operation.
\item [216  General Protection fault]
The application tried to access invalid memory space. This can
be caused by several problems:
\begin{enumerate}
 \item Dereferencing a \var{nil} pointer.
 \item Trying to access memory which is out of bounds
       (for example, calling \var{move} with an invalid length).
\end{enumerate}

\item [217 Unhandled exception occurred]
An exception occurred, and there was no exception handler present.
The \var{sysutils} unit installs a default exception handler which catches
all exceptions and exits gracefully.

\item [219 Invalid typecast]

Thrown when an invalid typecast is attempted on a class using the \var{as}
operator. This error is also thrown when an object or class is
typecast to an invalid class or object and a virtual method of
that class or object is called. This last error is only detected
if the \var{-CR} compiler option is used.


\item[222 Variant dispatch error]
No dispatch method to call from variant.

\item[223 Variant array create]
The variant array creation failed. Usually when there is not enough memory.

\item[224 Variant is not an array]
This error occurs when a variant array operation is attempted on a variant
which is not an array.

\item[225 Var Array Bounds check error]
This error occurs when a variant array index is out of bounds.

\item [227 Assertion failed error]
An assertion failed, and no \var{AssertErrorProc} procedural variable was 
installed.

\item [229 Safecall error check]
This error occurs is a safecall check fails, and no handler routine is
available.

\item [231 Exception stack corrupted]
This error occurs when the exception object is retrieved and none is
available.

\item [232 Threads not supported]
Thread management relies on a separate driver on some operating systems
(notably, Unixes). The unit with this driver needs to be specified on
the uses clause of the program, preferably as the first unit
(\file{cthreads} on unix).

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%  GDB Configuration file
\chapter{A sample \file{gdb.ini} file}
\label{ch:GdbIniFile}

Here you have a sample \file{gdb.ini} file listing, which gives better
results when using \var{gdb}. Under \linux you should put this in a
\file{.gdbinit} file in your home directory or the current directory.

\begin{verbatim}
set print demangle off
set gnutarget auto
set verbose on
set complaints 1000
dir ./rtl/dosv2
set language c++
set print vtbl on
set print object on
set print sym on
set print pretty on
disp /i $eip

define pst
set $pos=&$arg0
set $strlen = {byte}$pos
print {char}&$arg0.st@($strlen+1)
end

document pst
  Print out a Pascal string
end
\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Options summary tables
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\input{options.tex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%  Downloading sources.
\chapter{Getting the latest sources or installers}
\label{ch:sourcedownload}

Free Pascal is under continuous development. From time to time, a new
set of installers with what are considered stable sources are made: these
are the releases. They can be downloaded from the Free Pascal website.
The downloads usually contain the sources from which the release is made.

If for some reason, a newer set of files is needed - for instance, because
certain bugs that prevent a program from functioning correctly have been
fixed, it is possible to download the latest source files and recompile
them.

Note that the latest sources may or may not compile: sometimes things get
broken, and then the downloaded sources are useless. For the fixes branches
(mentioned below) the sources should always compile, so it may be best
to use these only.

There are 3 ways to get the latest version.

\section{Download via Subversion}
All Free Pascal sources are in subversion, and can be downloaded anonymously
from the Subversion server. With a suitable Subversion client, the following
locations can be used:
\begin{verbatim}
http://svn.freepascal.org/svn/fpc/trunk/
\end{verbatim}
This repository contains the latest sources of the compiler, RTL and packages. 
This is the active development branch.

The documentation and all examples from the documentation are in the
following repository
\begin{verbatim}
http://svn.freepascal.org/svn/fpcdocs/trunk/
\end{verbatim}

All the files needed to make a release can be retrieved from
\begin{verbatim}
http://svn.freepascal.org/svn/fpcbuild/trunk/
\end{verbatim}
This repository contains external links to the other 2 repositories, and
contains all scripts, demos and other files needed to construct a new
release of Free Pascal.

Free Pascal maintains a fixes branch, which is used to create new releases
after a major version change. The branches are located in 
\begin{verbatim}
http://svn.freepascal.org/svn/fpc/branches/fpc_X_Y
\end{verbatim}
Where X and Y make up the major release number of Free Pascal. 
For instance, the fixes used to make the 2.2.x versions of Free Pascal are
available in
\begin{verbatim}
http://svn.freepascal.org/svn/fpc/branches/fixes_2_2
\end{verbatim}

The Subversion archive is mirrored on the server
\begin{verbatim}
svn2.freepascal.org
\end{verbatim}

\section{Downloading a source zip}
Every day, a zip is made which contains the sources as they are on this day,
they are available from the FTP site:
\begin{verbatim}
http://ftp.freepascal.org/develop.var
\end{verbatim}
This will lead to a download of the sources of the development branch:
\begin{verbatim}
ftp://ftp.freepascal.org/pub/fpc/snapshot/trunk/source/fpc.zip
\end{verbatim}
and also of the fixes branch:
\begin{verbatim}
ftp://ftp.freepascal.org/pub/fpc/snapshot/fixes/source/fpc.zip
\end{verbatim}
The creation of the zip files is an automated process, and so these files 
are created every day.

\section{Downloading a snapshot}
Some members of the Free Pascal team also maintain installable snapshots.
These are installers, made with the sources of that day. Since the sources
are not guaranteed to work, a snapshot of a certain day may not be
available, or the person responsible for it didn't have the opportunity to
make one: these snapshots may or may not be available. They can be
downloaded from the same page as the daily source zip:
\begin{verbatim}
http://ftp.freepascal.org/develop.var
\end{verbatim}
The snapshots are made for the development branch as well as for the fixes
branch. They are available from
\begin{verbatim}
ftp://ftp.freepascal.org/pub/fpc/snapshot/trunk/
\end{verbatim}
and
\begin{verbatim}
ftp://ftp.freepascal.org/pub/fpc/snapshot/fixes/
\end{verbatim}
respectively.

The FTP site is mirrored, it may be faster to use a mirror.

\end{document}