Free Pascal |
This is the user’s guide for Free Pascal . It describes the installation and use of the Free Pascal 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 Reference guide for these things. For a description of the possibilities and the inner workings of the compiler, see the Programmers guide . 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 README and FAQ files, distributed with the compiler. The README and FAQ files are, in case of conflict with this manual, authoritative.
Free Pascal is a 32- and 64-bit Pascal compiler. The current version (2.6) can compile code for the following processors:
The compiler and Run-Time Library are available for the following operating systems:
The complete list is at all times available on the Free Pascal website.
Free Pascal 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 Free Pascal . Users that prefer a graphical IDE can have a look at the Lazarus1 or MSEIDE2 projects.
Free Pascal consists of several parts :
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 Reference guide , and the available routines (units) are described in the RTL and FCL Unit reference guides.
If the documentation doesn’t give an answer to your questions, you can obtain more information on the Internet, at the following addresses:
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 michael@freepascal.org. .
Let’s get on with something useful.
The compiler needs at least one of the following processors:
Memory and disk requirements:
The dos distribution contains all the files you need to run the compiler and compile Pascal programs.
Under unix systems (such as linux ) you need to have the following programs installed :
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 mingw32 tools or the cygwin development tools. Links to both of these tools can be found on http://www.freePascal.org
While the Free Pascal 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:
ftp://hobbes.nmsu.edu/pub/os2/dev/emx/v0.9d
Mac OS X 10.1 or higher is required, and the developer tools or XCode should be installed.
The installation of Free Pascal is easy, but is platform-dependent. We discuss the process for each platform separately.
For Windows , there is a Windows installer, 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 .pp or .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.
First, you must get the latest distribution files of Free Pascal . 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 INSTALL.EXE. You must run this program to install the compiler.
The screen of the DOS or OS/2 installation program looks like figure ??.
The program allows you to select:
C:\PP).
In order to run Free Pascal from any directory on your system, you must extend
your path variable to contain the C:\PP\BIN directory.
Usually this is done in the AUTOEXEC.BAT file.
It should look something like this :
SET PATH=%PATH%;C:\PP\2.6\BIN\i386-DOS
for dos or
SET PATH=%PATH%;C:\PP\2.6\BIN\i386-OS2
for os/2 . (Again, assuming that you installed in the default location).
On os/2 , Free Pascal 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
C:\PP\DLL
directory. The name of this directory should be added to the LIBPATH directive in the config.sys file:
LIBPATH=XXX;C:\PP\DLL
Obviously, any existing directories in the LIBPATH directive (indicated by XXX in the above example) should be preserved.
For people who have an older CPU type, without math coprocessor (i387) it is necessary to install a coprocessor emulation, since Free Pascal uses the coprocessor to do all floating point operations.
The installation of the coprocessor emulation is handled by the installation program (INSTALL.EXE) under dos and Windows .
The linux distribution of Free Pascal comes in three forms:
If you use the .rpm format, installation is limited to
rpm -i fpc-X.Y.Z-N.ARCH.rpm
Where X.Y.Z is the version number of the .rpm file, and ARCH is one of the supported architectures (i386, x86_64 etc.).
If you use Debian, installation is limited to
dpkg -i fpc-XXX.deb
Here again, XXX is the version number of the .deb file.
You need root access to install these packages. The .tar file allows you to do an installation below your home directory if you don’t have root permissions.
When downloading the .tar file, or the separate files, installation is more interactive.
In case you downloaded the .tar file, you should first untar the file, in some directory where you have write permission, using the following command:
tar -xvf fpc.tar
We supposed here that you downloaded the 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 install.sh script, and the libraries (in libs.tar.gz).
To install Free Pascal , all that you need to do now is give the following command:
./install.sh
And then you must answer some questions. They’re very simple, they’re mainly concerned with 2 things :
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 root user, you can just accept all installation defaults. If you don’t run as 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 (fpc.cfg) for the Free Pascal compiler which reflects the settings that you chose. It will install this file in the /etc directory or in your home directory (with name .fpc.cfg) if you do not have write permission in the /etc directory. It will make a copy in the directory where you installed the libraries.
The compiler will first look for a file .fpc.cfg in your home directory before looking in the /etc directory.
On any platform, after installing the compiler you may wish to set some environment variables. The Free Pascal compiler recognizes the following variables :
PPC_EXEC_PATH contains the directory where support files for
the compiler can be found.
PPC_CONFIG_PATH specifies an alternate path to find the fpc.cfg.
PPC_ERROR_FILE specifies the path and name of the error-definition file.
FPCDIR specifies the root directory of the Free Pascal installation.
(e.g : C:\PP\BIN)
These locations are, however, set in the sample configuration file which is
built at the end of the installation process, except for the
PPC_CONFIG_PATH variable, which you must set if you didn’t install
things in the default places.
Also distributed in Free Pascal is a README file. It contains the latest instructions for installing Free Pascal , and should always be read first.
Furthermore, platform-specific information and common questions are addressed in the FAQ. It should be read before reporting any bug.
After the installation is completed and the optional environment variables are set as described above, your first program can be compiled.
Included in the Free Pascal 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
To compile a program (e.g demo\text\hello.pp), copy the program
to your current working directory, and simply type :
fpc hello
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:
fpc -Fuc:\pp\NNN\units\i386-go32v2\rtl hello
under dos , and under linux you could type
fpc -Fu/usr/lib/fpc/NNN/units/i386-linux/rtl hello
(replace NNN with the version number of Free Pascal that you are using).
This is, of course, assuming that you installed under C:\PP or
/usr/lib/fpc/NNN, respectively.
If you got no error messages, the compiler has generated an executable called hello.exe under dos , os/2 or Windows , or hello (no extension) under unix and most other operating systems.
To execute the program, simply type :
hello
or
./hello
on Unices (where the current directory usually is not in the PATH).
If all went well, you should see the following friendly greeting:
Hello world
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 Programmers guide .
The examples in this section suppose that you have an 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 ?? for more information on this.)
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.
Remark:
The use of slashes (/) and backslashes (\) 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 ).
The file that you specify on the command line, such as in
fpc foo.pp
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:
fpc subdir/foo.pp
will look for foo.pp in the subdirectory 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 , Windows NT , os/2 ) this is not the case.
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:
You can add a directory to the unit search path with the (-Fu, (see ??) ) option. Every occurrence of one of these options will 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:
/usr/local/lib/fpc/FPCVERSION or /usr/lib/fpc/FPCVERSIONwhichever is found first.
C:\FPC\2.6\units\i386-win32This is assuming the compiler was installed in the directory
C:\FPC\2.6
/usr/local/lib/fpc/2.6/units/i386-linux/or, when cross-compiling
/usr/local/lib/fpc/2.6/units/i386-win32/
The -Fu option accepts a single * wildcard, which will be replaced by all directories found on that location, but not the location itself. For example, given the directories
rtl/units/i386-linux fcl/units/i386-linux packages/base packages/extra
the command
fpc -Fu"*/units/i386-linux"
will have the same effect as
fpc -Furtl/units/i386-linux -Fufcl/units/i386-linux
since both the rtl and fcl directories contain further units/i386-linux subdirectories. The packages directory will not be added, since it doesn’t contain a units/i386-linux subdirectory.
The following command
fpc -Fu"units/i386-linux/*"
will match any directory below the units/i386-linux directory, but will not match the 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:
fpc -Fu"units/i386-linux" -Fu"units/i386-linux/*"
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 -vu option.
Note that unit file paths specified in a config file will be added at the end, while paths specified on the command-line are added at the beginning.
Imagine the following command-line:
fpc -n -Fu/home @cfg -Fu/usr foo.pp
Where the file cfg has the following contents:
-Fu/etc
This will result in the following search path
Using unit path: /home/ Using unit path: /usr/ Using unit path: /etc/ Using unit path: /data/FPC/installed/3.1.1/
Reverting the order of the files on the command-line :
fpc -n -Fu/usr @cfg -Fu/home foo.pp
Results in
Using unit path: /usr/ Using unit path: /home/ Using unit path: /etc/ Using unit path: /data/FPC/installed/3.1.1/
Moving the position of @cfg will not change the path:
fpc -n @cfg -Fu/home -Fu/usr foo.pp
Results in
Using unit path: /home/ Using unit path: /usr/ Using unit path: /etc/ Using unit path: /data/FPC/installed/3.1.1/
On systems where filenames are case sensitive (such as unix and linux ), the compiler will :
This is necessary, since Pascal is case-independent, and the statements Uses Unit1; or uses unit1; should have the same effect.
It will do this first with the extension .ppu (the compiled unit), .pp and then with the extension .pas.
For instance, suppose that the file foo.pp needs the unit bar. Then the command
fpc -Fu.. -Fuunits foo.pp
will tell the compiler to look for the unit bar in the following places:
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 -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 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.
If you include a file in your source with the {$I filename} directive, the compiler will look for it in the following places:
You can add files to the include file search path with the -I, (see ??) or -Fi, (see ??) options.
As an example, consider the following include statement in a file units/foo.pp:
{$i ../bar.inc}
Then the following command :
fpc -Iincfiles units/foo.pp
will cause the compiler to look in the following directories for bar.inc:
When you link to object files (using the {$L file.o} directive, the compiler will look for this file in the same way as it looks for include files:
You can add files to the object file search path with the -Fo, (see ??) option.
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 -n, (see ??) option, the compiler will look for a configuration file fpc.cfg in the following places:
Remark: Note that the compiler directory is determined by the location of the actual compiler binary. This has 2 consequences:
Free Pascal 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 is very simple. Assuming that you have a program source in the file prog.pp, you can compile this with the following command:
fpc [options] prog.pp
The square brackets [ ] indicate that what is between them is optional.
If your program file has the .pp or .pas extension, you can omit this on the command line, e.g. in the previous example you could have typed:
fpc [options] prog
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 .o. This contains the object file for your program. If you compiled a program, you can delete the object 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 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 foo.pp, just type :
fpc foo
Recall the remark about file extensions in the previous section.
When all went well, you will be left with 2 (two) unit files:
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 .ppu and .o file. One is useless without the other.
The Free Pascal 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 ppumove tool, section ?? ).
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 strip.The usage is simple. Just type
strip prog
On the command line, and the strip program will remove all unnecessary information from your program. This can lead to size reductions of up to 30 %.
You can use the -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 -XX, (see ??) switch. This technique is described in full in the programmers guide.
SET_PP.BAT in AUTOEXEC.BAT.SHELL=C:\DOS\COMMAND.COMand change it to the following:
SHELL=C:\DOS\COMMAND.COM /E:1024You may just need to specify a higher value, if this parameter is already set.
The output of the compiler can be controlled in many ways. This can be done essentially in two distinct ways:
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.
The available options for the current version of the compiler are listed by category. Also, see chapter ?? for a listing as generated by the current compiler.
The difference between an error/fatal error/hint/warning/note is the severity:
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.