%
%   $Id: user.tex,v 1.26 2004/05/18 22:10:56 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(Users' Guide)
           /Subject(Free Pascal Users' guide)
           /Keywords(Free Pascal)
           }
  \fi
\end{latexonly}

%
% Settings
%
\makeindex
%
% Start of document.
%
\begin{document}
\title{Free Pascal :\\ Users' manual}
\docdescription{Users' manual for \fpc, version \fpcversion}
\docversion{1.10}
\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 manual 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-bit compiler for the i386 and m68k processors. Currently, 
it supports the following operating systems:
\begin{itemize}
\item \dos
\item \linux % (Intel and m68k)
\item \amiga (version 0.99.5 only)
\item \windows
\item \ostwo (using the EMX package, so it also works on DOS/Windows)
\item \freebsd
\item \beos (under development)
\item \solaris (under development)
\item \palmos(under development)
\item \netbsd 
\item \openbsd (under development)
\end{itemize}

\fpc is designed to be, as much as possible, source compatible with
Turbo Pascal 7.0 and Delphi 5 (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.

Also, at the time of writing, there is a beta version of an
Integrated Development Environment (IDE) available for \fpc.

\fpc consists of three parts :
\begin{enumerate}
\item The compiler program itself.
\item The Run-Time Library (RTL).
\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. The RTL is described in the
\refref.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% 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, on 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 inscribing to the
\textit{mailing-list}.

\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{System requirements}
The compiler needs at least the following hardware:
\begin{enumerate}
\item An Intel 80386 or higher processor (for the intel version). 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 4 Megabytes of free memory. 
\item At least 3 Megabytes free disk space.
\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 distribution contains 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{http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/index.html}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% 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 DOS or Windows}
\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 file contains an
installation program \file{INSTALL.EXE}. You must run this program to install
the compiler.

The screen of the 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\BIN\GO32V2
\end{verbatim}
for \dos or 
\begin{verbatim}
  SET PATH=%PATH%;C:\PP\BIN\WIN32
\end{verbatim}
for \windows and finally
\begin{verbatim}
  SET PATH=%PATH%;C:\PP\BIN\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 seperate files.
\item a \file{.rpm} (Red Hat Package Manager) version, and
\item a \file{.deb} (Debian) version.
\end{itemize}
All of these packages contain a \var{ELF} version of the compiler binaries and
units. the older \var{aout} binaries are no longer distributed, although you
still can use the comiler on an \var{aout} system if you recompile it.

If you use the \file{.rpm} format, installation is limited to
\begin{verbatim}
rpm -i fpc-pascal-XXX.rpm
\end{verbatim}
(\var{XXX} is the version number of the \file{.rpm} file)

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 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\hello.pp|) 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\units\go32v2\rtl hello
\end{verbatim}
under \dos, and under \linux you could type
\begin{verbatim}
fpc -Fu/usr/lib/fpc/NNN/units/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}
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 a \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}

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 is being compiled.
\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 this 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/VERSION
or
  /usr/lib/fpc/VERSION
\end{verbatim}
whichever is found first.
\item On other OSes: the compiler binary directory, with '../' appended
to it, if it exists.
\end{itemize}
After this directory is determined , the following paths are added to the
search path:
\begin{enumerate}
\item FPCDIR/units/TARGET
\item FPCDIR/units/TARGET/rtl
\end{enumerate}
Here target must be replaced by the name of the target you are compiling for.
\end{enumerate}
You can see what paths the compiler will search by giving the compiler
the \var{-vu} option.

On systems where filenames to lower-case (such as \unix and \linux), the compiler 
will first convert the filename of a unit to all-lowercase. This is necessary, 
since Pascal is case-independent, and the statements \var{Uses Unit1;} or 
\var{uses unit1;} should have the same effect.

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.

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 compile 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}

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 files 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} directory 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}

Starting from version 1.0.6 of the compiler, usage of the
file \file{ppc386.cfg} is considered deprecated. The file
should now be called \file{fpc.cfg} and will work for
all processor targets. For compatibility, \file{fpc.cfg} will
be searched first, and if not found, the file \file{ppc386.cfg}
will be used.

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 In your home directory, it looks for \file{.fpc.cfg}.
\item The directory specified in the environment variable
\var{PPC\_CONFIG\_PATH}, and if it's not set under \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}

\subsection{About long filenames}
\fpc can handle long filenames under \windows; it will use support for
long filenames if it is available.

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 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
extensions \file{.o}. This contains the object file for your program.
If you compiled a program, you can delete the object file (\file{.o}),
but not if you compiled a unit.

Then the object file contains the code of the unit, and will be
linked in any program that uses the unit you compiled, so you shouldn't
remove 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.

\begin{remark}
Under \linux and \unix, a unit source file {\em must} have a lowercase filename.
Since Pascal is case independent, you can specify the names of units in the
\var{uses} clause in either case. To get a unique filename, the \fpc compiler
changes the name of the unit to all lowercase when looking for unit files.
\end{remark}
The compiler produces lowercase files, so your unit will be found, even if
your source file has uppercase letters in it. Only when the compiler tries to
recompile the unit, it will not find your source because of the uppercase
letters.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% 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 1 big object
file, which will be linked as a whole into your program.

Not only is it possible to compile a shared library under \windows and
\linux, but also it is possible to take existing units and put them
together in 1 static or shared library (using the \file{ppumove} tool)

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Creating an executable for GO32V1, PMODE/DJ targets
\section{Creating an executable for GO32V1 and PMODE/DJ targets}
\label{go32v1}

The GO32V1 platform is officially no longer supported, so this section
is of interest only to people who wish to make go32V1 binaries anyway.

%
% GO32V1
%
\subsection{GO32V1}
When compiling under \dos, GO32V2 is the default target. However, if you use
go32V1 (using the \var{-TGO32V1} switch), the
compilation process leaves you with a file which you cannot execute right away.
There are 2 things you can do when compiling has finished.

