% % $Id: user.tex,v 1.32 2005/05/07 13:12:36 michael Exp $ % This file is part of the FPC documentation. % Copyright (C) 1997, by Michael Van Canneyt % % The FPC documentation is free text; you can redistribute it and/or % modify it under the terms of the GNU Library General Public License as % published by the Free Software Foundation; either version 2 of the % License, or (at your option) any later version. % % The FPC Documentation is distributed in the hope that it will be useful, % but WITHOUT ANY WARRANTY; without even the implied warranty of % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU % Library General Public License for more details. % % You should have received a copy of the GNU Library General Public % License along with the FPC documentation; see the file COPYING.LIB. If not, % write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, % Boston, MA 02111-1307, USA. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Preamble. \input{preamble.inc} \begin{latexonly} \ifpdf \hypersetup{ pdfauthor={Michael Van Canneyt}, pdftitle={User's Guide}, pdfsubject={Free Pascal User's Guide}, pdfkeywords={Free Pascal} } \fi \end{latexonly} % % Settings % \makeindex % % Start of document. % \begin{document} \title{Free Pascal :\\ User's Guide} \docdescription{User's Guide for \fpc, Version \fpcversion} \docversion{2.6} \input{date.inc} \author{Micha\"el Van Canneyt\\Florian Kl\"ampfl} \maketitle \tableofcontents %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Introduction %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Introduction} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % About this document \section{About this document} This is the user's guide for \fpc . It describes the installation and use of the \fpc compiler on the different supported platforms. It does not attempt to give an exhaustive list of all supported commands, nor a definition of the Pascal language. Look at the \refref for these things. For a description of the possibilities and the inner workings of the compiler, see the \progref . In the appendices of this document you will find lists of reserved words and compiler error messages (with descriptions). This document describes the compiler as it is/functions at the time of writing. First consult the \file{README} and \file{FAQ} files, distributed with the compiler. The \file{README} and \file{FAQ} files are, in case of conflict with this manual, authoritative. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % About the compiler \section{About the compiler} \fpc is a 32- and 64-bit Pascal compiler. The current version (2.6) can compile code for the following processors: \begin{itemize} \item Intel i386 and higher (i486, Pentium family and higher) \item AMD64/x86\_64 \item PowerPC \item PowerPC64 \item SPARC \item ARM \item The m68K processor is supported by an older version. \end{itemize} The compiler and Run-Time Library are available for the following operating systems: \begin{itemize} \item \dos \item \linux % (Intel, AMD64, Arm, SPARC, PPC and m68k) \item \amiga (version 0.99.5 only) \item \windows \item Mac OS X \item \ostwo (optionally using the EMX package, so it also works on DOS/Windows) \item \freebsd \item \beos \item \solaris \item \netbsd \item \netware \item \openbsd \item MorphOS \item Symbian \end{itemize} The complete list is at all times available on the Free Pascal website. \fpc is designed to be, as much as possible, source compatible with Turbo Pascal 7.0 and Delphi 7 (although this goal is not yet attained), but it also enhances these languages with elements like operator overloading. And, unlike these ancestors, it supports multiple platforms. It also differs from them in the sense that you cannot use compiled units from one system for the other, i.e. you cannot use TP compiled units. Also, there is a text version of an Integrated Development Environment (IDE) available for \fpc. Users that prefer a graphical IDE can have a look at the Lazarus or MSIDE projects. \fpc consists of several parts : \begin{enumerate} \item The compiler program itself. \item The Run-Time Library (RTL). \item The packages. This is a collection of many utility units, ranging from the whole Windows 32 API, through native ZIP/BZIP file handling to the whole GTK-2 interface. \item The Free Component Library. This is a set of class-based utility units which give a database framework, image support, web support, XML support and many many more. \item Utility programs and units. \end{enumerate} Of these you only need the first two, in order to be able to use the compiler. In this document, we describe the use of the compiler and utilities. The Pascal Language is described in the \refref, and the available routines (units) are described in the RTL and FCL Unit reference guides. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Getting more information. \section{Getting more information.} If the documentation doesn't give an answer to your questions, you can obtain more information on the Internet, at the following addresses: \begin{itemize} \item \seeurl{http://www.freepascal.org/} {http://www.freepascal.org} is the main site. It contains also useful mail addresses and links to other places. It also contains the instructions for subscribing to the \textit{mailinglist}. \item \seeurl{http://forum.lazarus.freepascal.org/} {http://forum.lazarus.freepascal.org/} is a forum site where questions can be posted. \end{itemize} Other than that, some mirrors exist. Finally, if you think something should be added to this manual (entirely possible), please do not hesitate and contact me at \seeurl{michael@freepascal.org}{mailto:michael@freepascal.org}. . Let's get on with something useful. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Installation %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Installing the compiler} \label{ch:Installation} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Before Installation : Requirements \section{Before Installation : Requirements} % % System requirements % \subsection{Hardware requirements} The compiler needs at least one of the following processors: \begin{enumerate} \item An Intel 80386 or higher processor. A coprocessor is not required, although it will slow down your program's performance if you do floating point calculations without a coprocessor, since emulation will be used. \item An AMD64 or EMT64 processor. \item A PowerPC processor. \item A SPARC processor \item An ARM processor. \item Older FPC versions exist for the motorola 68000 processor, but these are no longer maintained. \end{enumerate} Memory and disk requirements: \begin{enumerate} \item 8 Megabytes of free memory. This is sufficient to allow compilation of small programs. \item Large programs (such as the compiler itself) will require at least 64 MB. of memory, but 128MB is recommended. (Note that the compiled programs themselves do not need so much memory.) \item At least 80 MB free disk space. When the sources are installed, another 270 MB are needed. \end{enumerate} % Software requirements \subsection{Software requirements} \subsubsection{Under DOS} The \dos distribution contains all the files you need to run the compiler and compile Pascal programs. \subsubsection{Under UNIX} Under \unix systems (such as \linux) you need to have the following programs installed : \begin{enumerate} \item \gnu \file{as}, the \gnu assembler. \item \gnu \file{ld}, the \gnu linker. \item Optionally (but highly recommended) : \gnu \file{make}. For easy recompiling of the compiler and Run-Time Library, this is needed. \end{enumerate} \subsubsection{Under Windows} The \windows distributions (both 32 and 64 bit) contain all the files you need to run the compiler and compile Pascal programs. However, it may be a good idea to install the \file{mingw32} tools or the \var{cygwin} development tools. Links to both of these tools can be found on \var{http://www.freePascal.org} \subsubsection{Under OS/2} While the \fpc distribution comes with all necessary tools, it is a good idea to install the EMX extender in order to compile and run programs with the Free Pascal compiler. The EMX extender can be found on:\\ \var{ftp://hobbes.nmsu.edu/pub/os2/dev/emx/v0.9d} \subsubsection{Under Mac OS X} Mac OS X 10.1 or higher is required, and the developer tools or XCode should be installed. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Installing the compiler. \section{Installing the compiler.} The installation of \fpc is easy, but is platform-dependent. We discuss the process for each platform separately. % Installing under DOS \subsection{Installing under Windows} For \windows, there is a \windows installer, \file{setup.exe}. This is a normal installation program, which offers the usual options of selecting a directory, and which parts of the distribution you want to install. It will, optionally, associate the \file{.pp} or \var{.pas} extensions with the text mode IDE. It is not recommended to install the compiler in a directory which has spaces in it's path name. Some of the external tools do not support filenames with spaces in them, and you will have problems creating programs. \subsection{Installing under DOS or OS/2} \subsubsection{Mandatory installation steps.} First, you must get the latest distribution files of \fpc. They come as zip files, which you must unzip first, or you can download the compiler as a series of separate files. This is especially useful if you have a slow connection, but it is also nice if you want to install only some parts of the compiler distribution. The distribution zip files for DOS or OS/2 contain an installation program \file{INSTALL.EXE}. You must run this program to install the compiler. The screen of the DOS or OS/2 installation program looks like figure \ref{fig:install1}. \FPCpic{The \dos install program screen}{}{install1} \FPCpic{}{}{install2} The program allows you to select: \begin{itemize} \item What components you wish to install. e.g do you want the sources or not, do you want docs or not. Items that you didn't download when downloading as separate files, will not be enabled, i.e. you can't select them. \item Where you want to install (the default location is \verb|C:\PP|). \end{itemize} In order to run \fpc from any directory on your system, you must extend your path variable to contain the \verb|C:\PP\BIN| directory. Usually this is done in the \file{AUTOEXEC.BAT} file. It should look something like this : \begin{verbatim} SET PATH=%PATH%;C:\PP\2.6\BIN\i386-DOS \end{verbatim} for \dos or \begin{verbatim} SET PATH=%PATH%;C:\PP\2.6\BIN\i386-OS2 \end{verbatim} for \ostwo. (Again, assuming that you installed in the default location). On \ostwo, \fpc installs some libraries from the EMX package if they were not yet installed. (The installer will notify you if they should be installed). They are located in the \begin{verbatim} C:\PP\DLL \end{verbatim} directory. The name of this directory should be added to the \var{LIBPATH} directive in the \file{config.sys} file: \begin{verbatim} LIBPATH=XXX;C:\PP\DLL \end{verbatim} Obviously, any existing directories in the \var{LIBPATH} directive (indicated by \var{XXX} in the above example) should be preserved. \subsubsection{Optional Installation: The coprocessor emulation} For people who have an older CPU type, without math coprocessor (i387) it is necessary to install a coprocessor emulation, since \fpc uses the coprocessor to do all floating point operations. The installation of the coprocessor emulation is handled by the installation program (\file{INSTALL.EXE}) under \dos and \windows. % % Installing under Linux % \subsection{Installing under Linux} \subsubsection{Mandatory installation steps.} The \linux distribution of \fpc comes in three forms: \begin{itemize} \item a \file{tar.gz} version, also available as separate files. \item a \file{.rpm} (Red Hat Package Manager) version, and \item a \file{.deb} (Debian) version. \end{itemize} If you use the \file{.rpm} format, installation is limited to \begin{verbatim} rpm -i fpc-X.Y.Z-N.ARCH.rpm \end{verbatim} Where \var{X.Y.Z} is the version number of the \file{.rpm} file, and \var{ARCH} is one of the supported architectures (i386, x86\_64 etc.). If you use Debian, installation is limited to \begin{verbatim} dpkg -i fpc-XXX.deb \end{verbatim} Here again, \var{XXX} is the version number of the \file{.deb} file. You need root access to install these packages. The \file{.tar} file allows you to do an installation below your home directory if you don't have root permissions. When downloading the \var{.tar} file, or the separate files, installation is more interactive. In case you downloaded the \file{.tar} file, you should first untar the file, in some directory where you have write permission, using the following command: \begin{verbatim} tar -xvf fpc.tar \end{verbatim} We supposed here that you downloaded the file \file{fpc.tar} somewhere from the Internet. (The real filename will have some version number in it, which we omit here for clarity.) When the file is untarred, you will be left with more archive files, and an install program: an installation shell script. If you downloaded the files as separate files, you should at least download the \file{install.sh} script, and the libraries (in \file{libs.tar.gz}). To install \fpc, all that you need to do now is give the following command: \begin{verbatim} ./install.sh \end{verbatim} And then you must answer some questions. They're very simple, they're mainly concerned with 2 things : \begin{enumerate} \item Places where you can install different things. \item Deciding if you want to install certain components (such as sources and demo programs). \end{enumerate} The script will automatically detect which components are present and can be installed. It will only offer to install what has been found. Because of this feature, you must keep the original names when downloading, since the script expects this. If you run the installation script as the \var{root} user, you can just accept all installation defaults. If you don't run as \var{root}, you must take care to supply the installation program with directory names where you have write permission, as it will attempt to create the directories you specify. In principle, you can install it wherever you want, though. At the end of installation, the installation program will generate a configuration file (\file{fpc.cfg}) for the \fpc compiler which reflects the settings that you chose. It will install this file in the \file{/etc} directory or in your home directory (with name \file{.fpc.cfg}) if you do not have write permission in the \file{/etc} directory. It will make a copy in the directory where you installed the libraries. The compiler will first look for a file \file{.fpc.cfg} in your home directory before looking in the \file{/etc} directory. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Optional configuration %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Optional configuration steps} On any platform, after installing the compiler you may wish to set some environment variables. The \fpc compiler recognizes the following variables : \begin{itemize} \item \verb|PPC_EXEC_PATH| contains the directory where support files for the compiler can be found. \item \verb|PPC_CONFIG_PATH| specifies an alternate path to find the \file{fpc.cfg}. \item \verb|PPC_ERROR_FILE| specifies the path and name of the error-definition file. \item \verb|FPCDIR| specifies the root directory of the \fpc installation. (e.g : \verb|C:\PP\BIN|) \end{itemize} These locations are, however, set in the sample configuration file which is built at the end of the installation process, except for the \verb|PPC_CONFIG_PATH| variable, which you must set if you didn't install things in the default places. \section{Before compiling} Also distributed in \fpc is a README file. It contains the latest instructions for installing \fpc, and should always be read first. Furthermore, platform-specific information and common questions are addressed in the \var{FAQ}. It should be read before reporting any bug. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Testing the compiler \section{Testing the compiler} After the installation is completed and the optional environment variables are set as described above, your first program can be compiled. Included in the \fpc distribution are some demonstration programs, showing what the compiler can do. You can test if the compiler functions correctly by trying to compile these programs. The compiler is called \begin{itemize} \item \file{fpc.exe} under \windows, \ostwo and \dos. \item \file{fpc} under most other operating systems. \end{itemize} To compile a program (e.g \verb|demo\text\hello.pp|), copy the program to your current working directory, and simply type : \begin{verbatim} fpc hello \end{verbatim} at the command prompt. If you don't have a configuration file, then you may need to tell the compiler where it can find the units, for instance as follows: \begin{verbatim} fpc -Fuc:\pp\NNN\units\i386-go32v2\rtl hello \end{verbatim} under \dos, and under \linux you could type \begin{verbatim} fpc -Fu/usr/lib/fpc/NNN/units/i386-linux/rtl hello \end{verbatim} (replace \var{NNN} with the version number of \fpc that you are using). This is, of course, assuming that you installed under \verb|C:\PP| or \file{/usr/lib/fpc/NNN}, respectively. If you got no error messages, the compiler has generated an executable called \file{hello.exe} under \dos, \ostwo or \windows, or \file{hello} (no extension) under \unix and most other operating systems. To execute the program, simply type : \begin{verbatim} hello \end{verbatim} or \begin{verbatim} ./hello \end{verbatim} on Unices (where the current directory usually is not in the PATH). If all went well, you should see the following friendly greeting: \begin{verbatim} Hello world \end{verbatim} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Usage %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Compiler usage} \label{ch:Usage} Here we describe the essentials to compile a program and a unit. For more advanced uses of the compiler, see the section on configuring the compiler, and the \progref{}. The examples in this section suppose that you have an \file{fpc.cfg} which is set up correctly, and which contains at least the path setting for the RTL units. In principle this file is generated by the installation program. You may have to check that it is in the correct place. (see section \ref{se:configfile} for more information on this.) %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Where the compiler looks for its files. \section{File searching} Before you start compiling a program or a series of units, it is important to know where the compiler looks for its source files and other files. In this section we discuss this, and we indicate how to influence this. \begin{remark} The use of slashes (/) and backslashes (\verb+\+) as directory separators is irrelevant, the compiler will convert to whatever character is used on the current operating system. Examples will be given using slashes, since this avoids problems on \unix systems (such as \linux). \end{remark} % Command line files. \subsection{Command line files} The file that you specify on the command line, such as in \begin{verbatim} fpc foo.pp \end{verbatim} will be looked for ONLY in the current directory. If you specify a directory in the filename, then the compiler will look in that directory: \begin{verbatim} fpc subdir/foo.pp \end{verbatim} will look for \file{foo.pp} in the subdirectory \file{subdir} of the current directory. Under case sensitive file systems (such as \linux and \unix), the name of this file is case sensitive; under other operating systems (such as \dos, \windowsnt, \ostwo) this is not the case. % Unit files. \subsection{Unit files} \label{se:unitsearching} When you compile a unit or program that needs other units, the compiler will look for compiled versions of these units in the following way: \begin{enumerate} \item It will look in the current directory. \item It will look in the directory where the source file resides. \item It will look in the directory where the compiler binary is. \item It will look in all the directories specified in the unit search path. \end{enumerate} You can add a directory to the unit search path with the (\seeo{Fu}) option. Every occurrence of one of these options will {\em insert} a directory to the unit search path. i.e. the last path on the command line will be searched first. The compiler adds several paths to the unit search path: \begin{enumerate} \item The contents of the environment variable \var{XXUNITS}, where \var{XX} must be replaced with one of the supported targets: \var{GO32V2}, \var{LINUX},\var{WIN32}, \var{OS2}, \var{BEOS}, \var{FREEBSD}, \var{SUNOS}, \var{DARWIN} (the actual list depends on the available targets). \item The standard unit directory. This directory is determined from the \var{FPCDIR} environment variable. If this variable is not set, then it is defaulted to the following: \begin{itemize} \item On \linux: \begin{verbatim} /usr/local/lib/fpc/FPCVERSION or /usr/lib/fpc/FPCVERSION \end{verbatim} whichever is found first. \item On other OSes: the compiler binary directory, with '../' appended to it, if it exists. For instance, on Windows, this would mean \begin{verbatim} C:\FPC\2.6\units\i386-win32 \end{verbatim} This is assuming the compiler was installed in the directory \begin{verbatim} C:\FPC\2.6 \end{verbatim} \end{itemize} After this directory is determined , the following paths are added to the search path: \begin{enumerate} \item FPCDIR/units/FPCTARGET \item FPCDIR/units/FPCTARGET/rtl \end{enumerate} Here target must be replaced by the name of the target you are compiling for: this is a combination of CPU and OS, so for instance \begin{verbatim} /usr/local/lib/fpc/2.6/units/i386-linux/ \end{verbatim} or, when cross-compiling \begin{verbatim} /usr/local/lib/fpc/2.6/units/i386-win32/ \end{verbatim} \end{enumerate} The \var{-Fu} option accepts a single \var{*} wildcard, which will be replaced by all directories found on that location, but {\em not} the location itself. For example, given the directories \begin{verbatim} rtl/units/i386-linux fcl/units/i386-linux packages/base packages/extra \end{verbatim} the command \begin{verbatim} fpc -Fu"*/units/i386-linux" \end{verbatim} will have the same effect as \begin{verbatim} fpc -Furtl/units/i386-linux -Fufcl/units/i386-linux \end{verbatim} since both the \file{rtl} and \file{fcl} directories contain further \file{units/i386-linux} subdirectories. The packages directory will not be added, since it doesn't contain a \file{units/i386-linux} subdirectory. The following command \begin{verbatim} fpc -Fu"units/i386-linux/*" \end{verbatim} will match any directory below the \file{units/i386-linux} directory, but will not match the \file{units/i386-linux} directory itself, so you should add it manually if you want the compiler to look for files in this directory as well: \begin{verbatim} fpc -Fu"units/i386-linux" -Fu"units/i386-linux/*" \end{verbatim} Note that (for optimization) the compiler will drop any non-existing paths from the search path, i.e. the existence of the path (after wildcard and environment variable expansion) will be tested. You can see what paths the compiler will search by giving the compiler the \var{-vu} option. On systems where filenames are case sensitive (such as \unix and \linux), the compiler will : \begin{enumerate} \item Search for the original file name, i.e. preserves case. \item Search for the filename all lowercased. \item Search for the filename all uppercased. \end{enumerate} This is necessary, since Pascal is case-independent, and the statements \var{Uses Unit1;} or \var{uses unit1;} should have the same effect. It will do this first with the extension \file{.ppu} (the compiled unit), \file{.pp} and then with the extension \file{.pas}. For instance, suppose that the file \file{foo.pp} needs the unit \file{bar}. Then the command \begin{verbatim} fpc -Fu.. -Fuunits foo.pp \end{verbatim} will tell the compiler to look for the unit \file{bar} in the following places: \begin{enumerate} \item In the current directory. \item In the directory where the compiler binary is (not under \linux). \item In the parent directory of the current directory. \item In the subdirectory \file{units} of the current directory \item In the standard unit directory. \end{enumerate} Also, unit names that are longer than 8 characters will first be looked for with their full length. If the unit is not found with this name, the name will be truncated to 8 characters, and the compiler will look again in the same directories, but with the truncated name. If the compiler finds the unit it needs, it will look for the source file of this unit in the same directory where it found the unit. If it finds the source of the unit, then it will compare the file times. If the source file was modified more recent than the unit file, the compiler will attempt to recompile the unit with this source file. If the compiler doesn't find a compiled version of the unit, or when the \var{-B} option is specified, then the compiler will look in the same manner for the unit source file, and attempt to recompile it. It is recommended to set the unit search path in the configuration file \file{fpc.cfg}. If you do this, you don't need to specify the unit search path on the command line every time you want to compile something. % Include files. \subsection{Include files} If you include a file in your source with the \var{\{\$I filename\}} directive, the compiler will look for it in the following places: \begin{enumerate} \item It will look in the path specified in the include file name. \item It will look in the directory where the current source file is. \item it will look in all directories specified in the include file search path. \end{enumerate} You can add files to the include file search path with the \seeo{I} or \seeo{Fi} options. As an example, consider the following include statement in a file \file{units/foo.pp}: \begin{verbatim} {$i ../bar.inc} \end{verbatim} Then the following command : \begin{verbatim} fpc -Iincfiles units/foo.pp \end{verbatim} will cause the compiler to look in the following directories for \file{bar.inc}: \begin{enumerate} \item The parent directory of the current directory. \item The \file{units} subdirectory of the current directory. \item The \file{incfiles} subdirectory of the current directory. \end{enumerate} % Object files. \subsection{Object files} When you link to object files (using the \var{\{\$L file.o\}} directive, the compiler will look for this file in the same way as it looks for include files: \begin{enumerate} \item It will look in the path specified in the object file name. \item It will look in the directory where the current source file is. \item It will look in all directories specified in the object file search path. \end{enumerate} You can add files to the object file search path with the \seeo{Fo} option. % Configuration file \subsection{Configuration file} \label{searchconfig} Not all options must be given on the compiler command line. The compiler can use a configuration file which can contain the same options as on the command line. There can be only one command-line option on each line in the configuration file. Unless you specify the \seeo{n} option, the compiler will look for a configuration file \file{fpc.cfg} in the following places: \begin{itemize} \item Under \unix (such as \linux) \begin{enumerate} \item The current directory. \item Your home directory, it looks for \file{.fpc.cfg}. \item The directory specified in the environment variable \var{PPC\_CONFIG\_PATH}, and if it is not set, it will look in the \file{etc} directory above the compiler directory. (For instance, if the compiler is in \file{/usr/local/bin}, it will look in \file{/usr/local/etc}) \item The directory \file{/etc}. \end{enumerate} \item Under all other OSes: \begin{enumerate} \item The current directory. \item If it is set, the directory specified in the environment variable \var{PPC\_CONFIG\_PATH}. \item The directory where the compiler is. \end{enumerate} \end{itemize} Versions prior to version 1.0.6 of the compiler used a configuration file \file{ppc386.cfg}. This file is still searched, but its usage is considered deprecated. For compatibility, \file{fpc.cfg} will be searched first, and if not found, the file \file{ppc386.cfg} will be searched and used. \begin{remark} The searching for \file{ppc386.cfg} will be removed from the compiler in version 2.4.0. To indicate this, the compiler gives a warning as of version 2.3.1 if it uses a \file{ppc386.cfg} configuration file. \end{remark} \subsection{About long filenames} \fpc can handle long filenames on all platforms, except DOS. On Windows, it will use support for long filenames if it is available (which is not always the case on older versions of Windows). If no support for long filenames is present, it will truncate unit names to 8 characters. It is not recommended to put units in directories that contain spaces in their names, since the external GNU linker doesn't understand such filenames. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Compiling a program \section{Compiling a program} Compiling a program is very simple. Assuming that you have a program source in the file \file{prog.pp}, you can compile this with the following command: \begin{verbatim} fpc [options] prog.pp \end{verbatim} The square brackets \var{[\ ]} indicate that what is between them is optional. If your program file has the \file{.pp} or \file{.pas} extension, you can omit this on the command line, e.g. in the previous example you could have typed: \begin{verbatim} fpc [options] prog \end{verbatim} If all went well, the compiler will produce an executable file. You can execute it straight away; you don't need to do anything else. You will notice that there is also another file in your directory, with extension \file{.o}. This contains the object file for your program. If you compiled a program, you can delete the object file (\file{.o}), but don't delete it if you compiled a unit. This is because the unit object file contains the code of the unit, and will be linked in any program that uses it. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Compiling a unit \section{Compiling a unit} Compiling a unit is not essentially different from compiling a program. The difference is mainly that the linker isn't called in this case. To compile a unit in the file \file{foo.pp}, just type : \begin{verbatim} fpc foo \end{verbatim} Recall the remark about file extensions in the previous section. When all went well, you will be left with 2 (two) unit files: \begin{enumerate} \item \file{foo.ppu} - this is the file describing the unit you just compiled. \item \file{foo.o} - this file contains the actual code of the unit. This file will eventually end up in the executables. \end{enumerate} Both files are needed if you plan to use the unit for some programs. So don't delete them. If you want to distribute the unit, you must provide both the \file{.ppu} and \file{.o} file. One is useless without the other. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Units libraries and smartlinking \section{Units, libraries and smartlinking} The \fpc compiler supports smartlinking and the creation of libraries. However, the default behaviour is to compile each unit into one big object file, which will be linked as a whole into your program. Shared libraries can be created on most platforms, although current level of FPC support may vary (they are e.g. not supported for GO32v2 and OS2 targets). It is also possible to take existing units and put them together in 1 static or shared library (using the \file{ppumove} tool, \sees{ppumove}). %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Reducing the size of your program \section{Reducing the size of your program} When you created your program, it is possible to reduce the size of the resulting executable. This is possible, because the compiler leaves a lot of information in the program which, strictly speaking, isn't required for the execution of the program. The surplus of information can be removed with a small program called \file{strip}.The usage is simple. Just type \begin{verbatim} strip prog \end{verbatim} On the command line, and the \file{strip} program will remove all unnecessary information from your program. This can lead to size reductions of up to 30 \%. %\begin{remark} %In the \win version, \file{strip} is called \file{stripw}. %\end{remark} You can use the \var{-Xs} switch to let the compiler do this stripping automatically at program compile time. (The switch has no effect when compiling units.) Another technique to reduce the size of a program is to use smartlinking. Normally, units (including the system unit) are linked in as a whole. It is however possible to compile units such that they can be smartlinked. This means that only the functions and procedures that are actually used are linked in your program, leaving out any unnecessary code. The compiler will turn on smartlinking with the \seeo{XX} switch. This technique is described in full in the programmers guide. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Problems %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Compiling problems} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % General problems \section{General problems} \begin{itemize} \item \textbf{IO-error -2 at ...} : Under \linux you can get this message at compiler startup. It means typically that the compiler doesn't find the error definitions file. You can correct this mistake with the \seeo{Fr} option under \linux. \item \textbf {Error : File not found : xxx} or \textbf{Error: couldn't compile unit xxx}: This typically happens when your unit path isn't set correctly. Remember that the compiler looks for units only in the current directory, and in the directory where the compiler itself is. If you want it to look somewhere else too, you must explicitly tell it to do so using the \seeo{Fu} option. Or you must set up a configuration file. \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Problems you may encounter under DOS \section{Problems you may encounter under DOS} \begin{itemize} \item \textbf{No space in environment}.\\ An error message like this can occur if you call \verb|SET_PP.BAT| in \file{AUTOEXEC.BAT}.\\ To solve this problem, you must extend your environment memory. To do this, search a line in \file{CONFIG.SYS} like \begin{verbatim} SHELL=C:\DOS\COMMAND.COM \end{verbatim} and change it to the following: \begin{verbatim} SHELL=C:\DOS\COMMAND.COM /E:1024 \end{verbatim} You may just need to specify a higher value, if this parameter is already set. \item \textbf{ Coprocessor missing}\\ If the compiler writes a message that there is no coprocessor, install the coprocessor emulation. \item \textbf{Not enough DPMI memory}\\ If you want to use the compiler with \var{DPMI} you must have at least 7-8 MB free \var{DPMI} memory, but 16 Mb is a more realistic amount. \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Configuration. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Compiler configuration} \label{ch:CompilerConfiguration} The output of the compiler can be controlled in many ways. This can be done essentially in two distinct ways: \begin{itemize} \item Using command line options. \item Using the configuration file: \file{fpc.cfg}. \end{itemize} The compiler first reads the configuration file. Only then are the command line options checked. This creates the possibility to set some basic options in the configuration file, and at the same time you can still set some specific options when compiling some unit or program. First we list the command line options, and then we explain how to specify the command line options in the configuration file. When reading this, keep in mind that the options are case sensitive. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Using the command line options \section{Using the command line options} The available options for the current version of the compiler are listed by category. Also, see \seec{commandlineoptions} for a listing as generated by the current compiler. % % General options % \subsection{General options} \begin{description} \item[-h] Print a list of all options and exit. \olabel{h} \item[-?] Same as \var{-h}, waiting after each screenfull for the enter key. \item[-i] Print copyright and other information. You can supply a qualifier, \olabel{i} as \var{-ixxx} where xxx can be one of the following: \begin{description} \item[D] : Returns the compiler date. \item[V] : Returns the short compiler version. \item[W] : Return full compiler version. \item[SO] : Returns the compiler OS. \item[SP] : Returns the compiler processor. \item[TO] : Returns the target OS. \item[TP] : Returns the target processor. \end{description} \item[-l] Print the Free Pascal logo and version number. \olabel{l} \item [-n] Ignore the default configuration file. You can still pass a configuration file with the \var{@} option. \olabel{n} \end{description} % % Options for getting feedback % \subsection{Options for getting feedback} \label{se:feedbackoptions} \begin{description} \item[-vxxx] Be verbose. \var{xxx} is a combination of the following : \olabel{v} \begin{itemize} \item \var{e} : Show errors. This option is on by default. \item \var{i} : Display some general information. \item \var{w} : Issue warnings. \item \var{n} : Issue notes. \item \var{h} : Issue hints. \item \var{i} : Issue informational messages. \item \var{l} : Report number of lines processed (every 100 lines). \item \var{u} : Show information on units being loaded. \item \var{t} : Show names of files being opened. \item \var{p} : Show names of procedures and functions being processed. \item \var{q} : Show message numbers. \item \var{c} : Notify on each conditional being processed. \item \var{mxxx} : \var{xxx} is a comma-separated list of messages numbers which should not be shown. This option can be specified multiple times. \item \var{d} : Show additional debugging information. \item \var{0} : No messages. This is useful for overriding the default setting in the configuration file. \item \var{b} : Show all procedure declarations if an overloaded function error occurs. \item \var{x} : Show information about the executable (Win32 platform only). \item \var{r} : Format errors in RHIDE/GCC compatibility mode. \item \var{a} : Show all possible information. (this is the same as specifying all options) \item \var{b} : Tells the compiler to write filenames using the full path. \item \var{v} : Write copious debugging information to file. \file{fpcdebug.txt}.. \item \var{s} : Write timestamps. Mainly for the compiler developers. %\item \var{p} Write parse tree to file tree.log. (Intended for compiler developers.) \end{itemize} \end{description} % % The difference between an error/fatal error/hint/warning/note is the severity: \begin{description} \item[Fatal] The compiler encountered an error, and can no longer continue compiling. It will stop at once. \item[Error] The compiler encountered an error, but can continue to compile (at most till the end of the current unit). \item[Warning] if there is a warning, it means there is probably an error, i.e. something may be wrong in your code. \item[Hint] Is issued if the compiler thinks the code could be better, but there is no suspicion of error. \item[Note] Is some noteworthy information, but again there is no error. \end{description} The difference between hints and notes is not really very clear. Both can be ignored without too much risk, but warnings should always be checked. % % Options concerning files and directories % \subsection{Options concerning files and directories} \begin{description} \item [-exxx] Specify \file{xxx} as the directory containing the executables for the programs \file{as} (the assembler) and \var{ld} (the linker). \olabel{e} \item[-FaXYZ] load units \var{XYZ} after the system unit, but before any other unit is loaded. \var{XYZ} is a comma-separated list of unit names. This can only be used for programs, and has the same effect as if \var{XYZ} were inserted as the first item in the program's \var{uses} clause. \item[-FcXXX] Set the input codepage to \var{XXX}. Experimental. \item[-FCxxx] Set the RC compiler (resource compiler) binary name to \file{xxx}. \item[-Fd] Disable the compiler's internal directory cache. By default, the compiler caches the names of all files in a directory as soon as it looks for a single file in said directory. This ensures that the correct case of all file names is used in the debug information. It also allows to create compiled files with the correct casing when compiling on a case-preserving file systems under an OS that also support case-sensitive file systems. Lastly, it can also increase performance. This feature can however cause severe slowdowns on networked file systems, especially when compiling trivial programs in directories containing many files, and such slowdowns can be addressed by disabling the cache using this switch. \item [-FD] Same as \var{-e}. \item [-Fexxx] Write errors, etc. to the file named \file{xxx}. \olabel{Fe} \item [-FExxx] Write the executable and units to directory \file{xxx} instead of the current directory. If this option contains a path component and is followed by an option \seeo{o}), then the \var{-o} path will override the \var{-FE} path setting. \olabel{FE} \item [-Ffxxx] Add \file{xxx} to the framework path (only for Darwin). \item [-Fixxx] Add \file{xxx} to the include file search path. \olabel{Fi} \item [-Flxxx] Add \file{xxx} to the library search path. (This is also passed to the linker.) \olabel{Fl} \item[-FLxxx] (\linux only) Use \file{xxx} as the dynamic linker. The default is \file{/lib/ld-linux.so.2}, or \file{/lib/ld-linux.so.1}, depending on which one is found first. \olabel{FL} \item[-Fmxxx] Load the unicode conversion table from file \file{x.txt} in the directory where the compiler is located. Only used when \var{-Fc} is also in effect. \item[-Foxxx] Add \file{xxx} to the object file search path. This path is used when looking for files that need to be linked in. \olabel{Fo} \item [-Frxxx] Specify \file{xxx} as the file which contain the compiler messages. This will override the compiler's built-in default messages, which are in english. \olabel{Fr} \item[-FRxxx] set the resource (.res) linker to \file{xxx}. \item [-Fuxxx] Add \file{xxx} to the unit search path. Units are first searched in the current directory. If they are not found there then the compiler searches them in the unit path. You must {\em always} supply the path to the system unit. The \file{xxx} path can contain a single wildcard (*) which will be expanded to all possible directory names found at that location. Note that the location itself is not included in the list. See \sees{unitsearching} for more information about this option. \olabel{Fu} \item [-FUxxx] Write units to directory \var{xxx} instead of the current directory. It overrides the \var{-FE} option. \item [-Ixxx] \olabel{I} Add \file{xxx} to the include file search path. This option has the same effect as \var{-Fi}. %\item [-P] uses pipes instead of files when assembling. This may speed up %the compiler on \ostwo and \linux. Only with assemblers (such as \gnu %\file{as}) that support piping... \item[-FWxxx] store generated Whole Program Optimization information in file \file{xxx}. \item[-Fwxxx] Read Whole Program Optimization information from file \file{xxx}. \end{description} % Options controlling the kind of output. \subsection{Options controlling the kind of output.} \label{se:codegen} For more information on these options, see \progref. \begin{description} \item [-a] \olabel{a} Do not delete the assembler files (not applicable when using the internal assembler). This also applies to the (possibly) generated batch script. \item [-al] \olabel{al} Include the source code lines in the assembler file as comments. \item[-an] \olabel{an} Write node information in the assember file (nodes are the way the compiler represents statements or parts thereof internally). This is primarily intended for debugging the code generated by the compiler. \item[-ap] \olabel{ap} Use pipes instead of creating temporary assembler files. This may speed up the compiler on \ostwo and \linux. Only with assemblers (such as \gnu %\file{as}) that support piping, and not if the internal assembler is used. \item[-ar] \olabel{ar} List register allocation and release info in the assembler file. This is primarily intended for debugging the code generated by the compiler. \item[-at] \olabel{at} List information about temporary allocations and deallocations in the assembler file. \item [-Axxx] \olabel{A} specify what kind of assembler should be generated. Here \var{xxx} is one of the following : \begin{description} \item[default] Use the built-in default. \item[as] Assemble using \gnu as. \item[gas] Assemble using \gnu gas. \item[gas-darwin] Assemble using \gnu gas for darwin Mach-O64. \item[nasmcoff] Coff (Go32v2) file using Nasm. \item[nasmelf] Elf32 (\linux) file using Nasm. \item[nasmwin32] \windows 32-bit file using Nasm. \item[nasmwdosx] \windows 32-bit/DOSX file using Nasm. \item[nasmobj] Object file using Nasm.darwin Mach-O64 using GNU GAS \item[macho] Mach-O (Darwin, Intel 32 bit) using internal writer. \item[masm] Object file using Masm (Microsoft). \item[tasm] Object file using Tasm (Borland). \item[elf] Elf32 (\linux) using internal writer. \item[coff] Coff object file (Go32v2) using the internal binary object writer. \item[pecoff] PECoff object file (Win32) using the internal binary object writer. \item[wasm] Object file using wasm (Watcom). \end{description} \item[-B] \olabel{B} Re-compile all used units, even if the unit sources didn't change since the last compilation. \item[-b] \olabel{b} Generate browser info. This information can be used by an Integrated Development Environment (IDE) to provide information on classes, objects, procedures, types and variables in a unit. \item[-bl] \olabel{bl} The same as \var{-b} but also generates information about local variables, types and procedures. \item[-C3] Turn on (or off) IEEE error checking for constants. \item[-Caxxx] Set the ABI (Application Binary Interface) to \file{xxx}. The \var{-i} option gives the possible values for \file{xxx}. \item[-Cb] Generate big-endian code. \item[-Cc] Set the default calling convention used by the compiler. \item [-CD] Create a dynamic library. This is used to transform units into dynamically linkable libraries on \linux. \item[-Ce] Emulate floating point operations. \item[-Cfxxx] Set the used floating point processor to \file{xxx}. \var{fpc -i} lists all possible values. \item[-CFNN] Set the minimal floating point precision to \var{NN}. Possible values are 32 and 64. \item[-Cg] Enable generation of PIC code. This should only be necessary when generating libraries on \linux or other Unices. \item [-Chxxx] \olabel {Ch} Reserves \var{xxx} bytes heap. \var{xxx} should be between 1024 and 67107840. \item [-Ci] \olabel{Ci} Generate Input/Output checking code. In case some input/output code of your program returns an error status, the program will exit with a run-time error. Which error is generated depends on the I/O error. \item [-Cn] \olabel{Cn} Omit the linking stage. \item [-Co] \olabel{Co} Generate Integer overflow checking code. In case of integer errors, a run-time error will be generated by your program. \item [-CO] \olabel{CO} Check for possible overflow of integer operations. \item [-CpXXX] Set the processor type to \var{XXX}. \item [-CPX=N] Set the packing for \file{X} to N. X can be \var{PACKSET}, \var{PACKENUM} or \var{PACKRECORD}, and N can be a value of 1,2,4,8 or one of the keywords \var{DEFAULT} or \var{NORMAL}. \item [-Cr] \olabel{Cr} Generate Range checking code. If your program accesses an array element with an invalid index, or if it increases an enumerated type beyond its scope, a run-time error will be generated. \item [-CR] \olabel{CR} Generate checks when calling methods to verify if the virtual method table for that object is valid. \item [-Csxxx] \olabel{Cs} Set stack size to \var{xxx}. \item [-Ct] \olabel{Ct} Generate stack checking code. If your program performs a faulty stack operation, a run-rime error will be generated. \item [-CX] \olabel{Cx} Create a smartlinked unit when writing a unit. Smartlinking will only link in the code parts that are actually needed by the program. All unused code is left out. This can lead to substantially smaller binaries. \item [-dxxx] \olabel{d} Define the symbol name \var{xxx}. This can be used to conditionally compile parts of your code. \item [-D] Generate a DEF file (for OS/2). \item [-Dd] Set the description of the executable/library (\windows). \item [-Dv] Set the version of the executable/library (\windows). \item [-E] \olabel{E} Same as \var{-Cn}. \item [-fPIC] same as \var{-Cg}. \item [-g] \olabel{g} Generate debugging information for debugging with \file{gdb}. \item [-gc] Generate checks for pointers. This must be used with the \var{-gh} command line option. When this options is enabled, it will verify that all pointer accesses are within the heap. %\item [-gd] \olabel{gd} Generate debugging info for \file{dbx}. \item [-gg] Same as \var{-g}. \item [-gh] Use the heaptrc unit (see \unitsref). (Produces a report about heap usage after the program exits) \item [-gl] Use the lineinfo unit (see \unitsref). (Produces file name/line number information if the program exits due to an error.) \item[-goXXX] set debug information options. One of the options is \var{dwarfsets}: It enables dwarf set debug information (this does not work with \var{gdb} versions prior to 6.5. \var{stabsabsincludes} tells the compiler to store absolute/full include file paths in stabs. \var{dwarfmethodclassprefix} tells the compiler to prefix method names in DWARF with class name. item [-gp] Preserve case in stabs symbol names. Default is to uppercase all names. \item [-gs] Write stabs debug information. \item [-gt] Trash local variables. This writes a random value to local variables at procedure start. This can be used to detect uninitialized variables. \item [-gv] Emit info for valgrind. \item [-gw] Emit dwarf debugging info (version 2). \item [-gw2] Emit dwarf debugging info (version 2). \item [-gw3] Emit dwarf debugging info (version 3). \item [-gw4] Emit dwarf debugging info (version 4, experimental). \item[-kxxx] Pass \var{xxx} to the linker. \item[-Nxxx] Do node tree optimizations. Here xxx is one of \begin{description} \item[u] Unroll loops \end{description} \item[-Oxxx] \olabel{O} Optimize the compiler's output; \var{xxx} can have one of the following values : \begin{description} \item[aPARAM=VALUE] Specify alignment of structures and code. \var{PARAM} determines what should be aligned; \var{VALUE} specifies the alignment boundary. See the Programmer's Guide for a description of the possible values. %\item[s] 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[oNNN] Specify specific optimizations: \var{NNN} can be one of \begin{description} \item[REGVAR] Use register variables \item[STACKFRAME] Skip stack frames \item[LOOPUNROLL] unroll (small) loops \item[TAILREC] change tail recursion to non-recursive loop. \item[UNCERTAIN] Uncertain optimizations (use with care). \item[CSE] Common subexpression elimination. \item[ORDERFIELDS] Reorder fields if this results in better alignment. \item[FASTMATH] Fast math operations \item[REMOVEEMPTYPROCS] remove calls to empty procedures. \item[DFA] Enable Data Flow Analysis. (normally included -O3) \end{description} \item[pxxx] select processor \var{xxx} to optimize for. \var{fpc -i} lists all available processor instruction sets. \item[Wxxx] Generate Whole-Program-Optimization information for feature \var{xxx}. \var{fpc -i} will generate a list of possible values. \item[wxxx] Perform Whole-Program-Optimization information for feature \var{xxx}. \var{fpc -i} will generate a list of possible values. \item[s] Optimize for size rather than speed. \end{description} The exact effect of some of these optimizations can be found in the \progref. \item [-oxxx] \olabel{o} Use \var{xxx} as the name of the output file (executable). For use only with programs. The output filename can contain a path, and if it does, it will override any previous \var{-FE} setting. If the output filename does not contain a path, the \var{-FE} setting is observed. \item [-pg] \olabel{gp} Generate profiler code for \file{gprof}. This will define the symbol \var{FPC\_PROFILE}, which can be used in conditional defines. \item [-s] \olabel{s} Do not call the assembler and linker. Instead, the compiler writes a script, \file{PPAS.BAT} under \dos, or \file{ppas.sh} under \linux, which can then be executed to produce an executable. This can be used to speed up the compiling process or to debug the compiler's output. This option can take an extra parameter, mainly used for cross-compilation. It can have one of the following values: \begin{description} \item[h] Generate script to link on host. The generated script can be run on the compilation platform (host platform). \item[t] Generate script to link on target platform. The generated script can be run on the target platform. (where the binary is intended to be run) \item[r] Skip register allocation phase (optimizations will be disabled). \end{description} \item[-Txxx] \olabel{T} Specify the target operating system. \var{xxx} can be one of the following: \begin{itemize} \item \textbf{emx} : OS/2 via EMX (and DOS via EMX extender). \item \textbf{freebsd} : FreeBSD. \item \textbf{go32v2} : \dos and version 2 of the DJ DELORIE extender. \item \textbf{linux} : \linux. \item \textbf{netbsd} : NetBSD. \item \textbf{netware} : Novell Netware Module (clib). \item \textbf{netwlibc} : Novell Netware Module (libc). \item \textbf{openbsd} : OpenBSD. \item \textbf{os2} : OS/2 (2.x) using the \var{EMX} extender. \item \textbf{sunos} : SunOS/Solaris. \item \textbf{watcom} : Watcom compatible DOS extender \item \textbf{wdosx} : WDOSX extender. \item \textbf{win32} : \windows 32 bit. \item \textbf{win64} : \windows 64 bit. \item \textbf{wince} : \windows for handhelds (ARM processor). \end{itemize} The available list of targets depends on the actual compiler binary. Use \var{fpc -i} to get a list of targets supported by the compiler binary. \item [-uxxx] \olabel{u} Undefine the symbol \var{xxx}. This is the opposite of the \var{-d} option. \item [-Ur] \olabel{Ur} Generate release unit files. These files will not be recompiled, even when the sources are available. This is useful when making release distributions. This also overrides the \var{-B} option for release mode units. \item[-W] Set some \windows or \ostwo attributes of the generated binary. It can be one or more of the following \begin{description} \item[A] Specify native type application (Windows) \item[b] Create a bundle instead of a library (Darwin) \item[B] Create arelocatable image (Windows) \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[e] Use external resources (Darwin) \item[F] Generate a FS application (+) or a console application (-). \item[G] Generate a GUI application (+) or a console application (-). \item[Mnnn] Minimum Mac OS X deployment version: nnn equals 10.4, 10.5.1, ... (Darwin) \item[N] Do not generate a relocation section. \item[R] Generate a relocation section. \item[T] Generate a TOOL application (+) or a console application (-). \item[X] Enable use of an executable stack (Linux) \end{description} \item [-Xx] \olabel{X} Specify executable options. This tells the compiler what kind of executable should be generated. The parameter \var{x} can be one of the following: \begin{itemize} \item \textbf{c} : (\linux only) Link with the C library. You should only use this when you start to port \fpc to another operating system. \olabel{Xe} \item \textbf{d} Do not use the standard library path. This is needed for cross-compilation, to avoid linking with the host platform's libraries. \item \textbf{D} : Link with dynamic libraries (defines the \var{FPC\_LINK\_DYNAMIC} symbol) \olabel{XD} \item \textbf{e} use external (GNU) linker. \item \textbf{g} Create debug information in a separate file and add a debuglink section to executable. \item \textbf{i} use internal linker. \item \textbf{MXXX} : Set the name of the program entry routine. The default is 'main'. \item \textbf{m} : Generate linker map file. \item \textbf{PXXX} : Prepend binutils names with \var{XXX} for cross-compiling. \item \textbf{rXXX} : Set library path to \var{XXX}. \item \textbf{Rxxx} Prepend \file{xxx} to all linker search paths. (used for cross compiling). \item \textbf{s} : Strip the symbols from the executable. \olabel{Xs} \item \textbf{S} : Link with static units (defines the \var{FPC\_LINK\_STATIC} symbol). \olabel{XS} \item \textbf{t} : Link static (passes the \var{-static} option to the linker). \olabel{Xt} \item \textbf{X} : Link with smartlinked units (defines the \var{FPC\_LINK\_SMART} symbol). \olabel{XX} \end{itemize} \end{description} % % % Options concerning the sources (language options) \subsection{Options concerning the sources (language options)} \label{se:sourceoptions} For more information on these options, see \progref \begin{description} \item[-Mmode] \olabel{M} Set language mode to \var{mode}, which can be one of the following: \begin{description} \item[delphi] Try to be Delphi compatible. This is more strict than the \var{objfpc} mode, since some \fpc extensions are switched off. \item[fpc] Free Pascal dialect (default). %\item[gpc] Try to be gpc compatible. \item[macpas] Try to be compatible with Macintosh Pascal dialects. \item[objfpc] Switch on some Delphi extensions. This is different from Delphi mode, because some \fpc constructs are still available. \item[tp] Try to be TP/BP 7.0 compatible. This means no function overloading etc. \end{description} \item[-Mfeature] \olabel{M} Select language feature \var{feature}. As of FPC version 2.3.1, the \var{-M} command line switch can be used to select individual language features. In that case, \var{feature} is one of the following keywords: \begin{description} \item[CLASS] Use object pascal classes. \item[OBJPAS] Automatically include the ObjPas unit. \item[RESULT] Enable the \var{Result} identifier for function results. \item[PCHARTOSTRING] Allow automatic conversion of null-terminated strings to strings, \item[CVAR] Allow the use of the \var{CVAR} keyword. \item[NESTEDCOMMENTS] Allow use of nested comments. \item[CLASSICPROCVARS] Use classical procedural variables. \item[MACPROCVARS] Use mac-style procedural variables. \item[REPEATFORWARD] Implementation and Forward declaration must match completely. \item[POINTERTOPROCVAR] Allow silent conversion of pointers to procedural variables. \item[AUTODEREF] Automatic (silent) dereferencing of typed pointers. \item[INITFINAL] Allow use of \var{Initialization} and \var{Finalization} \item[ANSISTRINGS] Allow use of ansistrings. \item[OUT] Allow use of the \var{out} parameter type. \item[DEFAULTPARAMETERS] Allow use of default parameter values. \item[HINTDIRECTIVE] Support the hint directives (\var{deprecated}, \var{platform} etc.) \item[DUPLICATELOCALS] Allow method arguments with the same name as properties in classes. \item[PROPERTIES] Allow use of global properties. \item[ALLOWINLINE] Allow inline procedures. \item[EXCEPTIONS] Allow the use of exceptions. \item[OBJECTIVEC1] Allow the use of objective C version 1. \item[OBJECTIVEC2] Allow the use of objective C version 2. \item[NESTEDPROCVARS] Allow assigning local procedures to procedural variables. \item[NONLOCALGOTO] Allow a GOTO statement to jump outside the local scope (as ISO Pascal). \item[ADVANCEDRECORDS] Allow the use of advanced records (records with methods/properties) \item[ISOUNARYMINUS] Treat unary minus like in ISO Pascal: same precedence level as binary minus/plus. \end{description} The keyword can be followed by a plus or minus sign to enable or disable the feature. \item [-Rxxx] \olabel{R} Specify what kind of assembler you use in your \var{asm} assembler code blocks. Here \var{xxx} is one of the following: \begin{description} \item [att\ ] \var{asm} blocks contain AT\&T-style assembler. This is the default style. \item [intel] \var{asm} blocks contain Intel-style assembler. \item [default] Use the default assembler for the specified target. \item [direct] \var{asm} blocks should be copied as is in the assembler, only replacing certain variables. \end{description} \item [-S2] \olabel{Stwo} Switch on Delphi 2 extensions (\var{objfpc} mode). Deprecated, use \var{-Mobjfpc} instead. \item [-Sa] \olabel{Sa} Include assert statements in compiled code. Omitting this option will cause assert statements to be ignored. \item [-Sc] \olabel{Sc} Support C-style operators, i.e. \var{*=, +=, /= and -=}. \item [-Sd] \olabel{Sd} Try to be Delphi compatible. Deprecated, use \var{-Mdelphi} instead. \item [-SeN] \olabel{Se} The compiler stops after the N-th error. Normally, the compiler tries to continue compiling after an error, until 50 errors are reached, or a fatal error is reached, and then it stops. With this switch, the compiler will stop after the N-th error (if N is omitted, a default of 1 is assumed). Instead of a number, one of \var{n}, \var{h} or \var{w} can also be specified. In that case the compiler will consider notes, hints or warnings as errors and stop when one is encountered. \item [-Sg] \olabel{Sg} Support the \var{label} and \var{goto} commands. By default these are not supported. You must also specify this option if you use labels in assembler statements. (if you use the \var{AT\&T} style assember) \item [-Sh] Use ansistrings by default for strings. If this option is specified, the compiler will interpret the \var{string} keyword as an ansistring. Otherwise it is supposed to be a shortstring (TP style). \item [-Si] \olabel{Si} Support \var{C++} style INLINE. \item [-SIXXX] Set interfaces style to XXX. \item [-Sk] Load the Kylix compatibility unit (\file{fpcylix}). \item [-Sm] \olabel{Sm} Support C-style macros. \item [-So] \olabel{So} Try to be Borland TP 7.0 compatible. Deprecated, use \var{-Mtp} instead. %\item [-Sp] \olabel{Sp} Try to be \file{gpc} (\gnu Pascal compiler) %compatible. Deprecated, use \var{-Mgpc} instead. \item [-Ss] \olabel{Ss} The name of constructors must be \var{init}, and the name of destructors should be \var{done}. \item [-St] \olabel{St} Allow the \var{static} keyword in objects. \item [-Sx] Enable exception keywords (default in Delphi/Objfpc mode). This will mark all exception related keywords as keywords, also in \tp or \file{FPC} mode. This can be used to check for code which should be mode-neutral as much as possible. \item [-Un] \olabel{Un} Do not check the unit name. Normally, the unit name is the same as the filename. This option allows them to be different. \item [-Us] \olabel{Us} Compile a system unit. This option causes the compiler to define only some very basic types. \end{description} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Using the configuration file \section{Using the configuration file} \label{se:configfile} Using the configuration file \file{fpc.cfg} is an alternative to command line options. When a configuration file is found, it is read, and the lines in it are treated as if you had typed them as options on the command line: Specify one option on each line of the configuration file. 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. \subsection{Conditional processing of the config file} In addition to placeholder substitution, the configuration file allows a type of preprocessing. It understands the following directives, which you should place starting on the first column of a line: \begin{description} \item [\#IFDEF] \item [\#IFNDEF] \item [\#ELSE] \item [\#ENDIF] \item [\#DEFINE] \item [\#UNDEF] \item [\#WRITE] \item [\#INCLUDE] \item [\#SECTION] \end{description} They work the same way as their \{\$...\} counterparts in Pascal source code. All the default defines used to compile source code are also defined while processing the configuration file. For example, if the target compiler is an intel 80x86 compatible linux platform, both \var{cpu86} and \var{linux} will be defined while interpreting the configuration file. For the possible default defines when compiling, consult Appendix G of the \progref. What follows is a description of the different directives. \subsection{\#IFDEF} Syntax: \begin{verbatim} #IFDEF name \end{verbatim} Lines following \var{\#IFDEF} are read only if the keyword \var{name} following it is defined. They are read until the keywords \var{\#ELSE} or \var{\#ENDIF} are encountered, after which normal processing is resumed. Example : \begin{verbatim} #IFDEF VER2_6_0 -Fu/usr/lib/fpc/2.6.0/linuxunits #ENDIF \end{verbatim} In the above example, \file{/usr/lib/fpc/2.6.0/linuxunits} will be added to the path if you're compiling with version 2.6.0 of the compiler. \subsection{\#IFNDEF} Syntax: \begin{verbatim} #IFNDEF name \end{verbatim} Lines following \var{\#IFNDEF} are read only if the keyword \var{name} following it is not defined. They are read until the keywords \var{\#ELSE} or \var{\#ENDIF} are encountered, after which normal processing is resumed. Example : \begin{verbatim} #IFNDEF VER2_6_0 -Fu/usr/lib/fpc/2.6.0/linuxunits #ENDIF \end{verbatim} In the above example, \file{/usr/lib/fpc/2.6.0/linuxunits} will be added to the path if you're NOT compiling with version 2.6.0 of the compiler. \subsection{\#ELSE} Syntax: \begin{verbatim} #ELSE \end{verbatim} \var{\#ELSE} can be specified after a \var{\#IFDEF} or \var{\#IFNDEF} directive as an alternative. Lines following \var{\#ELSE} are read only if the preceding \var{\#IFDEF} or \var{\#IFNDEF} was not accepted. They are skipped until the keyword \var{\#ENDIF} is encountered, after which normal processing is resumed. Example : \begin{verbatim} #IFDEF VER2_6_2 -Fu/usr/lib/fpc/2.6.2/linuxunits #ELSE -Fu/usr/lib/fpc/2.6.0/linuxunits #ENDIF \end{verbatim} In the above example, \file{/usr/lib/fpc/2.6.2/linuxunits} will be added to the path if you're compiling with version 2.6.2 of the compiler, otherwise \file{/usr/lib/fpc/2.6.0/linuxunits} will be added to the path. \subsection{\#ENDIF} Syntax: \begin{verbatim} #ENDIF \end{verbatim} \var{\#ENDIF} marks the end of a block that started with \var{\#IF(N)DEF}, possibly with an \var{\#ELSE} between them. \subsection{\#DEFINE} Syntax: \begin{verbatim} #DEFINE name \end{verbatim} \var{\#DEFINE} defines a new keyword. This has the same effect as a \var{-dname} command line option. \subsection{\#UNDEF} Syntax: \begin{verbatim} #UNDEF name \end{verbatim} \var{\#UNDEF} un-defines a keyword if it existed. This has the same effect as a \var{-uname} command line option. \subsection{\#WRITE} Syntax: \begin{verbatim} #WRITE Message Text \end{verbatim} \var{\#WRITE} writes \var{Message Text} to the screen. This can be useful to display warnings if certain options are set. Example: \begin{verbatim} #IFDEF DEBUG #WRITE Setting debugging ON... -g #ENDIF \end{verbatim} If \var{DEBUG} is defined, this will produce a line \begin{verbatim} Setting debugging ON... \end{verbatim} and will then switch on debugging information in the compiler. \subsection{\#INCLUDE} Syntax: \begin{verbatim} #INCLUDE filename \end{verbatim} \var{\#INCLUDE} instructs the compiler to read the contents of \file{filename} before continuing to process options in the current file. This can be useful if you want to have a particular configuration file for a project (or, under \linux, in your home directory), but still want to have the global options that are set in a global configuration file. Example: \begin{verbatim} #IFDEF LINUX #INCLUDE /etc/fpc.cfg #ELSE #IFDEF GO32V2 #INCLUDE c:\pp\bin\fpc.cfg #ENDIF #ENDIF \end{verbatim} This will include \file{/etc/fpc.cfg} if you're on a \linux machine, and will include \verb+c:\pp\bin\fpc.cfg+ on a \dos machine. \subsection{\#SECTION} Syntax: \begin{verbatim} #SECTION name \end{verbatim} The \var{\#SECTION} directive acts as a \var{\#IFDEF} directive, only it doesn't require an \var{\#ENDIF} directive. The special name \var{COMMON} always exists, i.e. lines following \var{\#SECTION COMMON} are always read. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Variable subsitution in paths \section{Variable substitution in paths} To avoid having to edit your configuration files too often, the compiler allows you to insert some variables in the paths that you specify for the compiler. They are specified as follows: \begin{verbatim} $VARNAME \end{verbatim} The above will be replaced with the value of the variable \var{VARNAME}. Normally, only a set of compiler-defined variable names are recognized. In addition to these compiler-defined variable names, the following notation can be used \begin{verbatim} $ENVVAR$ \end{verbatim} to substiture the value of an environment variable. The compiler will fetch the value of \var{ENVVAR} from the environment, and replace the \var{\$ENVVAR\$} with this value. The compiler defines the following variable names: \begin{description} \item[FPCFULLVERSION] is replaced by the compiler's version string. \item[FPCVERSION] is replaced by the compiler's version string. \item[FPCDATE] is replaced by the compiler's date. \item[FPCTARGET] is replaced by the compiler's target (combination of CPU-OS) \item[FPCCPU] is replaced by the compiler's target CPU. \item[FPCOS] is replaced by the compiler's target OS. \end{description} Additionally, under windows the following special variables are recognized: \begin{description} \item[LOCAL\_APPDATA] Usually the directory "Local settings/Application Data" under the user's home directory. \item[APPDATA] Usually the directory "Application Data" under the user's home directory. \item[COMMON\_APPDATA] Usually the directory "Application Data" under the 'All users' directory. \item[PERSONAL] Usually the "My documents" directory of the user. \item[PROGRAM\_FILES] Usually "program files" directory on the system drive \item[PROGRAM\_FILES\_COMMON] Usually the "Common files" directory under the program files directory. \item[PROFILE] The user's home directory. \end{description} The values of these can vary based on the installation, they are fetched from the operating system. If none of the pre-defines variable names were matched, and the template name ends on \$, then the environment variable with the same name is used: \begin{verbatim} -Fu$HOME$/FPC/currentversion/ \end{verbatim} This will refer to the directory \file{FPC/currentversion} under the user's home directory on Unix (HOME is the environment variable that contains the location of the user's directory). So, have one of the above variables subsituted, just insert them with a \var{\$} prepended, as follows: \begin{verbatim} -Fu/usr/lib/fpc/$FPCVERSION/rtl/$FPCOS \end{verbatim} This is equivalent to \begin{verbatim} -Fu/usr/lib/fpc/2.6.2/rtl/linux \end{verbatim} if the compiler version is \var{2.6.2} and the target OS is \linux{}. These replacements are valid on the command line and also in the configuration file. On the \linux{} command line, you must be careful to escape the \var{\$} since otherwise the shell will attempt to expand the variable for you, which may have undesired effects. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % IDE. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \input{ide.tex} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Porting. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Porting and portable code} \section{Free Pascal compiler modes} The \fpc team tries to create a compiler that can compile as much as possible code produced for \tp, \delphi{} or the Mac pascal compilers: this should make sure that porting code that was written for one of these compilers is as easy as possible. At the same time, the \fpc developers have introduced a lot of extensions in the Object Pascal language. To reconcile these different goals, and to make sure that people can produce code which can still be compiled by the \tp and \delphi compilers, the compiler has a concepts of 'compiler modes'. In a certain compiler mode, the compiler has certain functionalities switched on or off. This allows to introduce a compatibility mode in which only features supported by the original compiler are supported. Currently, 5 modes are supported: \begin{description} \item[FPC] This is the original \fpc compiler mode: here all language constructs except classes, interfaces and exceptions are supported. Objects are supported in this mode. This is the default mode of the compiler. \item[OBJFPC] This is the same mode as \var{FPC} mode, but it also includes classes, interfaces and exceptions. \item[TP] Turbo Pascal compatibility mode. In this mode, the compiler tries to mimic the Turbo Pascal compiler as closely as possible. Obviously, only 32-bit or 64-bit code can be compiled. \item[DELPHI] Delphi compatibility mode. In this mode, the compiler tries to resemble the Delphi compiler as best as it can: All Delphi 7 features are implemented. Features that were implemented in the .NET versions of Delphi are {\em not} implemented. \item[MACPAS] the Mac Pascal compatibility mode. In this mode, the compiler attempts to allow all constructs that are implemented in Mac pascal. In particular, it attempts to compile the universal interfaces. \end{description} The compiler mode can be set on a per-unit basis: each unit can have its own compiler mode, and it is possible to use units which have been compiled in different modes intertwined. The mode can be set in one of 2 ways: \begin{enumerate} \item On the command line, with the -M switch. \item In the source file, with the \var{\{\$MODE \}} directive. \end{enumerate} Both ways take the name of the mode as an argument. If the unit or program source file does not specify a mode, the mode specified on the command-line is used. If the source file specifies a mode, then it overrides the mode given on the command-line. Thus compiling a unit with the \var{-M} switch as follows: \begin{verbatim} fpc -MOBJFPC myunit \end{verbatim} is the same as having the following mode directive in the unit: \begin{verbatim} {$MODE OBJFPC} Unit myunit; \end{verbatim} The \var{MODE} directive should always be located before the uses clause of the unit interface or program uses clause, because setting the mode may result in the loading of an additional unit as the first unit to be loaded. Note that the \var{\{\$MODE \}} directive is a global directive, i.e. it is valid for the whole unit; Only one directive can be specified. The mode has no influence on the availability of units: all available units can be used, independent of the mode that is used to compile the current unit or program. \section{Turbo Pascal} \fpc was originally designed to resemble Turbo Pascal as closely as possible. There are, of course, restrictions. Some of these are due to the fact that Turbo Pascal was developed for 16-bit architectures whereas \fpc is a 32-bit/64-bit compiler. Other restrictions result from the fact that \fpc works on more than one operating system. In general we can say that if you keep your program code close to ANSI Pascal, you will have no problems porting from Turbo Pascal, or even Delphi, to \fpc. To a large extent, the constructs defined by Turbo Pascal are supported. This is even more so if you use the \var{-Mtp} or \var{-MObjfpc} switches. In the following sections we will list the Turbo Pascal and Delphi constructs which are not supported in \fpc, and we will list in what ways \fpc extends Turbo Pascal. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Things that will not work \subsection{Things that will not work} Here we give a list of things which are defined/allowed in Turbo Pascal, but which are not supported by \fpc. Where possible, we indicate the reason. \begin{enumerate} \item Duplicate case labels are permitted in Turbo Pascal, but not in \fpc. This is actually a bug in Turbo Pascal, and so support for it will not be implemented in Free Pascal. \item In \tp, parameter lists of previously defined functions and procedures did not have to match exactly. In Free Pascal, they must. The reason for this is the function overloading mechanism of \fpc. However, the \seeo{M} option overcomes this restriction. \item The Turbo Pascal variables \var{MEM, MEMW, MEML} and \var{PORT} for memory and port access are not available in the system unit. This is due to the operating system. Under \dos, both the system and the extender unit (\file {GO32}) implement the mem constuct. Under \linux, the \file{ports} unit implements such a construct for the \var{Ports} variable. \item Turbo Pascal allows you to create procedure and variable names using words that are not permitted in that role in Free Pascal. This is because there are certain words that are reserved in Free Pascal (and Delphi) that are not reserved in Turbo Pascal, such as: \var{PROTECTED, PUBLIC, PUBLISHED, TRY, FINALLY, EXCEPT, RAISE}. Using the \var{-Mtp} switch will solve this problem if you want to compile Turbo Pascal code that uses these words (\seec{reserved} for a list of all reserved words). \item The Turbo Pascal reserved words \var{FAR, NEAR} are ignored. This is because their purpose was limited to a 16-bit environment and \fpc is a 32-bit/64-bit compiler. \item The Turbo Pascal \var{INTERRUPT} directive will work only on the \fpc \dos target. Other operating systems do not allow handling of interrupts by user programs. \item By default the \fpc compiler uses \var{AT\&T} assembler syntax. This is mainly because \fpc uses \gnu \var{as}. However, other assembler forms are available. For more information, see the \progref. \item Turbo Pascal's Turbo Vision is available in \fpc under the name of FreeVision, which should be almost 100\% compatible with Turbo Vision. \item Turbo Pascal's 'overlay' unit is not available. It also isn't necessary, since \fpc is a 32/64-bit compiler, so program size shouldn't be an issue. %\item Turbo Pascal has fewer reserved words than Free Pascal. %(see appendix \ref{ch:reserved} for a list of all reserved words.) \item The command line parameters of the compiler are different. \item Compiler switches and directives are mostly the same, but some extra exist. \item Units are not binary compatible. That means that you cannot use a \file{.tpu} unit file, produced by Turbo Pascal, in a \fpc project. \item The \fpc \var{TextRec} structure (for internal description of files) is not binary compatible with TP or Delphi. \item Sets are by default 4 bytes in Free Pascal; this means that some typecasts which were possible in Turbo Pascal are no longer possible in Free Pascal. However, there is a switch to set the set size, see \progref for more information. \item A file is opened for output only (using \var{fmOutput}) when it is opened with \var{Rewrite}. In order to be able to read from it, it should be reset with \var{Reset}. \item Turbo Pascal destructors allowed parameters. This is not permitted in Free Pascal: by default, in \fpc, Destructors cannot have parameters. This restriction can be removed by using the \var{-So} switch. \item Turbo Pascal permits more than one destructor for an object. In \fpc, there can be only one destructor. This restriction can also be removed by using the \var{-So} switch. \item The order in which expressions are evaluated is not necessarily the same. In the following expression: \begin{verbatim} a := g(2) + f(3); \end{verbatim} it is not guaranteed that \var{g(2)} will be evaluated before \var{f(3)}. \item In \fpc, you need to use the address @ operator when assigning procedural variables. \end{enumerate} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Things which are extra \subsection{Things which are extra} Here we give a list of things which are possible in \fpc, but which didn't exist in Turbo Pascal or Delphi. \begin{enumerate} \item \fpc functions can also return complex types, such as records and arrays. \item In \fpc, you can use the function return value in the function itself, as a variable. For example: \begin{verbatim} function a : longint; begin a:=12; while a>4 do begin {...} end; end; \end{verbatim} The example above would work with TP, but the compiler would assume that the \var{a>4} is a recursive call. If a recursive call is actually what is desired, you must append \var{()} after the function name: \begin{verbatim} function a : longint; begin a:=12; { this is the recursive call } if a()>4 then begin {...} end; end; \end{verbatim} \item In \fpc, there is partial support of Delphi constructs. (See the \progref for more information on this). \item The \fpc \var{exit} call accepts a return value for functions. \begin{verbatim} function a : longint; begin a:=12; if a>4 then begin exit(a*67); {function result upon exit is a*67 } end; end; \end{verbatim} \item \fpc supports function overloading. That is, you can define many functions with the same name, but with different arguments. For example: \begin{verbatim} procedure DoSomething (a : longint); begin {...} end; procedure DoSomething (a : real); begin {...} end; \end{verbatim} You can then call procedure \var{DoSomething} with an argument of type \var{Longint} or \var{Real}.\\ This feature has the consequence that a previously declared function must always be defined with the header completely the same: \begin{verbatim} procedure x (v : longint); forward; {...} procedure x;{ This will overload the previously declared x} begin {...} end; \end{verbatim} This construction will generate a compiler error, because the compiler didn't find a definition of \var{procedure x (v : longint);}. Instead you should define your procedure x as: \begin{verbatim} procedure x (v : longint); { This correctly defines the previously declared x} begin {...} end; \end{verbatim} The command line option \seeo{So} disables overloading. When you use it, the above will compile, as in Turbo Pascal. \item Operator overloading. \fpc allows operator overloading, e.g. you can define the '+' operator for matrices. \item On FAT16 and FAT32 systems, long file names are supported. \end{enumerate} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Turbo Pascal compatibility mode \subsection{Turbo Pascal compatibility mode} When you compile a program with the \var{-Mtp} switch, the compiler will attempt to mimic the Turbo Pascal compiler in the following ways: \begin{itemize} \item Assigning a procedural variable doesn't require an @ operator. One of the differences between Turbo Pascal and \fpc is that the latter requires you to specify an address operator when assigning a value to a procedural variable. In Turbo Pascal compatibility mode, this is not required. \item Procedure overloading is disabled. If procedure overloading is disabled, the function header doesn't need to repeat the function header. \item Forward defined procedures don't need the full parameter list when they are defined. Due to the procedure overloading feature of \fpc, you must always specify the parameter list of a function when you define it, even when it was declared earlier with \var{Forward}. In Turbo Pascal compatibility mode, there is no function overloading; hence you can omit the parameter list: \begin{verbatim} Procedure a (L : Longint); Forward; ... Procedure a ; { No need to repeat the (L : Longint) } begin ... end; \end{verbatim} \item Recursive function calls are handled differently. Consider the following example: \begin{verbatim} Function expr : Longint; begin ... Expr:=L: Writeln (Expr); ... end; \end{verbatim} In Turbo Pascal compatibility mode, the function will be called recursively when the \var{writeln} statement is processed. In \fpc, the function result will be printed. In order to call the function recursively under \fpc, you need to implement it as follows : \begin{verbatim} Function expr : Longint; begin ... Expr:=L: Writeln (Expr()); ... end; \end{verbatim} %\item Any text after the final \var{End.} statement is ignored. Normally, %this text is processed too. \item You cannot assign procedural variables to untyped pointers; so the following is invalid: \begin{verbatim} a: Procedure; b: Pointer; begin b := a; // Error will be generated. \end{verbatim} \item The @ operator is typed when applied on procedures. \item You cannot nest comments. \end{itemize} \begin{remark} The \var{MemAvail} and \var{MaxAvail} functions are no longer available in \fpc as of version 2.0. The reason for this incompatibility follows: On modern operating systems, \footnote{The DOS extender GO32V2 falls under this definition of "modern" because it can use paged memory and run in multitasked environments.} the idea of "Available Free Memory" is not valid for an application. The reasons are: \begin{enumerate} \item One processor cycle after an application asked the OS how much memory is free, another application may have allocated everything. \item It is not clear what "free memory" means: does it include swap memory, does it include disk cache memory (the disk cache can grow and shrink on modern OS'es), does it include memory allocated to other applications but which can be swapped out, etc. \end{enumerate} Therefore, programs using \var{MemAvail} and \var{MaxAvail} functions should be rewritten so they no longer use these functions, because it does not make sense any more on modern OS'es. There are 3 possibilities: \begin{enumerate} \item Use exceptions to catch out-of-memory errors. \item Set the global variable "ReturnNilIfGrowHeapFails" to \var{True} and check after each allocation whether the pointer is different from \var{Nil}. \item Don't care and declare a dummy function called \var{MaxAvail} which always returns \var{High(LongInt)} (or some other constant). \end{enumerate} \end{remark} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % A note about long file names. \subsection{A note on long file names under \dos} Under \windows 95 and higher, long filenames are supported. Compiling for the \windows target ensures that long filenames are supported in all functions that do file or disk access in any way. Moreover, \fpc supports the use of long filenames in the system unit and the \file{Dos} unit also for go32v2 executables. The system unit contains the boolean variable \var{LFNsupport}. If it is set to \var{True} then all system unit functions and \file{Dos} unit functions will use long file names if they are available. This should be so on \windows 95 and 98, but not on \windows NT or \windows 2000. The system unit will check this by calling \dos function \var{71A0h} and checking whether long filenames are supported on the \file{C:} drive. It is possible to disable the long filename support by setting the \var{LFNSupport} variable to \var{False}; but in general it is recommended to compile programs that need long filenames as native \windows applications. \section{Porting Delphi code} Porting Delphi code should be quite painless. The \var{Delphi} mode of the compiler tries to mimic Delphi as closely as possible. This mode can be enabled using the \var{-Mdelphi} command line switch, or by inserting the following code in the sources before the \var{unit} or \var{program} clause: \begin{verbatim} {$IFDEF FPC} {$MODE DELPHI} {$ENDIF FPC} \end{verbatim} This ensures that the code will still compile with both Delphi and FPC. Nevertheless, there are some things that will not work. Delphi compatibility is relatively complete up to Delphi 7. New constructs in higher versions of Delphi (notably, the versions that work with .NET) are not supported. \subsection{Missing language constructs} At the level of language compatibility, FPC is very compatible with Delphi: it can compile most of FreeCLX, the free Widget library that was shipped with Delphi 6, Delphi 7 and Kylix. Currently, the only missing language constructs are: \begin{enumerate} \item \var{Dynamic} methods are actually the same as \var{virtual}. \item \var{Const} for a parameter to a procedure does not necessarily mean that the variable or value is passed by reference. \item Packages are not supported. \end{enumerate} There are some inline assembler constructs which are not supported, and since \fpc is designed to be platform independent, it is quite unlikely that these constructs will be supported in the future. Note that the \var{-Mobjfpc} mode switch is to a large degree Delphi compatible, but is more strict than Delphi. The most notable differences are: \begin{enumerate} \item Parameters or local variables of methods cannot have the same names as properties of the class in which they are implemented. \item The address operator is needed when assigning procedural variables (or event handlers). \item AnsiStrings are not switched on by default. \end{enumerate} \subsection{Missing calls / API incompatibilities} Delphi is heavily bound to Windows. Because of this, it introduced a lot of Windows-isms in the API (e.g. file searching and opening, loading libraries). \fpc was designed to be portable, so things that are very Windows specific are missing, although the \fpc team tries to minimize this. The following are the main points that should be considered: \begin{itemize} \item By default, \fpc generates console applications. This means that you must explicitly enable the GUI application type for Windows: \begin{verbatim} {$APPTYPE GUI} \end{verbatim} \item The \file{Windows} unit provides access to most of the core Win32 API. Some calls may have different parameter lists: instead of declaring a parameter as passed by reference (var), a pointer is used (as in C). For most cases, \fpc provides overloaded versions of such calls. \item Widestrings. Widestring management is not automatic in \fpc, since various platforms have different ways of dealing with widestring encodings and Multi-Byte Character Sets. FPC supports Widestrings, but may not use the same encoding as on Windows. Note that in order to have correct widestring management, you need to include the \file{cwstring} unit on Unix/\linux platforms: This unit initializes the widestring manager with the necessary callbacks which use the C library to implement all needed widestring functionality. \item Threads: At this moment, \fpc does not offer native thread management on all platforms; on Unix, linking to the C library is needed to provide thread management in an FPC application. This means that a \file{cthreads} unit must be included to enable threads. \item A much-quoted example is the \var{SetLastOSError} call. This is not supported, and will never be supported. \item Filename Case sensitivity: Pascal is a case-insensitive language, so the uses clause should also be case insensitive. Free Pascal ensures case insensitive filenames by also searching for a lowercase version of the file. Kylix does not do this, so this could create problems if two differently cased versions of the same filename are in the path. \item RTTI is NOT stored in the same way as for Delphi. The format is mostly compatible, but may differ. This should not be a problem if the API of the TypeInfo unit is used and no direct access to the RTTI information is attempted. \item By default, sets are of different size than in Delphi, but set size can be specified using directives or command line switches. \item Likewise, by default enumeration types are of different size than in Delphi. Here again, the size can be specified using directives or command line switches. \item In general, one should not make assumptions about the internal structure of complex types such as records, objects, classes and their associated structure. For example, the VMT table layout is different, the alignment of fields in a record may be different, etc. \item The same is true for basic types: on other processors the high and low bytes of a word or integer may not be at the same location as on an Intel processor (the endianness is different). \item Names of local variables and method arguments are not allowed to match the name of a property or field of the class: this is bad practise, as there can be confusion as to which of the two is meant. \end{itemize} \subsection{Delphi compatibility mode} Switching on Dephi compatibility mode has the following effect: \begin{enumerate} \item Support for Classes, exceptions and threadvars is enabled. \item The \file{objpas} is loaded as the first unit. This unit redefines some basic types: \var{Integer} is 32-bit for instance. \item The address operator (@) is no longer needed to set event handlers (i.e. assign to procedural variables or properties). \item Names of local variables and method parameters in classes can match the name of properties or field of the class. \item The \var{String} keyword implies \var{AnsiString} by default. \item Operator overloading is switched off. \end{enumerate} \subsection{Best practices for porting} When encountering differences in Delphi/FPC calls, the best thing to do is not to insert IFDEF statements whenever a difference is encountered, but to create a separate unit which is only used when compiling with FPC. The missing/incompatible calls can then be implemented in that unit. This will keep the code more readable and easier to maintain. If a language construct difference is found, then the \fpc team should be contacted and a bug should be reported. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % writing portable code %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Writing portable code} \fpc is designed to be cross-platform. This means that the basic RTL units are usable on all platforms, and the compiler behaves the same on all platforms (as far as possible). The Object Pascal language is the same on all platforms. Nevertheless, FPC comes with a lot of units that are not portable, but provide access to all possibilities that a platform provides. The following are some guidelines to consider when writing portable code: \begin{itemize} \item Avoid system-specific units. The system unit, the objects and classes units and the SysUtils unit are guaranteed to work on all systems. So is the DOS unit, but that is deprecated. \item Avoid direct hardware access. Limited, console-like hardware access is available for most platforms in the Video, Mouse and Keyboard units. \item Do not use hard-coded filename conventions. See below for more information on this. \item Make no assumptions on the internal representation of types. Various processors store information in different ways ('endianness'). \item If system-specific functionality is needed, it is best to separate this out in a single unit. Porting efforts will then be limited to re-implementing this unit for the new platform. \item Don't use assembler, unless you have to. Assembler is processor specific. Some instructions will not work even on the same processor family. \item Do not assume that pointers and integers have the same size. They do on an Intel 32-bit processor, but not necessarily on other processors. The \var{PtrInt} type is an alias for the integer type that has the same size as a pointer. \var{SizeInt} is used for all size-related issues. \end{itemize} The system unit contains some constants which describe file access on a system: \begin{description} \item[AllFilesMask] a file mask that will return all files in a directory. This is \var{*} on Unix-like platforms, and \var{*.*} on dos and windows like platforms. \item[LineEnding] A character or string which describes the end-of-line marker used on the current platform. Commonly, this is one of \#10, \#13\#10 or \#13. \item[LFNSupport] A boolean that indicates whether the system supports long filenames (i.e. is not limited to MS-DOS 8.3 filenames). \item[DirectorySeparator] The character which acts as a separator between directory parts of a path. \item[DriveSeparator] For systems that support drive letters, this is the character that is used to separate the drive indication from the path. \item[PathSeparator] The character used to separate items in a list (notably, a PATH). \item[maxExitCode] The maximum value for a process exitcode. \item[MaxPathLen] The maximum length of a filename, including a path. \item[FileNameCaseSensitive] A boolean that indicates whether filenames are handled case sensitively. \item[FileNameCasePreserving] A boolean that indicates whether case in filenames is preserved on creation or rename. \item[UnusedHandle] A value used to indicate an unused/invalid file handle. \item[StdInputHandle] The value of the standard input file handle. This is not always 0 (zero), as is commonly the case on Unices. \item[StdOutputHandle] The value of the standard output file handle. This is not always 1, as is commonly the case on Unices. \item[StdErrorHandle] The value of the standard diagnostics output file handle. This is not always 2, as is commonly the case on Unices. \item[CtrlZMarksEOF] A boolean that indicates whether the \#26 character marks the end of a file (an old MS-DOS convention). \end{description} To ease writing portable filesystem code, the Free Pascal file routines in the system unit and \file{sysutils} unit treat the common directory separator characters (/ and $\backslash$) as equivalent. That means that if you use / on a \windows system, it will be transformed to a backslash, and vice versa. This feature is controlled by 2 (pre-initialized) variables in the system unit: \begin{description} \item[AllowDirectorySeparators] A set of characters which, when used in filenames, are treated as directory separators. They are transformed to the \var{DirectorySeparator} character. \item[AllowDriveSeparators] A set of characters which, when used in filenames, are treated as drive separator characters. They are transformed to the \var{DriveSeparator} character. \end{description} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Utilities. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Utilities that come with Free Pascal} \label{ch:Utilities} Besides the compiler and the runtime Library, \fpc comes with some utility programs and units. Here we list these programs and units. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Demo programs and examples. \section{Demo programs and examples} A suite of demonstration programs comes included with the Free Pascal distribution. These programs have no other purpose than to demonstrate the capabilities of \fpc. They are located in the \file{demo} directory of the sources. All example programs mentioned in the documentation are available. Check out the directories that are beneath the same directory as the demo directory. The names of these directories end on \file{ex}. There you will find all example sources. \section{fpcmake} \file{fpcmake} is the \fpc makefile constructor program. It reads a \file{Makefile.fpc} configuration file and converts it to a \file{Makefile} suitable for reading by GNU \file{make} to compile your projects. It is similar in functionality to GNU \file{autoconf} or \file{Imake} for making X projects. \file{fpcmake} accepts filenames of makefile description files as its command line arguments. For each of these files it will create a \file{Makefile} in the same directory where the file is located, overwriting any other existing file. If no options are given, it just attempts to read the file \file{Makefile.fpc} in the current directory and tries to construct a makefile from it. Any previously existing \file{Makefile} will be erased. The format of the \file{fpcmake} configuration file is described in great detail in the appendices of the \progref. \section{fpdoc - Pascal Unit documenter} \file{fpdoc} is a program which generates fully cross-referenced documentation for a unit. It generates documentation for each identifier found in the unit's interface section. The generated documentation can be in many formats, for instance HTML, RTF, Text, man page and LaTeX. Unlike other documentation tools, the documentation can be in a separate file (in XML format), so the sources aren't cluttered with documentation. Its companion program \file{makeskel} creates an empty XML file with entries for all identifiers, or it can update an existing XML file, adding entries for new identifiers. \file{fpdoc} and \file{makeskel} are described in the \fpdocref. \section{h2pas - C header to Pascal Unit converter} \file{h2pas} attempts to convert a C header file to a Pascal unit. it can handle most C constructs that one finds in a C header file, and attempts to translate them to their Pascal counterparts. See below (constructs) for a full description of what the translator can handle. The unit with Pascal declarations can then be used to access code written in C. The output of the h2pas program is written to a file with the same name as the C header file that was used as input, but with the extension \file{.pp} The output file that h2pas creates can be customized in a number of ways by means of many options. \subsection{Options} The output of \file{h2pas} can be controlled with the following options: \begin{description} \item[-d] Use \var{external;} for all procedure and function declarations. \item[-D] Use \var{external libname name 'func\_name'} for function and procedure declarations. \item[-e] Emit a series of constants instead of an enumeration type for the C \var{enum} construct. \item[-i] Create an include file instead of a unit (omits the unit header). \item[-l] \textbf{libname} specify the library name for external function declarations. \item[-o] \textbf{outfile} Specify the output file name. Default is the input file name with the extension replaced by \file{.pp} \item[-p] Use the letter \var{P} in front of pointer type parameters instead of \^. \item[-s] Strip comments from the input file. By default comments are converted to comments, but they may be displaced, since a comment is handled by the scanner. \item[-t] Prepend typedef type names with the letter \var{T} (used to follow Borland's convention that all types should be defined with T). \item[-v] Replace pointer parameters with call by reference parameters. Use with care because some calls can expect a \var{Nil} pointer. \item[-w] Header file is a win32 header file (adds support for some special macros). \item[-x] Handle SYS\_TRAP of the PalmOS header files. \end{description} \subsection{Constructs} The following C declarations and statements are recognized: \begin{description} \item[defines] Defines are changed into Pascal constants if they are simple defines. Macros are changed - wherever possible - to functions; however the arguments are all integers, so these must be changed manually. Simple expressions in define staments are recognized, as are most arithmetic operators: addition, substraction, multiplication, division, logical operators, comparison operators, shift operators. The C construct ( A ? B : C) is also recognized and translated to a Pascal construct with an IF statement. (This is buggy, however). \item[preprocessor statements] The conditional preprocessing commands are recognized and translated into equivalent Pascal compiler directives. The special \begin{verbatim} #ifdef __cplusplus \end{verbatim} is also recognized and removed. \item[typedef] A typedef statement is changed into a Pascal type statement. The following basic types are recognized: \begin{itemize} \item \var{char} changed to \var{char}. \item \var{float} changed to \var{real} (=double in \fpc). \item \var{int} changed to \var{longint}. \item \var{long} changed to \var{longint}. \item \var{long int} changed to \var{longint}. \item \var{short} changed to \var{integer}. \item \var{unsigned} changed to \var{cardinal}. \item \var{unsigned char} changed to \var{byte}. \item \var{unsigned int} changed to \var{cardinal}. \item \var{unsigned long int} changed to \var{cardinal}. \item \var{unsigned short} changed to \var{word}. \item \var{void} ignored. \end{itemize} These types are also changed if they appear in the arguments of a function or procedure. \item[functions and procedures] Functions and procedures are translated as well. Pointer types may be changed to call by reference arguments (using the \var{var} argument) by using the \var{-p} command line argument. Functions that have a variable number of arguments are changed to a function with a \var{cvar} modifier. (This used to be the \var{array of const} argument.) \item[specifiers] The \var{extern} specifier is recognized; however it is ignored. The \var{packed} specifier is also recognised and changed with the \var{PACKRECORDS} directive. The \var{const} specifier is also recognized, but is ignored. \item[modifiers] If the \var{-w} option is specified, then the following modifiers are recognized: \begin{verbatim} STDCALL CDECL CALLBACK PASCAL WINAPI APIENTRY WINGDIAPI \end{verbatim} as defined in the win32 headers. If additionally the \var{-x} option is specified then the \begin{verbatim} SYS_TRAP \end{verbatim} specifier is also recognized. \item[enums] Enum constructs are changed into enumeration types. Bear in mind that, in C, enumeration types can have values assigned to them. Free Pascal also allows this to a certain degree. If you know that values are assigned to enums, it is best to use the \var{-e} option to change the enumerations to a series of integer constants. \item[unions] Unions are changed to variant records. \item[structs] Structs are changed to Pascal records, with C packing. \end{description} \section{h2paspp - preprocessor for h2pas} \var{h2paspp} can be used as a simple preprocessor for \file{h2pas}. It removes some of the constructs that h2pas has difficulties with. \file{h2paspp} reads one or more C header files and preprocesses them, writing the result to files with the same name as the originals as it goes along. It does not accept all preprocesser tokens of C, but takes care of the following preprocessor directives: \begin{description} \item [\#define symbol] Defines the new symbol \var{symbol}. Note that macros are not supported. \item [\#if symbol] The text following this directive is included if \var{symbol} is defined. \item [\#ifdef symbol] The text following this directive is included if \var{symbol} is defined. \item [\#ifndef symbol] The text following this directive is included if \var{symbol} is not defined. \item [\#include filename] Include directives are removed, unless the \var{-I} option was given, in which case the include file is included and written to the output file. \item[\#undef symbol] The symbol \var{symbol} is undefined. \end{description} \subsection{Usage} \file{h2paspp} accepts one or more filenames and preprocesses them. It will read the input, and write the output to a file with the same name unless the \var{-o} option is given, in which case the file is written to the specified file. Note that only one output filename can be given. \subsection{Options} \file{h2paspp} has a small number of options to control its behaviour: \begin{description} \item[-dsymbol] Define the symbol \var{symbol} before processing is started. \item[-h] Emit a small helptext. \item[-I] Include include files instead of dropping the include statement. \item[-ooutfile] If this option is given, the output will be written to a file named \file{outfile}. Note that only one output file can be given. \end{description} \section{ppudump program} \file{ppudump} is a program which shows the contents of a \fpc unit. It is distributed with the compiler. You can just issue the following command \begin{verbatim} ppudump [options] foo.ppu \end{verbatim} to display the contents of the \file{foo.ppu} unit. You can specify multiple files on the command line. The options can be used to change the verbosity of the display. By default, all available information is displayed. You can set the verbosity level using the \var{-Vxxx} option. Here, \var{xxx} is a combination of the following letters: \begin{description} \item [h:\ ] Show header info. \item [i:\ ] Show interface information. \item [m:\ ] Show implementation information. \item [d:\ ] Show only (interface) definitions. \item [s:\ ] Show only (interface) symbols. \item [b:\ ] Show browser info. \item [a:\ ] Show everything (default if no -V option is present). \end{description} \section{ppumove program} \label{se:ppumove} \file{ppumove} is a program to make shared or static libraries from multiple units. It can be compared with the \file{tpumove} program that comes with Turbo Pascal. It is distributed in binary form along with the compiler. Its usage is very simple: \begin{verbatim} ppumove [options] unit1.ppu unit2.ppu ... unitn.ppu \end{verbatim} where \var{options} is a combination of: \begin{description} \item[-b:\ ] Generate a batch file that will contain the external linking and archiving commands that must be executed. The name of this batch file is \file{pmove.sh} on \linux (and Unix like OSes), and \file{pmove.bat} on \windows and \dos. \item[-d xxx:\ ] Set the directory in which to place the output files to \file{xxx}. \item[-e xxx:\ ] Set the extension of the moved unit files to \file{xxx}. By default, this is \file{.ppl}. You don't have to specify the dot. \item[-o xxx:\ ] Set the name of the output file, i.e. the name of the file containing all the units. This parameter is mandatory when you use multiple files. On \linux, \file{ppumove} will prepend this name with \file{lib} if it isn't already there, and will add an extension appropriate to the type of library. \item [-q:\ ] Operate silently. \item [-s:\ ] Make a static library instead of a dynamic one; By default a dynamic library is made on \linux. \item [-w:\ ] Tell \file{ppumove} that it is working under \windowsnt. This will change the names of the linker and archiving program to \file{ldw} and \file{arw}, respectively. \item[-h or -?:\ ] Display a short help. \end{description} The action of the \file{ppumove} program is as follows: It takes each of the unit files, and modifies it so that the compiler will know that it should look for the unit code in the library. The new unit files will have an extension \file{.ppu}; this can be changed with the \var{-e} option. It will then put together all the object files of the units into one library, static or dynamic, depending on the presence of the \var{-s} option. The name of this library must be set with the \var{-o} option. If needed, the prefix \file{lib} will be prepended under \linux. The extension will be set to \file{.a} for static libraries, for shared libraries, the extensions are \var{.so} on linux, and \var{.dll} under \windowsnt and \ostwo. As an example, the following command \begin{verbatim} ./ppumove -o both -e ppl ppu.ppu timer.ppu \end{verbatim} will generate the following output under \linux{}: \begin{verbatim} PPU-Mover Version 2.1.1 Copyright (c) 1998-2007 by the Free Pascal Development Team Processing ppu.ppu... Done. Processing timer.ppu... Done. Linking timer.o ppu.o Done. \end{verbatim} And it will produce the following files: \begin{enumerate} \item \file{libboth.so} : The shared library containing the code from \file{ppu.o} and \file{timer.o}. Under \windowsnt, this file would be called \file{both.dll}. \item \file{timer.ppl} : The unit file that tells the \fpc compiler to look for the timer code in the library. \item \file{ppu.ppl} : The unit file that tells the \fpc compiler to look for the ppu code in the library. \end{enumerate} You could then use or distribute the files \file{libboth.so}, \file{timer.ppl} and \file{ppu.ppl}. \section{ptop - Pascal source beautifier} \subsection{ptop program} % This section was supplied by Marco Van de voort, for which my thanks. % I did some cleaning, and added the subsubsection with help on on the % object. MVC. \file{ptop} is a source beautifier written by Peter Grogono based on the ancient pretty-printer by Ledgard, Hueras, and Singer, modernized by the \fpc team (objects, streams, configurability etc). This configurability, and the thorough bottom-up design are the advantages of this program over the diverse Turbo Pascal source beautifiers on e.g. SIMTEL. The program is quite simple to operate: ptop "[-v] [-i indent] [-b bufsize ][-c \file{optsfile}] \file{infile} \file{outfile}" The \file{infile} parameter is the Pascal file to be processed, and will be written to \file{outfile}, overwriting an existing \file{outfile} if it exists. Some options modify the behaviour of ptop: \begin{description} \item[-h] Write an overview of the possible parameters and command line syntax. \item[-c \file{ptop.cfg}] Read some configuration data from configuration file instead of using the internal defaults then. A config file is not required, the program can operate without one. See also -g. \item[-i ident] Set the number of indent spaces used for BEGIN END; and other blocks. \item[-b bufsize] Set the streaming buffersize to bufsize. The default is 255; 0 is considered non-valid and ignored. \item[-v] Be verbose. Currently only outputs the number of lines read/written and some error messages. \item[-g \file{ptop.cfg}] Write \file{ptop} configuration defaults to the file "ptop.cfg". The contents of this file can be changed to your liking, and it can be used with the -c option. \end{description} \subsection{The ptop configuration file} Creating and distributing a configuration file for ptop is not necessary, unless you want to modify the standard behaviour of \file{ptop}. The configuration file is never preloaded, so if you want to use it you should always specify it with a \var{-c ptop.cfg} parameter. The structure of a ptop configuration file is a simple building block repeated several (20-30) times, for each Pascal keyword known to the \file{ptop} program. (See the default configuration file or \file{ptopu.pp} source to find out which keywords are known). The basic building block of the configuration file consists of one or two lines, describing how \file{ptop} should react on a certain keyword. First comes a line without square brackets with the following format: keyword=option1,option2,option3,... If one of the options is "dindonkey" (see further below), a second line - with square brackets - is needed: [keyword]=otherkeyword1,otherkeyword2,otherkeyword3,... As you can see the block contains two types of identifiers: keywords (keyword and otherkeyword1..3 in above example) and options, (option1..3 above). \var{Keywords} are the built-in valid Pascal structure-identifiers like BEGIN, END, CASE, IF, THEN, ELSE, IMPLEMENTATION. The default configuration file lists most of these. Besides the real Pascal keywords, some other codewords are used for operators and comment expressions as in \seet{keywords}. \begin{FPCltable}{lll}{Keywords for operators}{keywords} Name of codeword & Operator \\ \hline casevar & : in a case label ( unequal 'colon') \\ becomes & := \\ delphicomment & // \\ opencomment & \{ or (* \\ closecomment & \} or *) \\ semicolon & ; \\ colon & : \\ equals & = \\ openparen & [ \\ closeparen & ] \\ period & . \\ \end{FPCltable} The \textbf{options} codewords define actions to be taken when the keyword before the equal sign is found, as listed in \seet{ptopoptions}. \begin{FPCltable}{lll}{Possible options}{ptopoptions} Option & does what \\ \hline crsupp & Suppress CR before the keyword.\\ crbefore & Force CR before keyword.\\ & (do not use with crsupp.)\\ blinbefore & Blank line before keyword.\\ dindonkey & De-indent on associated keywords.\\ & (see below)\\ dindent & Deindent (always)\\ spbef & Space before\\ spaft & Space after\\ gobsym & Print symbols which follow a\\ & keyword but which do not\\ & affect layout. prints until\\ & terminators occur.\\ & (terminators are hard-coded in pptop,\\ & still needs changing)\\ inbytab & Indent by tab.\\ crafter & Force CR after keyword.\\ upper & Prints keyword all uppercase\\ lower & Prints keyword all lowercase\\ capital & Capitalizes keyword: 1st letter\\ & uppercase, rest lowercase.\\ \end{FPCltable} The option "dindonkey" given in table \seet{ptopoptions} requires some further explanation. "dindonkey" is a contraction of "DeINDent ON associated KEYword". When it is present as an option in the first line, then a second, square-bracketed, line is required. A de-indent will be performed when any of the other keywords listed in the second line are encountered in the source. Example: The lines \begin{verbatim} else=crbefore,dindonkey,inbytab,upper [else]=if,then,else \end{verbatim} mean the following: \begin{itemize} \item The keyword this block is about is \textbf{else} because it's on the LEFT side of both equal signs. \item The option \var{crbefore} signals not to allow other code (so just spaces) before the ELSE keyword on the same line. \item The option \var{dindonkey} de-indents if the parser finds any of the keywords in the square brackets line (if,then,else). \item The option \var{inbytab} means indent by a tab. \item The option \var{upper} uppercase the keyword (else or Else becomes ELSE) \end{itemize} Try to play with the configfile step by step until you find the effect you desire. The configurability and possibilities of ptop are quite large. E.g. I like all keywords uppercased instead of capitalized, so I replaced all capital keywords in the default file by upper. \file{ptop} is still development software. So it is wise to visually check the generated source and try to compile it, to see if \file{ptop} hasn't introduced any errors. \subsection{ptopu unit} The source of the \file{PtoP} program is conveniently split in two files: one is a unit containing an object that does the actual beautifying of the source, the other is a shell built around this object so it can be used from the command line. This design makes it possible to include the object in a program (e.g. an IDE) and use its features to format code. The object resides in the \file{PtoPU} unit, and is declared as follows \begin{verbatim} TPrettyPrinter=Object(TObject) Indent : Integer; { How many characters to indent ? } InS : PStream; OutS : PStream; DiagS : PStream; CfgS : PStream; Constructor Create; Function PrettyPrint : Boolean; end; \end{verbatim} Using this object is very simple. The procedure is as follows: \begin{enumerate} \item Create the object, using its constructor. \item Set the \var{InS} stream. This is an open stream, from which Pascal source will be read. This is a mandatory step. \item Set the \var{OutS} stream. This is an open stream, to which the beautified Pascal source will be written. This is a mandatory step. \item Set the \var{DiagS} stream. Any diagnostics will be written to this stream. This step is optional. If you don't set this, no diagnostics are written. \item Set the \var{CfgS} stream. A configuration is read from this stream. (see the previous section for more information about configuration). This step is optional. If you don't set this, a default configuration is used. \item Set the \var{Indent} variable. This is the number of spaces to use when indenting. Tab characters are not used in the program. This step is optional. The indent variable is initialized to 2. \item Call \var{PrettyPrint}. This will pretty-print the source in \var{InS} and write the result to \var{OutS}. The function returns \var{True} if no errors occurred, \var{False} otherwise. \end{enumerate} So, a minimal procedure would be: \begin{verbatim} Procedure CleanUpCode; var Ins,OutS : PBufStream; PPRinter : TPrettyPrinter; begin Ins:=New(PBufStream,Init('ugly.pp',StopenRead,TheBufSize)); OutS:=New(PBufStream,Init('beauty.pp',StCreate,TheBufSize)); PPrinter.Create; PPrinter.Ins:=Ins; PPrinter.outS:=OutS; PPrinter.PrettyPrint; end; \end{verbatim} Using memory streams allows very fast formatting of code, and is particularly suitable for editors. \section{rstconv program} The \file{rstconv} program converts the resource string files generated by the compiler (when you use resource string sections) to \file{.po} files that can be understood by the GNU \file{msgfmt} program. Its usage is very easy; it accepts the following options: \begin{description} \item[-i file] Use the specified file instead of stdin as input file. This option is optional. \item[-o file] Write output to the specified file. This option is required. \item[-f format] Specify the output format. At the moment, only one output format is supported: {\em po} for GNU gettext \file{.po} format. It is the default format. \end{description} As an example: \begin{verbatim} rstconv -i resdemo.rst -o resdemo.po \end{verbatim} will convert the \file{resdemo.rst} file to \file{resdemo.po}. More information on the \file{rstconv} utility can be found in the \progref, under the chapter about resource strings. \section{unitdiff program} \subsection{Synopsis} \file{unitdiff} shows the differences between two unit interface sections. \begin{verbatim} unitdiff [--disable-arguments] [--disable-private] [--disable-protected] [--help] [--lang=language] [--list] [--output=filename] [--sparse] file1 file2 \end{verbatim} \subsection{Description and usage} \file{Unitdiff} scans one or two Free Pascal unit source files and either lists all available identifiers, or describes the differences in identifiers between the two units. You can invoke \file{unitdiff} with an input filename as the only required argument. It will then simply list all available identifiers. The regular usage is to invoke \file{unitdiff} with two arguments: \begin{verbatim} unitdiff input1 input2 \end{verbatim} Invoked like this, it will show the difference in interface between the two units, or list the available identifiers in both units. The output of \file{unitdiff} will go to standard output by default. \subsection{Options} Most of the \file{unitdiff} options are not required. Defaults will be used in most cases. \begin{description} \item[--disable-arguments] Do not check the arguments of functions and procedures. The default action is to check them. \item[--disable-private] Do not check private fields or methods of classes. The default action is to check them. \item[--disable-protected] Do not check protected fields or methods of classes. The default action is to check them. \item[--help] Emit a short help text and exit. \item[--lang=language] Set the language for the output file. This will mainly set the strings used for the headers in various parts of the documentation files (by default they're in English). Currently, valid options are: \begin{itemize} \item \var{de}: German. \item \var{fr}: French. \item \var{nl}: Dutch. \end{itemize} \item[--list] Display just the list of available identifiers for the unit or units. If only one unit is specified on the command line, this option is automatically assumed. \item[--output=filename] Specify where the output should go. The default action is to send the output is sent to standard output (the screen). \item[--sparse] Turn on sparse mode. Output only the identifier names. Do not output types or type descriptions. By default, type descriptions are also written. \end{description} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Supplied units %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Units that come with Free Pascal} \label{ch:Units} Here we list the units that come with the \fpc distribution. Since there is a difference in the supplied units per operating system, we first describe the generic ones, then describe those which are operating system specific. % % Common units % \section{Standard units} The following units are standard and are meant to be ported to all platforms supported by \fpc. A brief description of each unit is also given. \begin{description} \item[charset] A unit to provide mapping of character sets. \item[cmem] Using this unit replaces the Free Pascal memory manager with the memory manager of the C library. \item[crt] This unit is similar to the unit of the same name of Turbo Pascal. It implements writing to the console in color, moving the text cursor around and reading from the keyboard. \item[dos] This unit provides basic routines for accessing the operating system. This includes file searching, environment variables access, getting the operating system version, getting and setting the system time. It is to note that some of these routines are duplicated in functionality in the \var{sysutils} unit. \item[dynlibs] Provides cross-platform access to loading dynamical libraries. %\item[errors] returns \item[getopts] This unit gives you the \gnu \var{getopts} command line arguments handling mechanism. It also supports long options. \item[graph] \emph{This unit is deprecated}. This unit provides basic graphics handling, with routines to draw lines on the screen, display text etc. It provides the same functions as the Turbo Pascal unit. \item[heaptrc] a unit which debugs the heap usage. When the program exits, it outputs a summary of the used memory, and dumps a summary of unreleased memory blocks (if any). \item[keyboard] provides basic keyboard handling routines in a platform independent way, and supports writing custom drivers. \item[macpas] This unit implements several functions available only in MACPAS mode. This unit should not be included; it's automatically included when the MACPAS mode is used. \item[math] This unit contains common mathematical routines (trigonometric functions, logarithms, etc.) as well as more complex ones (summations of arrays, normalization functions, etc.). \item[matrix] A unit providing matrix manipulation routines. \item[mmx] This unit provides support for \var{mmx} extensions in your code. \item[mouse] Provides basic mouse handling routines in a platform independent way, and supports writing custom drivers. \item [objects] This unit provides the base object for standard Turbo Pascal objects. It also implements File and Memory stream objects, as well as sorted and non-sorted collections, and string streams. \item[objpas] Is used for Delphi compatibility. You should never load this unit explicitly; it is automatically loaded if you request Delphi mode. \item[printer] This unit provides all you need for rudimentary access to the printer using standard I/O routines. \item[sockets] This gives the programmer access to sockets and TCP/IP programming. \item[strings] This unit provides basic string handling routines for the \var{pchar} type, comparable to similar routines in standard \var{C} libraries. \item[system] This unit is available for all supported platforms. It includes among others, basic file I/O routines, memory management routines, all compiler helper routines, and directory services routines. \item[strutils] Offers a lot of extended string handling routines. \item[dateutils] Offers a lot of extended date/time handling routines for almost any date and time math. \item[sysutils] Is an alternative implementation of the sysutils unit of Delphi. It includes file I/O access routines which takes care of file locking, date and string handling routines, file search, date and string conversion routines. \item[typinfo] Provides functions to access runtime Type Information, just like Delphi. \item[variants] Provides basic variant handling. \item[video] Provides basic screen handling in a platform independent way, and supports writing custom drivers. \end{description} % % Under DOS % \section{Under DOS} \begin{description} \item [emu387] This unit provides support for the coprocessor emulator. \item [go32] This unit provides access to capabilities of the \var{GO32} \dos extender. \item[ports] This implements the various \var{port[]} constructs for low-level I/O. \end{description} % % Under Windows % \section{Under Windows} \begin{description} \item[wincrt] This implements a console in a standard GUI window, contrary to the \var{crt} unit which is for the Windows console only. \item[Windows] This unit provides access to all Win32 API calls. Effort has been taken to make sure that it is compatible to the Delphi version of this unit, so code for Delphi is easily ported to \fpc. \item[opengl] Provides access to the low-level opengl functions in \windows. \item[winmouse] Provides access to the mouse in \windows. \item[ole2] Provides access to the OLE capabilities of \windows. \item[winsock] Provides access to the \windows sockets API Winsock. \item[Jedi windows header translations] The units containing the Jedi translations of the Windows API headers is also distributed with Free Pascal. The names of these units start with \file{jw}, followed by the name of the particular API. \end{description} % % Under Linux % \section{Under Linux and BSD-like platforms} \begin{description} \item[baseunix] Basic Unix operations, basically a subset of the POSIX specification. Using this unit should ensure portability across most unix systems. \item[clocale] This unit initializes the internationalization settings in the \file{sysutils} unit with settings obtained through the C library. \item[cthreads] This unit should be specified as the first or second unit in the uses clause of your program: it will use the Posix threads implementation to enable threads in your FPC program. \item[cwstring] If widestring routines are used, then this unit should be inserted as one of the first units in the uses clause of your program: it will initialize the widestring manager in the system unit with routines that use C library functions to handle Widestring conversions and other widestring operations. \item[errors] Returns a string describing an operating system error code. \item[Libc] This is the interface to GLibc on a linux I386 system. It will {\em not} work for other platforms, and is in general provided for Kylix compatibility. \item[oldlinux] \emph{This unit is deprecated}. This unit provides access to the \linux operating system. It provides most file and I/O handling routines that you may need. It implements most of the standard \var{C} library constructs that you will find on a Unix system. It is recommended, however, that you use the \file{baseunix}, \file{unixtype} and \file{unix} units. They are more portable. \item[ports] This implements the various \var{port[]} constructs. These are provided for compatibility only, and it is not recommended to use them extensively. Programs using this construct must be run as root or setuid root, and are a serious security risk on your system. \item[termio] Terminal control routines, which are compatible to the C library routines. \item[unix] Extended Unix operations. \item[unixtype] All types used commonly on Unix platforms. \end{description} \section{Under OS/2} \begin{description} \item[doscalls] Interface to \file{doscalls.dll}. \item[dive] Interface to \file{dive.dll} \item[emx] Provides access to the EMX extender. \item[pm*] Interface units for the Presentation Manager (PM) functions (GUI). \item[viocalls] Interface to \file{viocalls.dll} screen handling library. \item[moucalls] Interface to \file{moucalls.dll} mouse handling library. \item[kbdcalls] Interface to \file{kbdcalls.dll} keyboard handling library. \item[moncalls] Interface to \file{moncalls.dll} monitoring handling library. \item[winsock] Provides access to the (emulated) \windows sockets API Winsock. \item[ports] This implements the various \var{port[]} constructs for low-level I/O. \end{description} \section{Unit availability} Standard unit availability for each of the supported platforms is given in the FAQ / Knowledge base. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Debugging %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Debugging your programs} \fpc supports debug information for the \gnu debugger \var{gdb}, or its derivatives \file{Insight} on win32 or \file{ddd} on \linux. It can write 2 kinds of debug information: \begin{description} \item[stabs] The old debug information format. \item[dwarf] The new debug information format. \end{description} Both are understood by GDB. This chapter briefly describes how to use this feature. It doesn't attempt to describe completely the \gnu debugger, however. For more information on the workings of the \gnu debugger, see the \var{GDB} User Manual. \fpc also suports \var{gprof}, the \gnu profiler. See section \ref{se:gprof} for more information on profiling. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Compiling your program with debugger support \section{Compiling your program with debugger support} First of all, you must be sure that the compiler is compiled with debugging support. Unfortunately, there is no way to check this at run time, except by trying to compile a program with debugging support. To compile a program with debugging support, just specify the \var{-g} option on the command line, as follows: \begin{verbatim} fpc -g hello.pp \end{verbatim} This will incorporate debugging information in the executable generated from your program source. You will notice that the size of the executable increases substantially because of this\footnote{A good reason not to include debug information in an executable you plan to distribute.}. Note that the above will only incorporate debug information {\em for the code that has been generated} when compiling \file{hello.pp}. This means that if you used some units (the system unit, for instance) which were not compiled with debugging support, no debugging support will be available for the code in these units. There are 2 solutions for this problem. \begin{enumerate} \item Recompile all units manually with the \var{-g} option. \item Specify the 'build' option (\var{-B}) when compiling with debugging support. This will recompile all units, and insert debugging information in each of the units. \end{enumerate} The second option may have undesirable side effects. It may be that some units aren't found, or compile incorrectly due to missing conditionals, etc. If all went well, the executable now contains the necessary information with which you can debug it using \gnu \var{gdb}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Using gdb \section{Using \var{gdb} to debug your program} \label{se:usinggdb} To use gdb to debug your program, you can start the debugger, and give it as an option the {\em full} name of your program: \begin{verbatim} gdb hello \end{verbatim} Or, under \dos : \begin{verbatim} gdb hello.exe \end{verbatim} This starts the debugger, and the debugger immediately loads your program into memory, but it does not run the program yet. Instead, you are presented with the following (more or less) message, followed by the \var{gdb} prompt \var{'(gdb)'}: \begin{verbatim} GNU gdb 6.6.50.20070726-cvs Copyright (C) 2007 Free Software Foundation, Inc. GDB is free software, covered by the GNU General Public License, and you are welcome to change it and/or distribute copies of it under certain conditions. Type "show copying" to see the conditions. There is absolutely no warranty for GDB. Type "show warranty" for details. This GDB was configured as "x86_64-suse-linux". (gdb) \end{verbatim} The actual prompt will vary depending on your operating system and installed version of gdb, of course. To start the program you can use the \var{run} command. You can optionally specify command line parameters, which will then be fed to your program, for example: \begin{verbatim} (gdb) run -option -anotheroption needed_argument \end{verbatim} If your program runs without problems, \var{gdb} will inform you of this, and return the exit code of your program. If the exit code was zero, then the message \var{'Program exited normally'} is displayed. If something went wrong (a segmentation fault or such), \var{gdb} will stop the execution of your program, and inform you of this with an appropriate message. You can then use the other \var{gdb} commands to see what happened. Alternatively, you can instruct \var{gdb} to stop at a certain point in your program, with the \var{break} command. Here is a short list of \var{gdb} commands, which you are likely to need when debugging your program: \begin{description} \item [quit\ ] Exit the debugger. \item [kill\ ] Stop a running program. \item [help\ ] Give help on all \var{gdb} commands. \item [file\ ] Load a new program into the debugger. \item [directory\ ] Add a new directory to the search path for source files.\\ \begin{remark} My copy of gdb needs '.' to be added explicitly to the search path, otherwise it doesn't find the sources. \end{remark} \item [list\ ] List the program sources in chunks of 10 lines. As an option you can specify a line number or function name. \item [break\ ] Set a breakpoint at a specified line or function. \item [awatch\ ] Set a watch-point for an expression. A watch-point stops execution of your program whenever the value of an expression is either read or written. \end{description} In appendix {\ref{ch:GdbIniFile}} a sample init file for \var{gdb} is presented. It produces good results when debugging \fpc programs. For more information, refer to the \var{gdb} User Manual, or use the \var{'help'} function in \var{gdb}. The text mode IDE and Lazarus both use GDB as a debugging backend. It may be preferable to use that, as they hide much of the details of the debugger in an easy-to-use user interface. \section{Caveats when debugging with \var{gdb}} There are some peculiarities of \fpc which you should be aware of when using \var{gdb}. We list the main ones here: \begin{enumerate} \item \fpc generates information for GDB in uppercase letters. This is a consequence of the fact that Pascal is a case insensitive language. So, when referring to a variable or function, you need to make its name all uppercase. As an example, if you want to watch the value of a loop variable \var{count}, you should type \begin{verbatim} watch COUNT \end{verbatim} Or if you want to stop when a certain function (e.g \var{MyFunction}) is called, type \begin{verbatim} break MYFUNCTION \end{verbatim} \item \var{gdb} does not know sets. \item \var{gdb} doesn't know strings. Strings are represented in \var{gdb} as records with a length field and an array of char containing the string. You can also use the following user function to print strings: \begin{verbatim} define pst set $pos=&$arg0 set $strlen = {byte}$pos print {char}&$arg0.st@($strlen+1) end document pst Print out a Pascal string end \end{verbatim} If you insert it in your \file{gdb.ini} file, you can look at a string with this function. There is a sample \file{gdb.ini} in appendix \ref{ch:GdbIniFile}. \item Objects are difficult to handle, mainly because \var{gdb} is oriented towards C and C++. The workaround implemented in \fpc is that object methods are represented as functions, with an extra parameter \var{this} (all lowercase!). The name of this function is a concatenation of the object type and the function name, separated by two underscore characters. For example, the method \var{TPoint.Draw} would be converted to \var{TPOINT\_\_DRAW}, and you could stop at it by using: \begin{verbatim} break TPOINT__DRAW \end{verbatim} \item Global overloaded functions confuse \var{gdb} because they have the same name. Thus you cannot set a breakpoint at an overloaded function, unless you know its line number, in which case you can set a breakpoint at the starting line number of the function. \end{enumerate} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Using gprof \section{Support for \var{gprof}, the \gnu profiler} \label{se:gprof} You can compile your programs with profiling support. For this, you just have to use the compiler switch \var{-pg}. The compiler will insert the necessary stuff for profiling. When you have done this, you can run your program as you would normally run it: \begin{verbatim} yourexe \end{verbatim} Where \file{yourexe} is the name of your executable. When your program finishes, a file called gmon.out is generated. Then you can start the profiler to see the output. You can benefit from redirecting the output to a file, because it could be quite a lot: \begin{verbatim} gprof yourexe > profile.log \end{verbatim} Hint: you can use the \var{--flat} option to reduce the amount of output of gprof. It will then only output the information about the timings. For more information on the \gnu profiler \var{gprof}, see its manual. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Checking the heap \section{Detecting heap memory leaks} \label{se:heaptrc} \fpc has a built in mechanism to detect memory leaks. There is a plug-in unit for the memory manager that analyses the memory allocation/deallocation and prints a memory usage report after the program exits. The unit that does this is called \file{heaptrc}. If you want to use it, you should include it as the first unit in your uses clause. Alternatively, you can supply the \var{-gh} switch to the compiler, and it will include the unit automatically for you. After the program exits, you will get a report looking like this: \begin{verbatim} Marked memory at 0040FA50 invalid Wrong size : 128 allocated 64 freed 0x00408708 0x0040CB49 0x0040C481 Call trace for block 0x0040FA50 size 128 0x0040CB3D 0x0040C481 \end{verbatim} The output of the heaptrc unit is customizable by setting some variables. Output can also be customized using environment variables. You can find more information about the usage of the \file{heaptrc} unit in the \unitsref. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Verbose Run-time errors. \section{Line numbers in run-time error backtraces} \label{se:lineinfo} Normally, when a run-time error occurs, you are presented with a list of addresses that represent the call stack backtrace, i.e. the addresses of all procedures that were invoked when the run-time error occurred. This list is not very informative, so there exists a unit that generates the file names and line numbers of the called procedures using the addresses of the stack backtrace. This unit is called lineinfo. You can use this unit by giving the \var{-gl} option to the compiler. The unit will be automatically included. It is also possible to use the unit explicitly in your \var{uses} clause, but you must make sure that you compile your program with debug info. Here is an example program: \begin{verbatim} program testline; procedure generateerror255; begin runerror(255); end; procedure generateanerror; begin generateerror255; end; begin generateanerror; end. \end{verbatim} When compiled with \var{-gl}, the following output is generated: \begin{verbatim} Runtime error 255 at 0x0040BDE5 0x0040BDE5 GENERATEERROR255, line 6 of testline.pp 0x0040BDF0 GENERATEANERROR, line 13 of testline.pp 0x0040BE0C main, line 17 of testline.pp 0x0040B7B1 \end{verbatim} This is more understandable than the normal message. Make sure that all units you use are compiled with debug info, because if they are not, no line number and filename can be found. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Combining heaptrc and lineinfo \section{Combining \file{heaptrc} and \file{lineinfo}} If you combine the lineinfo and the heaptrc information, then the output of the \file{heaptrc} unit will contain the names of the files and line numbers of the procedures that occur in the stack backtrace. In such a case, the output will look something like this: \begin{verbatim} Marked memory at 00410DA0 invalid Wrong size : 128 allocated 64 freed 0x004094B8 0x0040D8F9 main, line 25 of heapex.pp 0x0040D231 Call trace for block 0x00410DA0 size 128 0x0040D8ED main, line 23 of heapex.pp 0x0040D231 \end{verbatim} If lines without filename / line number occur, this means there is a unit which has no debug info included (in the above case, the getmem call itself). %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% APPENDICES. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \appendix %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % APPENDIX A. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Alphabetical listing of command line options} \label{ch:commandlineoptions} The following is an alphabetical listing of all command line options, as generated by the compiler: \input{comphelp.inc} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % APPENDIX B. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Alphabetical list of reserved words} \label{ch:reserved} \begin{multicols}{3} \input{reserved.tex} \end{multicols} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % APPENDIX C. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Compiler messages} \label{ch:ErrorMessages} This appendix is meant to list all the compiler messages. The list of messages is generated from he compiler source itself, and should be fairly complete. At this point, only assembler errors are not in the list. For an explanation of how to control the messages, \sees{feedbackoptions}. % Message file is generated with msg2inc. \input {messages.inc} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Assembler reader errors \section{Assembler reader errors.} This section lists the errors that are generated by the inline assembler reader. They are {\em not} the messages of the assembler itself. % General assembler errors. \subsection{General assembler errors} \begin{description} \item [Divide by zero in asm evaluator] This fatal error is reported when a constant assembler expression performs a division by zero. \item [Evaluator stack overflow, Evaluator stack underflow] These fatal error is reported when a constant assembler expression is too big to be evaluated by the constant parser. Try reducing the number of terms. \item [Invalid numeric format in asm evaluator] This fatal error is reported when a non-numeric value is detected by the constant parser. Normally this error should never occur. \item [Invalid Operator in asm evaluator] This fatal error is reported when a mathematical operator is detected by the constant parser. Normally this error should never occur. \item [Unknown error in asm evaluator] This fatal error is reported when an internal error is detected by the constant parser. Normally this error should never occur. \item [Invalid numeric value] This warning is emitted when a conversion from octal, binary or hexadecimal to decimal is outside of the supported range. \item [Escape sequence ignored] This error is emitted when a non ANSI C escape sequence is detected in a C string. \item [Asm syntax error - Prefix not found] This occurs when trying to use a non-valid prefix instruction. \item [Asm syntax error - Trying to add more than one prefix] This occurs when you try to add more than one prefix instruction. \item [Asm syntax error - Opcode not found] You have tried to use an unsupported or unknown opcode. \item [Constant value out of bounds] This error is reported when the constant parser determines that the value you are using is out of bounds, either with the opcode or with the constant declaration used. \item [Non-label pattern contains @] This only applied to the m68k and Intel styled assembler. This is reported when you try to use a non-label identifier with an '@' prefix. \item [Internal error in Findtype()] \item [Internal Error in ConcatOpcode()] \item [Internal Errror converting binary] \item [Internal Errror converting hexadecimal] \item [Internal Errror converting octal] \item [Internal Error in BuildScaling()] \item [Internal Error in BuildConstant()] \item [internal error in BuildReference()] \item [internal error in HandleExtend()] \item [Internal error in ConcatLabeledInstr()] \label{InternalError} These errors should never occur. If they do then you have found a new bug in the assembler parsers. Please contact one of the developers. \item [Opcode not in table, operands not checked] This warning only occurs when compiling the system unit, or related files. No checking is performed on the operands of the opcodes. \item [@CODE and @DATA not supported] This Turbo Pascal construct is not supported. \item [SEG and OFFSET not supported] This Turbo Pascal construct is not supported. \item [Modulo not supported] Modulo constant operation is not supported. \item [Floating point binary representation ignored] \item [Floating point hexadecimal representation ignored] \item [Floating point octal representation ignored] These warnings occur when a floating point constant is declared in a base other than decimal. No conversion can be done on these formats. You should use a decimal representation instead. \item [Identifier supposed external] This warning occurs when a symbol is not found in the symbol table. It is therefore considered external. \item [Functions with void return value can't return any value in asm code] Only routines with a return value can have a return value set. \item [Error in binary constant] \item [Error in octal constant] \item [Error in hexadecimal constant] \item [Error in integer constant] \label{ErrorConst} These errors are reported when you tried using a constant expression that is invalid or whose value is out of range. \item [Invalid labeled opcode] \item [Asm syntax error - error in reference] \item [Invalid Opcode] \item [Invalid combination of opcode and operands] \item [Invalid size in reference] \item [Invalid middle sized operand] \item [Invalid three operand opcode] \item [Assembler syntax error] \item [Invalid operand type] You tried using an invalid combination of opcode and operands. Check the syntax and if you are sure it is correct, please contact one of the developers. \item [Unknown identifier] The identifier you are trying to access does not exist, or is not within the current scope. \item [Trying to define an index register more than once] \item [Trying to define a segment register twice] \item [Trying to define a base register twice] You are trying to define an index/segment register more than once. \item [Invalid field specifier] The record or object field you are trying to access does not exist, or is incorrect. \item [Invalid scaling factor] \item [Invalid scaling value] \item [Scaling value only allowed with index] Allowed scaling values are 1,2,4 or 8. \item [Cannot use SELF outside a method] You are trying to access the SELF identifier for objects outside a method. \item [Invalid combination of prefix and opcode] This opcode cannot be prefixed by this instruction. \item [Invalid combination of override and opcode] This opcode cannot be overriden by this combination. \item [Too many operands on line] At most three operand instructions exist on the m68k, and i386, you are probably trying to use an invalid syntax for this opcode. \item [Duplicate local symbol] You are trying to redefine a local symbol, such as a local label. \item [Unknown label identifer] \item [Undefined local symbol] \item [local symbol not found inside asm statement] This label does not seem to have been defined in the current scope. \item [Assemble node syntax error] \item [Not a directive or local symbol] The assembler statement is invalid, or you are not using a recognized directive. \end{description} % I386 specific errors \subsection{I386 specific errors} \begin{description} \item [repeat prefix and a segment override on \var{<=} i386 ...] A problem with interrupts and a prefix instruction may occur and may cause false results on 386 and earlier computers. \item [Fwait can cause emulation problems with emu387] This warning is reported when using the FWAIT instruction. It can cause emulation problems on systems which use the em387.dxe emulator. \item [You need GNU as version >= 2.81 to compile this MMX code] MMX assembler code can only be compiled using GAS v2.8.1 or later. \item [NEAR ignored] \item [FAR ignored] \label{FarIgnored} \var{NEAR} and \var{FAR} are ignored in the Intel assemblers, but are still accepted for compatiblity with the 16-bit code model. \item [Invalid size for MOVSX/MOVZX] \item [16-bit base in 32-bit segment] \item [16-bit index in 32-bit segment] 16-bit addressing is not supported. You must use 32-bit addressing. \item [Constant reference not allowed] It is not allowed to try to address a constant memory address in protected mode. \item [Segment overrides not supported] Intel style (eg: rep ds stosb) segment overrides are not supported by the assembler parser. \item [{Expressions of the form [sreg:reg...] are currently not supported}] To access a memory operand in a different segment, you should use the sreg:[reg...] snytax instead of [sreg:reg...] \item [Size suffix and destination register do not match] In intel AT\&T syntax, you are using a register size which does not concord with the operand size specified. \item [Invalid assembler syntax. No ref with brackets] \item [ Trying to use a negative index register ] \item [ Local symbols not allowed as references ] \item [ Invalid operand in bracket expression ] \item [ Invalid symbol name: ] \item [ Invalid Reference syntax ] \item [ Invalid string as opcode operand: ] \item [ Null label references are not allowed ] \item [ Using a defined name as a local label ] \item [ Invalid constant symbol ] \item [ Invalid constant expression ] \item [ / at beginning of line not allowed ] \item [ NOR not supported ] \item [ Invalid floating point register name ] \item [ Invalid floating point constant: ] \item [ Asm syntax error - Should start with bracket ] \item [ Asm syntax error - register: ] \item [ Asm syntax error - in opcode operand ] \item [ Invalid String expression ] \item [ Constant expression out of bounds ] \item [ Invalid or missing opcode ] \item [ Invalid real constant expression ] \item [ Parenthesis are not allowed ] \item [ Invalid Reference ] \item [ Cannot use \_\_SELF outside a method ] \item [ Cannot use \_\_OLDEBP outside a nested procedure ] \item [ Invalid segment override expression ] \item [ Strings not allowed as constants ] \item [ Switching sections is not allowed in an assembler block ] \item [ Invalid global definition ] \item [ Line separator expected ] \item [ Invalid local common definition ] \item [ Invalid global common definition ] \item [ assembler code not returned to text ] \item [ invalid opcode size ] \item [ Invalid character: < ] \item [ Invalid character: > ] \item [ Unsupported opcode ] \item [ Invalid suffix for intel assembler ] \item [ Extended not supported in this mode ] \item [ Comp not supported in this mode ] \item [ Invalid Operand: ] \item [ Override operator not supported ] \end{description} % m68k specific errors \subsection{m68k specific errors.} \begin{description} \item [Increment and Decrement mode not allowed together] You are trying to use dec/inc mode together. \item [Invalid Register list in movem/fmovem] The register list is invalid. Normally a range of registers should be separated by - and individual registers should be separated by a slash. \item [Invalid Register list for opcode] \item [68020+ mode required to assemble] \end{description} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Runtime errors listing %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Run-time errors} Applications generated by \fpc might generate run-time errors when certain abnormal conditions are detected in the application. This appendix lists the possible run-time errors and gives information on why they might be produced. \begin{description} \item [1 Invalid function number] An invalid operating system call was attempted. \item [2 File not found] Reported when trying to erase, rename or open a non-existent file. \item [3 Path not found] Reported by the directory handling routines when a path does not exist or is invalid. Also reported when trying to access a non-existent file. \item [4 Too many open files] The maximum number of files currently opened by your process has been reached. Certain operating systems limit the number of files which can be opened concurrently, and this error can occur when this limit has been reached. \item [5 File access denied] Permission to access the file is denied. This error might be caused by one of several reasons: \begin{itemize} \item Trying to open for writing a file which is read-only, or which is actually a directory. \item File is currently locked or used by another process. \item Trying to create a new file, or directory while a file or directory of the same name already exists. \item Trying to read from a file which was opened in write-only mode. \item Trying to write from a file which was opened in read-only mode. \item Trying to remove a directory or file while it is not possible. \item No permission to access the file or directory. \end{itemize} \item [6 Invalid file handle] If this happens, the file variable you are using is trashed; it indicates that your memory is corrupted. \item [12 Invalid file access code] Reported when a reset or rewrite is called with an invalid \var{FileMode} value. \item [15 Invalid drive number] The number given to the \var{Getdir} or \var{ChDir} function specifies a non-existent disk. \item [16 Cannot remove current directory] Reported when trying to remove the currently active directory. \item [17 Cannot rename across drives] You cannot rename a file such that it would end up on another disk or partition. \item [100 Disk read error] An error occurred when reading from disk. Typically happens when you try to read past the end of a file. \item [101 Disk write error] Reported when the disk is full, and you're trying to write to it. \item [102 File not assigned] This is reported by \var{Reset}, \var{Rewrite}, \var{Append}, \var{Rename} and \var{Erase}, if you call them with an unassigned file as a parameter. \item [103 File not open] Reported by the following functions : \var{Close, Read, Write, Seek, EOf, FilePos, FileSize, Flush, BlockRead,} and \var{BlockWrite} if the file is not open. \item [104 File not open for input] Reported by \var{Read, BlockRead, Eof, Eoln, SeekEof} or \var{SeekEoln} if the file is not opened with \var{Reset}. \item [105 File not open for output] Reported by write if a text file isn't opened with \var{Rewrite}. \item [106 Invalid numeric format] Reported when a non-numeric value is read from a text file, and a numeric value was expected. \item [150 Disk is write-protected] (Critical error) \item [151 Bad drive request struct length] (Critical error) \item [152 Drive not ready] (Critical error) \item [154 CRC error in data] (Critical error) \item [156 Disk seek error] (Critical error) \item [157 Unknown media type] (Critical error) \item [158 Sector Not Found] (Critical error) \item [159 Printer out of paper] (Critical error) \item [160 Device write fault] (Critical error) \item [161 Device read fault] (Critical error) \item [162 Hardware failure] (Critical error) \item [200 Division by zero] The application attempted to divide a number by zero. \item [201 Range check error] If you compiled your program with range checking on, then you can get this error in the following cases: \begin{enumerate} \item An array was accessed with an index outside its declared range. \item Trying to assign a value to a variable outside its range (for instance an enumerated type). \end{enumerate} \item [202 Stack overflow error] The stack has grown beyond its maximum size (in which case the size of local variables should be reduced to avoid this error), or the stack has become corrupt. This error is only reported when stack checking is enabled. \item [203 Heap overflow error] The heap has grown beyond its boundaries. This is caused when trying to allocate memory explicitly with \var{New}, \var{GetMem} or \var{ReallocMem}, or when a class or object instance is created and no memory is left. Please note that, by default, \fpc provides a growing heap, i.e. the heap will try to allocate more memory if needed. However, if the heap has reached the maximum size allowed by the operating system or hardware, then you will get this error. \item [204 Invalid pointer operation] You will get this if you call \var{Dispose} or \var{Freemem} with an invalid pointer (notably, \var{Nil}). \item [205 Floating point overflow] You are trying to use or produce real numbers that are too large. \item [206 Floating point underflow] You are trying to use or produce real numbers that are too small. \item [207 Invalid floating point operation] Can occur if you try to calculate the square root or logarithm of a negative number. \item [210 Object not initialized] When compiled with range checking on, a program will report this error if you call a virtual method without having called its object's constructor. \item [211 Call to abstract method] Your program tried to execute an abstract virtual method. Abstract methods should be overridden, and the overriding method should be called. \item [212 Stream registration error] This occurs when an invalid type is registered in the objects unit. \item [213 Collection index out of range] You are trying to access a collection item with an invalid index (\var{objects} unit). \item [214 Collection overflow error] The collection has reached its maximal size, and you are trying to add another element (\var{objects} unit). \item[215 Arithmetic overflow error] This error is reported when the result of an arithmetic operation is outside of its supported range. Contrary to Turbo Pascal, this error is only reported for 32-bit or 64-bit arithmetic overflows. This is due to the fact that everything is converted to 32-bit or 64-bit before doing the actual arithmetic operation. \item [216 General Protection fault] The application tried to access invalid memory space. This can be caused by several problems: \begin{enumerate} \item Dereferencing a \var{nil} pointer. \item Trying to access memory which is out of bounds (for example, calling \var{move} with an invalid length). \end{enumerate} \item [217 Unhandled exception occurred] An exception occurred, and there was no exception handler present. The \var{sysutils} unit installs a default exception handler which catches all exceptions and exits gracefully. \item [219 Invalid typecast] Thrown when an invalid typecast is attempted on a class using the \var{as} operator. This error is also thrown when an object or class is typecast to an invalid class or object and a virtual method of that class or object is called. This last error is only detected if the \var{-CR} compiler option is used. \item[222 Variant dispatch error] No dispatch method to call from variant. \item[223 Variant array create] The variant array creation failed. Usually when there is not enough memory. \item[224 Variant is not an array] This error occurs when a variant array operation is attempted on a variant which is not an array. \item[225 Var Array Bounds check error] This error occurs when a variant array index is out of bounds. \item [227 Assertion failed error] An assertion failed, and no \var{AssertErrorProc} procedural variable was installed. \item [229 Safecall error check] This error occurs is a safecall check fails, and no handler routine is available. \item [231 Exception stack corrupted] This error occurs when the exception object is retrieved and none is available. \item [232 Threads not supported] Thread management relies on a separate driver on some operating systems (notably, Unixes). The unit with this driver needs to be specified on the uses clause of the program, preferably as the first unit (\file{cthreads} on unix). \end{description} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % GDB Configuration file \chapter{A sample \file{gdb.ini} file} \label{ch:GdbIniFile} Here you have a sample \file{gdb.ini} file listing, which gives better results when using \var{gdb}. Under \linux you should put this in a \file{.gdbinit} file in your home directory or the current directory. \begin{verbatim} set print demangle off set gnutarget auto set verbose on set complaints 1000 dir ./rtl/dosv2 set language c++ set print vtbl on set print object on set print sym on set print pretty on disp /i $eip define pst set $pos=&$arg0 set $strlen = {byte}$pos print {char}&$arg0.st@($strlen+1) end document pst Print out a Pascal string end \end{verbatim} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Options summary tables %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \input{options.tex} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Downloading sources. \chapter{Getting the latest sources or installers} \label{ch:sourcedownload} Free Pascal is under continuous development. From time to time, a new set of installers with what are considered stable sources are made: these are the releases. They can be downloaded from the Free Pascal website. The downloads usually contain the sources from which the release is made. If for some reason, a newer set of files is needed - for instance, because certain bugs that prevent a program from functioning correctly have been fixed, it is possible to download the latest source files and recompile them. Note that the latest sources may or may not compile: sometimes things get broken, and then the downloaded sources are useless. For the fixes branches (mentioned below) the sources should always compile, so it may be best to use these only. There are 3 ways to get the latest version. \section{Download via Subversion} All Free Pascal sources are in subversion, and can be downloaded anonymously from the Subversion server. With a suitable Subversion client, the following locations can be used: \begin{verbatim} http://svn.freepascal.org/svn/fpc/trunk/ \end{verbatim} This repository contains the latest sources of the compiler, RTL and packages. This is the active development branch. The documentation and all examples from the documentation are in the following repository \begin{verbatim} http://svn.freepascal.org/svn/fpcdocs/trunk/ \end{verbatim} All the files needed to make a release can be retrieved from \begin{verbatim} http://svn.freepascal.org/svn/fpcbuild/trunk/ \end{verbatim} This repository contains external links to the other 2 repositories, and contains all scripts, demos and other files needed to construct a new release of Free Pascal. Free Pascal maintains a fixes branch, which is used to create new releases after a major version change. The branches are located in \begin{verbatim} http://svn.freepascal.org/svn/fpc/branches/fpc_X_Y \end{verbatim} Where X and Y make up the major release number of Free Pascal. For instance, the fixes used to make the 2.6.x versions of Free Pascal are available in \begin{verbatim} http://svn.freepascal.org/svn/fpc/branches/fixes_2_6 \end{verbatim} The Subversion archive is mirrored on the server \begin{verbatim} svn2.freepascal.org \end{verbatim} \section{Downloading a source zip} Every day, a zip is made which contains the sources as they are on this day, they are available from the FTP site: \begin{verbatim} http://ftp.freepascal.org/develop.var \end{verbatim} This will lead to a download of the sources of the development branch: \begin{verbatim} ftp://ftp.freepascal.org/pub/fpc/snapshot/trunk/source/fpc.zip \end{verbatim} and also of the fixes branch: \begin{verbatim} ftp://ftp.freepascal.org/pub/fpc/snapshot/fixes/source/fpc.zip \end{verbatim} The creation of the zip files is an automated process, and so these files are created every day. \section{Downloading a snapshot} Some members of the Free Pascal team also maintain installable snapshots. These are installers, made with the sources of that day. Since the sources are not guaranteed to work, a snapshot of a certain day may not be available, or the person responsible for it didn't have the opportunity to make one: these snapshots may or may not be available. They can be downloaded from the same page as the daily source zip: \begin{verbatim} http://ftp.freepascal.org/develop.var \end{verbatim} The snapshots are made for the development branch as well as for the fixes branch. They are available from \begin{verbatim} ftp://ftp.freepascal.org/pub/fpc/snapshot/trunk/ \end{verbatim} and \begin{verbatim} ftp://ftp.freepascal.org/pub/fpc/snapshot/fixes/ \end{verbatim} respectively. The FTP site is mirrored, it may be faster to use a mirror. \end{document}