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 a 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).
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).
fpc foo.ppwill 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.ppwill 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 (See Fu) option. Every occurrence of one of this 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/VERSION or /usr/lib/fpc/VERSIONwhichever is found first.
On systems where filenames to lower-case (such as UNIX and LINUX), the compiler will first convert the filename of a unit to all-lowercase. This is necessary, since Pascal is case-independent, and the statements Uses Unit1; or uses unit1; should have the same effect.
Also, unit names that are longer than 8 characters will first be looked for with their full length. If the unit is not found with this name, the name will be truncated to 8 characters, and the compiler will look again in the same directories, but with the truncated name.
For instance, suppose that the file foo.pp needs the unit bar. Then the command
fpc -Fu.. -Fuunits foo.ppwill tell the compiler to look for the unit bar in the following places:
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.
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.ppwill cause the compiler to look in the following directories for bar.inc:
Starting from version 1.0.6 of the compiler, usage of the file ppc386.cfg is considered deprecated. The file should now be called fpc.cfg and will work for all processor targets. For compatibility, fpc.cfg will be searched first, and if not found, the file ppc386.cfg will be used.
Unless you specify the See n option, the compiler will look for a configuration file fpc.cfg in the following places:
If no support for long filenames is present, it will truncate unit names to 8 characters.
It is not recommended to put units in directories that contain spaces in their names, since the linker doesn't understand such filenames.
fpc [options] prog.ppThe 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 extensions .o. This contains the object file for your program. If you compiled a program, you can delete the object file (.o), but not if you compiled a unit.
Then the object file contains the code of the unit, and will be linked in any program that uses the unit you compiled, so you shouldn't remove it.
Compiling a unit 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 fooRecall the remark about file extensions in the previous section.
When all went well, you will be left with 2 (two) unit files:
Remark: Under LINUX and UNIX, a unit source file must have a lowercase filename. Since Pascal is case independent, you can specify the names of units in the uses clause in either case. To get a unique filename, the Free Pascal compiler changes the name of the unit to all lowercase when looking for unit files.
The compiler produces lowercase files, so your unit will be found, even if your source file has uppercase letters in it. Only when the compiler tries to recompile the unit, it will not find your source because of the uppercase letters.
Not only is it possible to compile a shared library under WINDOWS and LINUX, but also it is possible to take existing units and put them together in 1 static or shared library (using the ppumove tool)
The GO32V1 platform is officially no longer supported, so this section is of interest only to people who wish to make go32V1 binaries anyway.
The first thing is to use the DOS extender from D.J. Delorie to execute your program :
go32 progThis is fine for testing, but if you want to use a program regularly, it would be easier if you could just type the program name, i.e.
progThis can be accomplished by making a DOS executable of your compiled program.
There two ways to create a DOS executable (under DOS only):
AOUT2EXE PROGand you get a DOS executable which loads the GO32.EXE automatically. the GO32.EXE executable must be in current directory or be in a directory in the PATH variable.
COPY /B GO32.EXE+PROG PROG.EXE(assuming Free Pascal created a file called PROG, of course.) This becomes then a stand-alone executable for DOS, which doesn't need the GO32.EXE on the machine where it should run.
EXE2COFF PROG.EXE(we suppose that PROG.EXE is the program generated by the compilation process.
COPY /B PMODSTUB.EXE+PROG PROG.EXEIf the PMODSTUB.EXE file isn't in your local directory, you need to supply the whole path to it.
That's it. No additional steps are needed to create a PMODE extender executable.
Be aware, though, that the PMODE extender doesn't support virtual memory, so if you're short on memory, you may run unto trouble. Also, officially there is not support for the PMODE/DJ extender. It just happens that the compiler and some of the programs it generates, run under this extender too.
When you created your program, it is possible to reduce its size. This is possible, because the compiler leaves a lot of information in the program which, strictly speaking, isn't required for the execution of it. The surplus of information can be removed with a small program called strip.The usage is simple. Just type
strip progOn 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 %.
Remark: In the WIN32 version, strip is called stripw.
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 the can be smartlinked. This means that only the functions and procedures are linked in your program, leaving out any unnecessary code. This technique is described in full in the programmers guide.