The first thing is to use the \dos extender from D.J. Delorie to execute
your program :
\begin{verbatim}
  go32 prog
\end{verbatim}
This is fine for testing, but if you want to use a program regularly, it
would be easier if you could just type the program name, i.e.
\begin{verbatim}
  prog
\end{verbatim}
This can be accomplished by making a \dos executable of your compiled program.

There two ways to create a \dos executable (under \dos only):
\begin{enumerate}
\item if the \file{GO32.EXE} is already
installed on the computers where the program should run, you must
only copy a program called \file{STUB.EXE} at the begin of
the AOUT file. This is accomplished with the \file{AOUT2EXE.EXE} program.
which comes with the compiler:
\begin{verbatim}
AOUT2EXE PROG
\end{verbatim}
and you get a \dos executable which loads the \file{GO32.EXE} automatically.
the \file{GO32.EXE} executable must be in current directory or be
in a directory in the \var{PATH} variable.
\item
The second way to create a \dos executable is to put
\file{GO32.EXE} at the beginning of the \file{AOUT} file. To do this, at the
command prompt, type :
\begin{verbatim}
COPY /B GO32.EXE+PROG PROG.EXE
\end{verbatim}
(assuming \fpc created a file called \file{PROG}, of course.)
This becomes then a stand-alone executable for \dos, which doesn't need the
\file{GO32.EXE} on the machine where it should run.
\end{enumerate}

%
%

% PMODE/DJ
\subsection{PMODE/DJ}
You can also use the PMODE/DJ extender to run your \fpc applications.
To make an executable which works with the PMODE extender, you can simply
create an GO32V2 executable (the default), and then convert it to a PMODE
executable with the following two extra commands:
\begin{enumerate}
\item First, strip the GO32V2 header of the executable:
\begin{verbatim}
EXE2COFF PROG.EXE
\end{verbatim}
(we suppose that \file{PROG.EXE} is the program generated by the compilation
process.
\item Secondly, add the PMODE stub:
\begin{verbatim}
COPY /B PMODSTUB.EXE+PROG PROG.EXE
\end{verbatim}
If the \file{PMODSTUB.EXE} file isn't in your local directory, you need to
supply the whole path to it.
\end{enumerate}

That's it. No additional steps are needed to create a PMODE extender
executable.

Be aware, though, that the PMODE extender doesn't support virtual memory, so
if you're short on memory, you may run unto trouble. Also, officially there
is not support for the PMODE/DJ extender. It just happens that the compiler
and some of the programs it generates, run under this extender too.


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

When you created your program, it is possible to reduce its size. This
is possible, because the compiler leaves a lot of information in the
program which, strictly speaking, isn't required for the execution of
it. 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 the can be smartlinked.
This means that only the functions and procedures are linked in your
program, leaving out any unnecessary code. 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 op
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 the \file{AUTOEXEC.BAT}.\\
To solve this problem, you must extend your environment memory.
To do this, search a line in the \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 the command line
options are 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 version 1.0.6 of the compiler are listed by
category (see appendix A for a listing as generated by the compiler):

%
% General options
%

\subsection{General options}
\begin{description}
\item[-h] if you specify this option, the compiler outputs a list of all options,
and exits after that.
\olabel{h}
\item[-?] idem as \var{-h}, waiting after every screenfull for the enter key.
\item[-i] This option tells the compiler to print the copyright information.
\olabel{i} You can give it an option, as \var{-ixxx} where xxx can be one of the
following:
\begin{description}
\item[D] : Returns the compiler date.
\item[V] : Returns the 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] This option tells the compiler to print the \fpc logo on standard
output. It also gives you the \fpc version number.
\olabel{l}
\item [-n] Tells the compiler not to read default the 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}
\begin{description}
\item[-vxxx] Be verbose. \var{xxx} is a combination of the following :
\olabel{v}
\begin{itemize}
\item \var{e} : Tells the compiler to show only errors. This option is on by default.
\item \var{i} : Tells the compiler to show some general information.
\item \var{w} : Tells the compiler to issue warnings.
\item \var{n} : Tells the compiler to issue notes.
\item \var{h} : Tells the compiler to issue hints.
\item \var{l} : Tells the compiler to show the line numbers as it processes a
file. Numbers are shown per 100.
\item \var{u} : Tells the compiler to print information on the units it loads.
\item \var{t} : Tells the compiler to print the names of the files it tries
to open.
\item \var{p} : Tells the compiler to print the names of procedures and
functions as it is processing them.
\item \var{c} : Tells the compiler to warn you when it processes a
conditional.
\item \var{m} : Tells the compiler to write which macros are defined.
\item \var{d} : Tells the compiler to write other debugging info.
\item \var{a} : Tells the compiler to write all possible info. (this is the
same as specifying all options)
\item \var{0} : Tells the compiler to write no messages. This is useful when
you want to override the default setting in the configuration file.
\item \var{b} : Tells the compiler to show all procedure declarations if an
overloaded function error occurs.
\item \var{x} : Tells the compiler to output some executable info (for Win32
platform only).
\item \var{r} : Rhide/GCC compatibility mode: formats the errors
differently, so they are understood by RHIDE.
\end{itemize}
\end{description}

%
% Options concerning files and directories
%
\subsection{Options concerning files and directories}
\begin{description}
\item [-exxx] \file{xxx} specifies the directory where the
compiler can find the executables \file{as} (the assembler) and \file{ld}
(the linker).
\olabel{e}
\item [-FD] same as \var{-e}.
\item [-Fexxx] This option tells the compiler to write errors, etc. to
the file named \file{xxx}.
\olabel{Fe}
\item [-FExxx] tells the compiler to write the executable and units in
directory \file{xxx} instead of th current directory.
\olabel{FE}
\item [-Fixxx] Adds \var{xxx} to the include file search path.
\olabel{Fi}
\item [-Flxxx] Adds \var{xxx} to the library searching path, and is passed
to the linker.
\olabel{Fl}
\item[-FLxxx] (\linux only) Tells the compiler to use \file{xxx} as the
dynamic linker. Default this is \file{/lib/ld-linux.so.2}, or
\file{/Hlib/ld-linux.so.1}, depending on which one is found first.
\olabel{FL}
\item[-Foxxx] Adds \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] \file{xxx} specifies the file which contain the compiler
messages. Default the compiler has built-in messages. Specifying this option
will override the default messages.
\olabel{Fr}
\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.
\olabel{Fu}
\item [-FUxxx] Tells the compiler to write units in 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...
\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 also \progref
\begin{description}
\item [-a] \olabel{a} Tells the compiler not to delete the assembler files
it generates (not when using the internal assembler).
This also counts for the (possibly) generated batch script.
\item [-al] \olabel{al} Tells the compiler to include the sourcecode lines
in the assembler file as comments.
\item[-ar] \olabel{ar} tells the compiler to 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} tells the compiler to list information about
temporary allocations and deallocations in the assembler file.
\item [-Axxx] \olabel{A} specifies what kind of assembler should be generated . Here
\var{xxx} is one of the following :
\begin{description}
\item[as] assemble using \gnu as.
\item[asaout] assemble using \gnu as for aout (Go32v1).
\item[nasmcoff] coff (Go32v2) file using Nasm.
\item[nasmelf] elf32 (Linux) file using Nasm.
\item[nasmobj] object file using Nasm.
\item[masm] object file using Masm (Microsoft).
\item[tasm] object file using Tasm (Borland).
\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} tells the compiler to re-compile all used units, even
if the unit sources didn't change since the last compilation.
\item[-b] \olabel{b} tells the compiler to 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} is the same as \var{-b} but also generates
information about local variables, types and procedures.
\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[-CeXXX] set the used floating point emulation.
\item[-CfXXX] set the used floating point processor.
\item[-Cg] enable generation of PIC code.
\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 [-CpXXX] set the processor type to XXX
\item [-Cr] \olabel{Cr} Generate Range checking code. In case your program
acesses an array element with an invalid index, or if it increases an
enumerated type beyond it's 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. In case 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 {-E} \olabel{E} Same as \var{-Cn}.
\item [-g] \olabel{g} Generate debugging information for debugging with
\file{gdb}
\item [-gg] idem as \var{-g}.
\item [-gd] \olabel{gd} generate debugging info for \file{dbx}.
\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 [-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[-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[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[Pn] (Intel only) Specify processor: \var{n} can be one of
\begin{description}
\item[1] optimize for 386/486
\item[2] optimize for Pentium/PentiumMMX (tm)
\item[3] optimizations for PentiumPro/PII/Cyrix 6x86/K6 (tm)
\end{description}
\end{description}
The exact effect of these effects can be found in the \progref.
\item [-oxxx] Tells the compiler to use \var{xxx} as the name of the output
file (executable). Only with programs.
\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} Tells the compiler not to 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 some extra parameter, mainly
used for cross-compilation.
\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 must be run)
\item[r] Skip register allocation phase (optimizations will be disabled).
\end{description}
\item[-Txxx] \olabel{T} Specifies the target operating system. \var{xxx} can be one of
the following:
\begin{itemize}
\item \textbf{GO32V1} : \dos and version 1 of the DJ DELORIE extender (no longer maintained).
\item \textbf{GO32V2} : \dos and version 2 of the DJ DELORIE extender.
\item \textbf{LINUX} : \linux.
\item \textbf{OS2} : OS/2 (2.x) using the \var{EMX} extender.
\item \textbf{WIN32} : \windows 32 bit.
\item \textbf{SUNOS} : SunOS/Solaris.
\item \textbf{BEOS} : BeOS.
\end{itemize}
\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 relocation section.
\item[R] Generate a relocation section.
\item[T] Generate a TOOL application (+) or a console application (-).
\end{description}
\item [-Xx] \olabel{X} 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} : Link with dynamic libraries (defines the
\var{FPC\_LINK\_DYNAMIC} symbol) \olabel{XD}
\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{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 also \progref
\begin{description}
\item[-Mmode] set language mode to \var{mode}, which can be one of the
following:
\begin{description}
\item[delphi] tries 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] tries to be gpc compatible.
\item[macpas] tries to be compatible to the macintosh pascal dialects.
\item[objfpc] switch some Delphi 2 extensions on. This is different from 
Delphi mode. because some \fpc constructs are still available.
\item[tp] tries to be TP/BP 7.0 compatible. This means, no function overloading
etc.
\end{description}
\item [-Rxxx] \olabel{R} Specifies 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 [direct] \var{asm} blocks should be copied as-is in the assembler,
only replacing certain variables.
file.
\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} Tells the compiler 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).
\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 keyword is
specified, the compiler will interpret the \var{string} keyword as a
ansistring. Otherwise it is supposed to be a short strings (TP style).
\item [-Si] \olabel{Si} Support \var{C++} style INLINE.
\item [-SIXXX] set interfaces style to XXX.
\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 [-Un] \olabel{Un} Do not check the unit name. Normally, the unit name
is the same as the filename. This option allows both 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 like 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 some kind of preprocessing. It understands the
following directives, which you should place 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. 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 compatile 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 skipped read 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}
#IFDEF VER0_99_5
-Fu/usr/lib/fpc/0.99.5/linuxunits
#ENDIF
\end{verbatim}
In the above example, \file{/usr/lib/fpc/0.99.5/linuxunits} will be added to
the path if you're compiling with version 0.99.5 of the compiler.

\subsection{\#IFNDEF}
Syntax:
\begin{verbatim}
#IFNDEF name
\end{verbatim}
Lines following \var{\#IFNDEF} are skipped read 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}
#IFNDEF VER0_99_5
-Fu/usr/lib/fpc/0.99.6/linuxunits
#ENDIF
\end{verbatim}
In the above example, \file{/usr/lib/fpc/0.99.6/linuxunits} will be added to
the path if you're NOT compiling with version 0.99.5 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 skipped read if the preceding \var{\#IFDEF}
or \var{\#IFNDEF} was accepted.

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

Example :
\begin{verbatim}
#IFDEF VER0_99_5
-Fu/usr/lib/fpc/0.99.5/linuxunits
#ELSE
-Fu/usr/lib/fpc/0.99.6/linuxunits
#ENDIF
\end{verbatim}
In the above example, \file{/usr/lib/fpc/0.99.5/linuxunits} will be added to
the path if you're compiling with version 0.99.5 of the compiler,
otherwise \file{/usr/lib/fpc/0.99.6/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 it.

\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[FPCVER] is replaced by the compiler's full version string.
\item[FPCDATE] is replaced by the compiler's date.
\item[FPCTARGET] is replaced by the compiler's target CPU
(deprecated).
\item[FPCCPU] is also replaced by the compiler's target CPU.
\item[TARGET] is replaced by the compiler's target OS (deprecated).
\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/$FPCVER/rtl/$FPCOS
\end{verbatim}
This is equivalent to
\begin{verbatim}
-Fu/usr/lib/fpc/0.99.12a/rtl/linux
\end{verbatim}
If the compiler version is \var{0.99.12a} and the target os is \var{linux}.

These replacemens 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 expand the variable for you, which may have
undesired effects.

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

\input{ide.tex}

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

\chapter{Porting Turbo Pascal Code}

\fpc was designed to resemble Turbo Pascal as closely as possible. There
are, of course, restrictions. Some of these are due to the fact that \fpc is
a 32-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{-So} or \var{-S2}
switches.

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


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Things that will not work
\section{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 not allowed. This is a bug in Turbo Pascal
and will not be changed.
\item Parameter lists of previously defined functions and procedures must
match exactly. The reason for this is the function overloading mechanism of
\fpc. (however, the \seeo{So} option solves this.)
\item The \var{MEM, MEMW, MEML} and \var{PORT} variables 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.PPU}) implements the mem constuct.
under \linux, the \file{ports} unit implements such a construct.
\item \var{PROTECTED, PUBLIC, PUBLISHED, TRY, FINALLY, EXCEPT, RAISE}
are reserved words. This means you cannot create procedures or variables
with the same name. While they are not reserved words in Turbo Pascal,
they are in Delphi. Using the \var{-So} switch will solve this problem if
you want to compile Turbo Pascal code that uses these words.
\item The reserved words \var{FAR, NEAR} are ignored. This is
because \fpc is a 32 bit compiler, so they're obsolete.
\item \var{INTERRUPT} will work only on the \dos target.
\item Boolean expressions are only evaluated until their result is completely
determined. The rest of the expression will be ignored. This is
configurable as of FPC 1.9.
\item By default the 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 \progref.
\item Turbo Vision is not completely available. There is FreeVision, but the
degree of compatibility with Turbo Vision is unclear at this
time\footnote{At the time of writing, FreeVision has been taken off the
net, because there are some copyright issues which make it impossible to
distribute it.}.
\item The 'overlay' unit is not available. It also isn't necessary, since
\fpc is a 32 bit compiler, so program size shouldn't be a point.
\item There are more reserved words. (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.
\item Sets are always 4 bytes in Free Pascal; this means that some typecasts
which were possible in Turbo Pascal are no longer possible in Free Pascal.
\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 Destructors cannot have parameters. This restriction can be solved by
using the \var{-So} switch.
\item There can be only one destructor. This restriction can also be
solved 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)}.
\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Things which are extra
\section{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 There are more reserved words. (see appendix \ref{ch:reserved} for a
list of all reserved words.)
\item Functions can also return complex types, such as records and arrays.
\item You can handle function results in the function itself, as a variable.
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. To do a recursive call in
this you must append \var{()} behind 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 There is partial support of Delphi constructs. (see the \progref for
more information on this).
\item The \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 \seeo{So} switch disables overloading. When you use it, the above will
compile, as in Turbo Pascal.
\item Operator overloading. \fpc allows to overload operators, i.e. you can
define e.g. the '+' operator for matrices.
\item On FAT16 and FAT32 systems, long file names are supported.
\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Turbo Pascal compatibility mode
\section{Turbo Pascal compatibility mode}
When you compile a program with the \var{-So} 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 a @ 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 recusively 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}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% A note about long file names.
\section{A note on long file names under \dos}
Under \windows 95 and higher, long filenames are supported. Compiling
for the win32 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 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 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 Win32 applications;


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

\chapter{Utilities that come with Free Pascal}
\label{ch:Utilities}
Besides the compiler and the Run-Time 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}
Also distributed with \fpc comes a series of demonstration programs.
These programs have no other purpose than demonstrating the capabilities of
\fpc. They are located in the \file{demo} directory of the sources.

All example programs of the documentation are available. Check out the
directories that end on \file{ex} in the documentation sources. There you
will find all example sources.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Supplied programs
\section{Supplied programs}

\subsection{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}


\subsection{ppumove program}

\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 should be 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:\ ] If specified, ppumve will 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
\file{pmove.bat} otherwise.
\item[-d xxx:\ ] If specified, the output files will put in the directory
\file{xxx}
\item[-e xxx:\ ] Sets 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:\ ] sets 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:\ ] Causes \file{ppumove} to operate silently.
\item [-s:\ ] Tells \file{ppumove} to make a static library instead of a
dynamic one; By default a dynamic library is made on \linux.
\item [-w:\ ] Tells ppumove that it is working under \windowsnt. This will
change the names of te linker and archiving program to \file{ldw} and
\file{arw}, respectively.
\item[-h or -?:\ ] will display a short help.
\end{description}

The action of the ppumve program is as follows:
It takes each of the unit files, and modifies it so that the compile 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}
under linux, will generate the following output:
\begin{verbatim}
PPU-Mover Version 0.99.7
Copyright (c) 1998 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 timer code in the library.
\end{enumerate}
You could then use or distribute the files \file{libboth.so}, \file{timer.ppl}
and \file{ppu.ppl}.

\subsection{ptop - Pascal source beautifier}

\subsubsection{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 TurboPascal sourcebeautifiers 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] Writes an overview of the possible parameters and commandline 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] Sets the number of indent spaces used for BEGIN END; and other blocks.
\item[-b bufsize] Sets the streaming buffersize to bufsize. Default 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}] Writes a default configuration file to be edited to the file "ptop.cfg"
\end{description}

\subsubsection{The ptop configuration file}

Creating and distributing a configuration file for ptop is not necesarry,
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 buildingblock 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 out of one or two
lines, describing how \file{ptop} should react on a certain keyword.
First 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 like this:

[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. \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, \seet{ptopoptions}

\begin{FPCltable}{lll}{Possible options}{ptopoptions}
Option         &     does what \\ \hline
crsupp         &     suppress CR before the keyword.\\
crbefore       &     force CR before keyword\\
               &     (doesn't go 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" requires some extra parameters, which are
set by a second line for that option (the one with the square brackets), which is
therefore is only needed if the options contain "dinkdonkey" (contraction of
de-indent on assiociated keyword).

"dinkdonkey" deindents if any of the keywords specified by the extra options of the
square-bracket line is found.

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 made any errors.

\subsubsection{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 some program (e.g. an IDE) and use its features to format code.

The object resided 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 perfectly
suitable for editors.

\subsection{rstconv program}

The \file{rstconv} program converts the resource string files generates 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] Specifies 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.

\subsection{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.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% 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 specific. 

%
% Common units
%
\section{Standard units}

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

\begin{description}
\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[getopts] This unit gives you the \gnu \var{getopts} command-line
arguments  handling mechanism. It also supports long options.
\item[graph] This unit provides basic graphics handling, with routines to
draw lines on the screen, display texts etc. It provides the same functions
as the Turbo Pascal unit.
\item[keyboard] provides basic keyboard handling routines in a platform independent way,
and supports writing custom drivers.
\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[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, even
though the unit name may be different (e.g : syslinux, sysos2). It includes
among others, basic file I/O routines, memory management routines, all compiler 
helper routines, and directory services routines. 
\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 acces Run-Time Type Information, just
like Delphi.
\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 possibilities of the \var{GO32}
\dos extender.
\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 al 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 acces to the \windows sockets API Winsock.
\end{description}

%
% Under Linux
%
\section{Under Linux}
\begin{description}
\item[linux] 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. If you do a lot of disk/file
operations, the use of this unit is recommended over the one you use under
Dos.
\item[graph] Is an implementation of Borlands \file{graph} unit, which
works on the Linux console. Its implementation is as complete as on
the other platforms (it shares the same code).
It uses the libvga and libvgagl graphics libraries, so you need these
installed for this unit to work. Also, programs using this library need
to be run as root, or setuid root, and hence are a potential security risk.
\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 ruit or setuid
root, and are a serious security risk on your system.
\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 program manager functions.
\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.
\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.

This chapter describes shortly 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}
users' guide.

\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 generate debugging information in the executable from your
program. 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 generate 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}
GDB is free software and you are welcome to 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.
GDB 4.15.1 (i486-slackware-linux),
Copyright 1995 Free Software Foundation, Inc...
(gdb)
\end{verbatim}
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 so), \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\ ] Exits the debugger.
\item [kill\ ] Stops a running program.
\item [help\ ] Gives help on all \var{gdb} commands.
\item [file\ ] Loads 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\ ] Lists the program sources per 10 lines. As an option you can
specify a line number or function name.
\item [break\ ] Sets a breakpoint at a specified line or function
\item [awatch\ ] Sets 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}

for more information, see the \var{gdb} users' guide, or use the \var{'help'}
function in \var{gdb}.

The appendix {\ref{ch:GdbIniFile}} contains a sample init file for
\var{gdb}, which produces good results when debugging \fpc programs.

It is also possible to use \file{RHIDE}, a text-based IDE that uses gdb.
There is a version of RHIDE available that can work together with FPC.

\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 uppercare 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, of 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 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 contaning 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 could be stopped at with
\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 linenumber 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 wil insert the
necessary stuff for profiling.

When you have done this, you can run your program as you normally would 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 better redirect the output to a file, becuase
it could be quite a lot:
\begin{verbatim}
gprof yourexe > profile.log
\end{verbatim}

Hint: you can use the --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 which 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 you 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.

\begin{ver2}
Output can also be customized using environment variables.
\end{ver2}

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}
Which 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)

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% CGI.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{CGI programming in Free Pascal}
\label{ch:CGIProgramming}

In these days of heavy WWW traffic on the Internet, CGI scripts have become
an important topic in computer programming. While CGI programming can be
done with almost any tool you wish, most languages aren't designed for it.
Perl may be a notable exception, but perl is an interpreted language, the
executable is quite big, and hence puts a big load on the server machine.

Because of its simple, almost intuitive, string handling and its easy syntax,
Pascal is very well suited for CGI programming. Pascal allows you to quickly
produce some results, while giving you all the tools you need for more
complex programming. The basic RTL routines in principle are enough to get
the job done, but you can create, with relatively little effort, some units
which can be used as a base for more complex CGI programming.

That's why, in this chapter, we will discuss the basics of CGI in \fpc.
In the subsequent, we will assume that the server for which the programs are
created, are based upon the NCSA \var{httpd} WWW server, as the examples
will be based upon the NCSA method of CGI programming\footnote{... and its
the only WWW-server I have to my disposition at the moment.}.
They have been tested with the \file{apache} server on \linux, and
the \file{xitami} server on \windowsnt.

The two example programs in this chapter have been tested on the command line
and worked, under the condition that no spaces were present in the name and
value pairs provided to them.

There is however, a faster and generally better \file{uncgi} unit available,
you can find it on the contributed units page of the \fpc web site. It uses
techniques discussed here, but in a generally more efficient way, and it
also provides some extra functionality, not discussed here.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Getting your data
\section{Getting your data}
Your CGI program must react on data the user has filled in on the form which
your web-server gave him. The Web server takes the response on the form, and
feeds it to the CGI script.

There are essentially two ways of feeding the data to the CGI script. We will
discuss both.

%
%

% Data coming through standard input.
\subsection{Data coming through standard input.}
The first method of getting your data is through standard input. This method
is invoked when the form uses a form submission method of \var{POST}.
The web browser sets three environment variables \var{REQUEST\_METHOD},
\var{CONTENT\_TYPE} and \var{CONTENT\_LENGTH}. It feeds then the results of
the different fields through standard input to the CGI script.
All the Pascal program has to do is :
\begin{itemize}
\item Check the value of the \var{REQUEST\_METHOD} environment variable. The
\var{getenv} function will retrieve this value this for you.
\item Check the value of the \var{CONTENT\_TYPE} environment variable.
\item Read \var{CONTENT\_LENGTH} characters from standard input. \var{read
(c)} with \var{c} of type \var{char} will take care of that.
\end{itemize}
if you know that the request method will always be \var{POST}, and the
\var{CONTENT\_TYPE} will be correct, then you can skip the first two steps.
The third step can be done easier: read characters until you reach the
end-of-file marker of standard input.

The following example shows how this can be achieved:
\begin{verbatim}
program cgi_post;

uses dos;

const max_data = 1000;

type datarec = record
  name,value : string;
  end;

var data : array[1..max_data] of datarec;
    i,nrdata : longint;
    c  : char;
    literal,aname : boolean;

begin
writeln ('Content-type: text/html');
writeln;
if getenv('REQUEST_METHOD')<>'POST' then
   begin
   writeln ('This script should be referenced with a METHOD of POST');
   write ('If you don''t understand this, see this ');
   write ('< A HREF="http://www.ncsa.uiuc.edu/SDG/Softare/Mosaic');
   writeln ('/Docs/fill-out-forms/overview.html">forms overview</A>.');
   halt(1);
   end;
if getenv('CONTENT_TYPE')<>'application/x-www-form-urlencoded' then
   begin
   writeln ('This script can only be used to decode form results');
   halt(1)
   end;
nrdata:=1;
aname:=true;
while not eof(input) do
  begin
  literal:=false;
  read(c);
  if c='\' then
     begin
     literal:=true;
     read(c);
     end;
  if literal or ((c<>'=') and (c<>'&')) then
     with data[nrdata] do
        if aname then name:=name+c else value:=value+c
  else
     begin
     if c='&' then
         begin
         inc (nrdata);
         aname:=true;
         end
      else
         aname:=false;
      end
  end;
writeln ('<H1>Form Results :</H1>');
writeln ('You submitted the following name/value pairs :');
writeln ('<UL>');
for i:=1 to nrdata do writeln ('<LI> ',data[i].name,' = ',data[i].value);
writeln ('</UL>');
end.
\end{verbatim}
While this program isn't shorter than the C program provided as an example
at NCSA, it doesn't need any other units. everythig is done using standard
Pascal procedures\footnote{actually, this program will give faulty results,
since spaces in the input are converted to plus signs by the web browser.
The program doesn't check for this, but that is easy to change.
The main concern here is to give the working principle.}.

Note that this program has a limitation: the length of names and values is
limited to 255 characters. This is due to the fact that strings in Pascal
have a maximal length of 255. It is of course easy to redefine the
\var{datarec} record in such a way that longer values are allowed.
In case you have to read the contents of a \var{TEXTAREA} form element,
this may be needed.


% Data passed through an environment variable
\subsection{Data passed through an environment variable}
If your form uses the \var{GET} method of passing its data, the CGI script
needs to read the \var{QUERY\_STRING} environment variable to get its data.
Since this variable can, and probably will, be more than 255 characters long,
you will not be able to use normal string methods, present in pascal. \fpc
implements the \var{pchar} type, which is a pointer to a null-terminated
array of characters.
And, fortunately, \fpc has a
\seestrings\  unit, which eases the use of the
\var{pchar} type.


The following example illustrates what to do in case of a method of \var{GET}
\begin{verbatim}
program cgi_get;

uses strings,linux;

const max_data = 1000;

type datarec = record
  name,value : string;
  end;

var data : array[1..max_data] of datarec;
    i,nrdata : longint;
    p  : PChar;
    literal,aname : boolean;

begin
Writeln ('Content-type: text/html');
Writeln;
if StrComp(GetEnv('REQUEST_METHOD'),'POST')<>0 then
   begin
   Writeln ('This script should be referenced with a METHOD of GET');
   write ('If you don''t understand this, see this ');
   write ('< A HREF="http://www.ncsa.uiuc.edu/SDG/Softare/Mosaic');
   Writeln ('/Docs/fill-out-forms/overview.html">forms overview</A>.');
   halt(1);
   end;
p:=GetEnv('QUERY_STRING');
nrdata:=1;
aname:=true;
while p^<>#0  do
  begin
  literal:=false;
  if p^='\' then
     begin
     literal:=true;
     inc(longint(p));
     end;
  if ((p^<>'=') and (p^<>'&')) or literal then
     with data[nrdata] do
        if aname then name:=name+p^ else value:=value+p^
  else
     begin
     if p^='&' then
         begin
         inc (nrdata);
         aname:=true;
         end
      else
         aname:=false;
      end;
  inc(longint(p));
  end;
Writeln ('<H1>Form Results :</H1>');
Writeln ('You submitted the following name/value pairs :');
Writeln ('<UL>');
for i:=1 to nrdata do writeln ('<LI> ',data[i].name,' = ',data[i].value);
Writeln ('</UL>');
end.
\end{verbatim}
Although it may not be written in the most elegant way, this program does
the same thing as the previous one. It also suffers from the same drawback,
namely the limited length of the \var{value} field of the \var{datarec}.

This drawback can be remedied by redefining \var{datarec} as follows:
\begin{verbatim}
type datarec = record;
      name,value : pchar;
     end;
\end{verbatim}
and assigning at run time enough space to keep the contents of the value
field. This can be done with a
\begin{verbatim}
 getmem (data[nrdata].value,needed_number_of_bytes);
\end{verbatim}
call. After that you can do a
\begin{verbatim}
strlcopy (data[nrdata].value,p,needed_number_of_bytes);
\end{verbatim}
to copy the data into place.

You may have noticed the following unorthodox call :
\begin{verbatim}
inc(longint(p));
\end{verbatim}
\fpc doesn't give you pointer arithmetic as in C. However, \var{longints} and
\var{pointers} have the same length (namely 4 bytes). Doing a type-cast to a
\var{longint} allows you to do arithmetic on the \var{pointer}.

Note however, that this is a non-portable call. This may work on the I386
processor, but not on a ALPHA processor (where a pointer is 8 bytes long).
This will be remedied in future releases of \fpc.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Producing output
\section{Producing output}
The previous section concentrated mostly on getting input from the web
server. To send the reply to the server, you don't need to do anything
special.You just print your data on standard output, and the Web-server will
intercept this, and send your output to the WWW-client waiting for it.

You can print anything you want, the only thing you must take care of is
that you supply a \var{Contents-type} line, followed by an empty line, as
follows:
\begin{verbatim}
Writeln ('Content-type: text/html');
Writeln;
{ ...start output of the form... }

\end{verbatim}

And that's all there is to it !


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% I'm under Windows, what now ?
\section{I'm under Windows, what now ?}
Under Windows the system of writing CGI scripts can be totally different.
If you use \fpc under Windows then you also should be able to do CGI
programming, but the above instructions may not work. They are known to work
for the \file{xitami} server, however.

If some kind soul is willing to write a section on CGI programming under
Windows for other servers, I'd be willing to include it here.
\appendix


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% APPENDIX A.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{Alphabetical listing of command-line options}
The following is alphabetical listing of all command-line options, as
generated by the compiler:
\begin{verbatim}
Free Pascal Compiler version 1.0.5 [2001/10/29] for i386
Copyright (c) 1993-2000 by Florian Klaempfl
/usr/local/lib/fpc/1.0.5/fpc [options] <inputfile> [options]
put + after a boolean switch option to enable it, - to disable it
  -a     the compiler doesn't delete the generated assembler file
      -al        list sourcecode lines in assembler file
      -ar        list register allocation/release info in assembler file
      -at        list temp allocation/release info in assembler file
  -b     generate browser info
      -bl        generate local symbol info
  -B     build all modules
  -C<x>  code generation options:
      -CD        create also dynamic library (not supported)
      -Ch<n>     <n> bytes heap (between 1023 and 67107840)
      -Ci        IO-checking
      -Cn        omit linking stage
      -Co        check overflow of integer operations
      -Cr        range checking
      -Cs<n>     set stack size to <n>
      -Ct        stack checking
      -CX        create also smartlinked library
  -d<x>  defines the symbol <x>
  -e<x>  set path to executable
  -E     same as -Cn
  -F<x>  set file names and paths:
      -FD<x>     sets the directory where to search for compiler utilities
      -Fe<x>     redirect error output to <x>
      -FE<x>     set exe/unit output path to <x>
      -Fi<x>     adds <x> to include path
      -Fl<x>     adds <x> to library path
      -FL<x>     uses <x> as dynamic linker
      -Fo<x>     adds <x> to object path
      -Fr<x>     load error message file <x>
      -Fu<x>     adds <x> to unit path
      -FU<x>     set unit output path to <x>, overrides -FE
  -g     generate debugger information:
      -gg        use gsym
      -gd        use dbx
      -gh        use heap trace unit (for memory leak debugging)
      -gl        use line info unit to show more info for backtraces
      -gc        generate checks for pointers
  -i     information
      -iD        return compiler date
      -iV        return compiler version
      -iSO       return compiler OS
      -iSP       return compiler processor
      -iTO       return target OS
      -iTP       return target processor
  -I<x>  adds <x> to include path
  -k<x>  Pass <x> to the linker
  -l     write logo
  -n     don't read the default config file
  -o<x>  change the name of the executable produced to <x>
  -pg    generate profile code for gprof (defines FPC_PROFILE)
  -P     use pipes instead of creating temporary assembler files
  -S<x>  syntax options:
      -S2        switch some Delphi 2 extensions on
      -Sc        supports operators like C (*=,+=,/= and -=)
      -sa        include assertion code.
      -Sd        tries to be Delphi compatible
      -Se<x>     compiler stops after the <x> errors (default is 1)
      -Sg        allow LABEL and GOTO
      -Sh        Use ansistrings
      -Si        support C++ styled INLINE
      -Sm        support macros like C (global)
      -So        tries to be TP/BP 7.0 compatible
      -Sp        tries to be gpc compatible
      -Ss        constructor name must be init (destructor must be done)
      -St        allow static keyword in objects
  -s     don't call assembler and linker (only with -a)
  -u<x>  undefines the symbol <x>
  -U     unit options:
      -Un        don't check the unit name
      -Ur        generate release unit files
      -Us        compile a system unit
  -v<x>  Be verbose. <x> is a combination of the following letters:
      e : Show errors (default)       d : Show debug info
      w : Show warnings               u : Show unit info
      n : Show notes                  t : Show tried/used files
      h : Show hints                  m : Show defined macros
      i : Show general info           p : Show compiled procedures
      l : Show linenumbers            c : Show conditionals
      a : Show everything             0 : Show nothing (except errors)
      b : Show all procedure          r : Rhide/GCC compatibility mode
          declarations if an error    x : Executable info (Win32 only)
          occurs
  -X     executable options:
      -Xc        link with the c library
      -Xs        strip all symbols from executable
      -XD        try to link dynamic          (defines FPC_LINK_DYNAMIC)
      -XS        try to link static (default) (defines FPC_LINK_STATIC)
      -XX        try to link smart            (defines FPC_LINK_SMART)

Processor specific options:
  -A<x>  output format:
      -Aas       assemble using GNU AS
      -Aasaout   assemble using GNU AS for aout (Go32v1)
      -Anasmcoff coff (Go32v2) file using Nasm
      -Anasmelf  elf32 (Linux) file using Nasm
      -Anasmobj  obj file using Nasm
      -Amasm     obj file using Masm (Microsoft)
      -Atasm     obj file using Tasm (Borland)
      -Acoff     coff (Go32v2) using internal writer
      -Apecoff   pecoff (Win32) using internal writer
  -R<x>  assembler reading style:
      -Ratt      read AT&T style assembler
      -Rintel    read Intel style assembler
      -Rdirect   copy assembler text directly to assembler file
  -O<x>  optimizations:
      -Og        generate smaller code
      -OG        generate faster code (default)
      -Or        keep certain variables in registers
      -Ou        enable uncertain optimizations (see docs)
      -O1        level 1 optimizations (quick optimizations)
      -O2        level 2 optimizations (-O1 + slower optimizations)
      -O3        level 3 optimizations (same as -O2u)
      -Op<x>     target processor:
         -Op1  set target processor to 386/486
         -Op2  set target processor to Pentium/PentiumMMX (tm)
         -Op3  set target processor to PPro/PII/c6x86/K6 (tm)
  -T<x>  Target operating system:
      -TGO32V1   version 1 of DJ Delorie DOS extender
      -TGO32V2   version 2 of DJ Delorie DOS extender
      -TLINUX    Linux
      -TOS2      OS/2 2.x
      -TSUNOS    SunOS/Solaris
      -TWin32    Windows 32 Bit
      -TBeOS     BeOS
  -W<x>  Win32 target options
      -WB<x>     Set Image base to Hexadecimal <x> value
      -WC        Specify console type application
      -WD        Use DEFFILE to export functions of DLL or EXE
      -WF        Specify full-screen type application (OS/2 only)
      -WG        Specify graphic type application
      -WN        Do not generate relocation code (necessary for debugging)
      -WR        Generate relocation code
  
  -?     shows this help
  -h     shows this help without waiting
\end{verbatim}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% 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 faitly
complete. At this point, only assembler errors are not in the list.

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

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% 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 expressions
does a division by zero.

\item [Evaluator stack overflow, Evaluator stack underflow]
These fatal errors are reported when a constant assembler expression
is too big to evaluate 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 a '@' 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 are declared in
a base other then 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 symolb 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 an invalid constant expression,
or that the 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 then 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 support 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 error 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 currently opened files 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 accessing the file is denied. This error might
be caused by 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 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, when 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 exlicitly 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]
This you will get 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 too large real numbers.
\item [206  Floating point underflow]
You are trying to use or produce too small real numbers.
\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 istr 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 Deferencing 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 excpetions 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 [227 Assertion failed error]
An assertion failed, and no \var{AssertErrorProc} procedural variable was 
installed.
\end{description}

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

\chapter{The Floating Point Coprocessor emulator}

In this appendix we note some caveats when using the floating point
emulator on GO32V2 systems. Under GO32V1 systems, all is as described in
the installation section.

{\em Q: I don't have an 80387. How do I compile and run floating point
   programs under GO32V2?

     Q: What shall I install on a target machine which lacks hardware
   floating-point support?
}

{\em A :}
 Programs which use floating point computations and could be run on
   machines without an 80387 should be allowed to dynamically load the
\file{emu387.dxe}
   file at run-time if needed. To do this you must link the \var{emu387} unit to your
   exectuable program, for example:

\begin{verbatim}
      Program MyFloat;

      Uses emu387;

      var
       r: real;
      Begin
       r:=1.0;
       WriteLn(r);
      end.
\end{verbatim}

   \var{Emu387} takes care of loading the dynamic emulation point library.

   You should always add emulation when you distribute floating-point
   programs.

   A few users reported that the emulation won't work for them unless
   they explicitly tell \var{DJGPP} there is no \var{x87} hardware, like this:

\begin{verbatim}
       set 387=N
       set emu387=c:/djgpp/bin/emu387.dxe
\end{verbatim}

   There is an alternative FP emulator called WMEMU. It mimics a real
   coprocessor more closely.

   {\em WARNING:} We strongly suggest that you use WMEMU as FPU emulator, since
   \file{emu387.dxe} does not emulate all the instructions which are used by the
   Run-Time Libary such as \var{FWAIT}.


{\em   Q: I have an 80387 emulator installed in my AUTOEXEC.BAT, but
   DJGPP-compiled floating point programs still doesn't work. Why?
}


{\em   A :} DJGPP switches the CPU to protected mode, and the information
   needed to emulate the 80387 is different. Not to mention that the
   exceptions never get to the real-mode handler. You must use emulators
   which are designed for DJGPP. Apart of emu387 and WMEMU, the only
   other emulator known to work with DJGPP is Q87 from QuickWare. Q87 is
   shareware and is available from the QuickWare Web site.


{\em   Q: I run DJGPP in an \ostwo DOS box, and I'm told that \ostwo will install
   its own emulator library if the CPU has no FPU, and will transparently
   execute FPU instructions. So why won't DJGPP run floating-point code
   under \ostwo on my machine?
}

{\em   A} : \ostwo installs an emulator for native \ostwo images, but does not
   provide FPU emulation for DOS sessions.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%  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}

\end{document}