Subsections


E. Using fpcmake

1 Introduction

Free Pascal comes with a special makefile tool, fpcmake, which can be used to construct a Makefile for use with GNU make. All sources from the Free Pascal team are compiled with this system.

fpcmake uses a file Makefile.fpc and constructs a file Makefile from it, based on the settings in Makefile.fpc.

The following sections explain what settings can be set in Makefile.fpc, what variables are set by fpcmake, what variables it expects to be set, and what targets it defines. After that, some settings in the resulting Makefile are explained.


2 Functionality

fpcmake generates a makefile, suitable for GNU make, which can be used to
  1. Compile units and programs, fit for testing or for final distribution.
  2. Compile example units and programs separately.
  3. Install compiled units and programs in standard locations.
  4. Make archives for distribution of the generated programs and units.
  5. Clean up after compilation and tests.
fpcmake knows how the Free Pascal compiler operates, which command line options it uses, how it searches for files and so on; It uses this knowledge to construct sensible command-lines.

Specifically, it constructs the following targets in the final makefile:

all
Makes all units and programs.
debug
Makes all units and programs with debug info included.
smart
Makes all units and programs in smartlinked version.
examples
Makes all example units and programs.
shared
Makes all units and programs in shared library version (currently disabled)
install
Installs all units and programs.
sourceinstall
Installs the sources to the Free Pascal source tree.
exampleinstall
Installs any example programs and units.
distinstall
Installs all units and programs, as well as example units and programs.
zipinstall
Makes an archive of the programs and units which can be used to install them on another location, i.e. it makes an archive that can be used to distribute the units and programs.
zipsourceinstall
Makes an archive of the program and unit sources which can be used to distribute the sources.
zipexampleinstall
Makes an archive of the example programs and units which can be used to install them on another location, i.e. it makes an archive that can be used to distribute the example units and programs.
zipdistinstall
Makes an archive of both the normal as well as the example programs and units. This archive can be used to install them on another location, i.e. it makes an archive that can be used to distribute.
clean
Cleans all files that are produced by a compilation.
distclean
Cleans all files that are produced by a compilation, as well as any archives, examples or files left by examples.
cleanall
Same as clean.
info
Produces some information on the screen about used programs, file and directory locations, where things will go when installing and so on.
Each of these targets can be highly configured, or even totally overridden by the configuration file Makefile.fpc

3 Usage

fpcmake reads a Makefile.fpc and converts it to a Makefile suitable for reading by GNU make to compile your projects. It is similar in functionality to GNU configure or Imake for making X projects.

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

If no options are given, it just attempts to read the file Makefile.fpc in the current directory and tries to construct a Makefile from it if the -m option is given. Any previously existing Makefile will be erased.

if the -p option is given, instead of a Makefile, a Package.fpc is generated. A Package.fpc file describes the package and it's dependencies on other packages.

Additionally, the following command-line options are recognized:

-p
A Package.fpc file is generated.
-w
A Makefile is generated.
-T targets
Support only specified target systems. Targets is a comma-separated list of targets. Only rule for the specified targets will be written.
-v
Be more verbose.
-q
be quiet.
-h
Writes a small help message to the screen.

4 Format of the configuration file

This section describes the rules that can be present in the file that is fed to fpcmake.

The file Makefile.fpc is a plain ASCII file that contains a number of pre-defined sections as in a WINDOWS .ini-file, or a Samba configuration file.

They look more or less as follows:

[package]
name=mysql
version=1.0.5

[target]
units=mysql_com mysql_version mysql
examples=testdb

[require]
libc=y

[install]
fpcpackage=y

[default]
fpcdir=../..

The following sections are recognized (in alphabetical order):

1 clean

Specifies rules for cleaning the directory of units and programs. The following entries are recognized:
units
names of all units that should be removed when cleaning. Don't specify extensions, the makefile will append these by itself.
files
names of files that should be removed. Specify full filenames.

2 compiler

In this section values for various compiler options can be specified, such as the location of several directories and search paths.

The following general keywords are recognised:

options
The value of this key will be passed on to the compiler as options.
version
If a specific or minimum compiler version is needed to compile the units or programs, then this version should be specified here.

The following keys can be used to control the location of the various directories used by the compiler:

unitdir
A colon-separated list of directories that must be added to the unit search path of the compiler.
librarydir
A colon-separated list of directories that must be added to the library search path of the compiler.
objectdir
A colon-separated list of directories that must be added to the object file search path of the compiler.
targetdir
Specifies the directory where the compiled programs should go.
sourcedir
A space separated list of directories where sources can reside. This will be used for the vpath setting of GNU make.
unittargetdir
Specifies the directory where the compiled units should go.
includedir
A colon-separated list of directories that must be added to the include file search path of the compiler.
sourcedir

3 Default

The default section contains some default settings. The following keywords are recognized:
cpu
Specifies the default target processor for which the Makefile should compile the units and programs. By default this is determined from the default compiler processor.
dir
Specifies any subdirectories that make should also descend in and make the specified target there as well.
fpcdir
Specifies the directory where all the Free Pascal source trees reside. Below this directory the Makefile expects to find the rtl, fcl and packages directory trees.
rule
Specifies the default rule to execute. fpcmake will make sure that this rule is executed if make is executed without arguments, i.e., without an explicit target.
target
Specifies the default operating system target for which the Makefile should compile the units and programs. By default this is determined from the default compiler target.

4 Dist

The Dist section controls the generation of a distribution package. A distribution package is a set of archive files (zip files or tar files on unix systems) that can be used to distribute the package.

The following keys can be placed in this section:

destdir
Specifies the directory where the generated zip files should be placed.
zipname
Name of the archive file to be created. If no zipname is specified, this defaults to the package name.
ziptarget
This is the target that should be executed before the archive file is made. This defaults to install.

5 Install

Contains instructions for installation of the compiler units and programs. The following keywords are recognized:
basedir
The directory that is used as the base directory for the installation of units. Default this is prefix appended with /lib/fpc/FPC_VERSION for LINUX or simply the prefix on other platforms.
datadir
Directory where data files will be installed, i.e. the files specified with the Files keyword.
fpcpackage
A boolean key. If this key is specified and equals y, the files will be installed as a fpc package under the Free Pascal units directory, i.e. under a separate directory. The directory will be named with the name specified in the package section.
files
extra data files to be installed in the directory specified with the datadir key.
prefix
is the directory below which all installs are done. This corresponds to the -prefix argument to GNU configure. It is used for the installation of programs and units. By default, this is /usr on LINUX, and /pp on all other platforms.
units
extra units that should be installed, and which are not part of the unit targets. The units in the units target will be installed automatically.
Units will be installed in the subdirectory units/$(OS_TARGET) of the dirbase entry.

6 Package

If a package (i.e. a collection of units that work together) is being compiled, then this section is used to keep package information. The following information can be stored:
name
The name of the package. When installing it under the package directory, this name will be used to create a directory (unless it is overridden by one of the installation options)
version
The version of this package.
main
If the package is part of another package, this key can be specified to indicate which package it is part of.

7 Prerules

Anything that is in this section will be inserted as-is in the makefile before the makefile target rules that are generated by fpcmake. This means that any variables that are normally defined by fpcmake rules should not be used in this section.

8 Requires

This section is used to indicate dependency on external packages (i.e units) or tools. The following keywords can be used:
fpcmake
Minimal version of fpcmake that this makefile.fpc needs.
packages
Other packages that should be compiled before this package can be compiled. Note that this will also add all packages these packages depend on to the dependencies of this package. By default, the Free Pascal Run-Time Library is added to this list.
libc
a boolean value that indicates whether this package needs the C library.
nortl
a boolean that prevents the addition of the Free Pascal Run-Time Library to the required packages.
unitdir
These directories will be added to the units search path of the compiler.
packagedir
List of package directories. The packages in these directories will be made as well before making the current package.
tools
A list of executables of extra tools that are required. The full path to these tools will be defined in the makefile as a variable with the same name as the tool name, only in uppercase. For example, the following definition:
tools=upx
will lead to the definition of a variable with the name UPX which will contain the full path to the upx executable.

9 Rules

In this section dependency rules for the units and any other needed targets can be inserted. It will be included at the end of the generated makefile. Targets or 'default rules' that are defined by fpcmake can be inserted here; if they are not present, then fpcmake will generate a rule that will call the generic fpc_ version. For a list of standard targets that will be defined by fpcmake, see section fpcmakefunctionality.

For example, it is possible to define a target all:. If it is not defined, then fpcmake will generate one which simply calls fpc_all:

all: fpc_all
The fpc_all rule will make all targets as defined in the Target section.

10 Target

This is the most important section of the makefile.fpc file. Here the files are defined which should be compiled when the 'all' target is executed.

The following keywords can be used there:

dirs
A space separated list of directories where make should also be run.
exampledirs
A space separated list of directories with example programs. The examples target will descend in this list of directories as well.
examples
A space separated list of example programs that need to be compiled when the user asks to compile the examples. Do not specify an extension, the extension will be appended.
loaders
A space separated list of names of assembler files that must be assembled. Don't specify the extension, the extension will be appended.
programs
A space separated list of program names that need to be compiled. Do not specify an extension, the extension will be appended.
rsts
a list of rst files that needs to be converted to .po files for use with GNU gettext and internationalization routines.
units
A space separated list of unit names that need to be compiled. Do not specify an extension, just the name of the unit as it would appear un a uses clause is sufficient.

5 Programs needed to use the generated makefile

At least the following programs are needed by the generated Makefile to function correctly:
cp
a copy program.
date
a program that prints the date.
install
a program to install files.
make
the make program, obviously.
pwd
a program that prints the current working directory.
rm
a program to delete files.
zip
the zip archiver program. (on dos/windows/OS2 systems only)
tar
the tar archiver program (on Unix systems only).
These are standard programs on LINUX systems, with the possible exception of make. For DOS or WINDOWS NT, they can be found in the file makeutil.zip on the Free Pascal FTP site.

The following programs are optionally needed if you use some special targets. Which ones you need are controlled by the settings in the tools section.

cmp
a DOS and WINDOWS NT file comparer.
diff
a file comparer.
ppdep
the ppdep depency lister. Distributed with Free Pascal.
ppufiles
the ppufiles unit file dependency lister. Distributed with Free Pascal.
ppumove
the Free Pascal unit mover.
sed
the sed program.
upx
the UPX executable packer.
All of these can also be found on the Free Pascal FTP site for DOS and WINDOWS NT. ppdep,ppufiles and ppumove are distributed with the Free Pascal compiler.

6 Variables that affect the generated makefile

The makefile generated by fpcmake contains a lot of variables. Some of them are set in the makefile itself, others can be set and are taken into account when set.

These variables can be split in two groups:

Each group will be discussed separately.

1 Directory variables

The first set of variables controls the directories that are recognised in the makefile. They should not be set in the Makefile.fpc file, but can be specified on the commandline.

INCDIR
this is a list of directories, separated by spaces, that will be added as include directories to the compiler command-line. Each directory in the list is prepended with -I and added to the compiler options.
UNITDIR
this is a list of directories, separated by spaces, that will be added as unit search directories to the compiler command-line. Each directory in the list is prepended with -Fu and added to the compiler options.
LIBDIR
is a list of library paths, separated by spaces. Each directory in the list is prepended with -Fl and added to the compiler options.
OBJDIR
is a list of object file directories, separated by spaces, that is added to the object files path, i.e. Each directory in the list is prepended with -Fo.

2 Compiler command-line variables

The following variable can be set on the make command-line, they will be recognised and integrated in the compiler command-line options.:

CREATESMART
If this variable is defined, it tells the compiler to create smartlinked units. Adds -CX to the command-line options.
DEBUG
If defined, this will cause the compiler to include debug information in the generated units and programs. It adds -gl to the compiler command-line, and will define the DEBUG define.
LINKSMART
Defining this variable tells the compiler to use smartlinking. It adds -XX to the compiler command-line options.
OPT
Any options that you want to pass to the compiler. The contents of OPT is simply added to the compiler command-line.
OPTDEF
Are optional defines, added to the command-line of the compiler. They get -d prepended to them.
OPTIMIZE
if this variable is defined, this will add -OG2p3 to the command-line options.
RELEASE
if this variable is defined, this will add the -Xs -OG2p3 -n options to the command-line options, and will define the RELEASE define.
STRIP
if this variable is defined, this will add the -Xs option to the command-line options.
VERBOSE
if this variable is defined, then -vnwi will be added to the command-line options.

7 Variables set by fpcmake

The makefile generated by fpcmake contains a lot of makefile variables. fpcmake will write all of the keys in the makefile.fpc as makefile variables in the form SECTION_KEYNAME. This means that the following section:

[package]
name=mysql
version=1.0.5
will result in the following variable definitions:
override PACKAGE_NAME=mysql
override PACKAGE_VERSION=1.0.5

Most targets and rules are constructed using these variables. They will be listed below, together with other variables that are defined by fpcmake.

The following sets of variables are defined:

Each of these sets is discussed in the subsequent:

1 Directory variables

The following compiler directories are defined by the makefile:

BASEDIR
is set to the current directory if the pwd command is available. If not, it is set to '.'.

COMPILER_INCDIR
is a space-separated list of library paths. Each directory in the list is prepended with -Fl and added to the compiler options. Set by the incdir keyword in the Compiler section.

COMPILER_LIBDIR
is a space-separated list of library paths. Each directory in the list is prepended with -Fl and added to the compiler options. Set by the libdir keyword in the Compiler section.

COMPILER_OBJDIR
is a list of object file directories, separated by spaces. Each directory in the list is prepended with -Fo and added to the compiler options. Set by the objdir keyword in the Compiler section.

COMPILER_TARGETDIR
This directory is added as the output directory of the compiler, where all units and executables are written, i.e. it gets -FE prepended. It is set by the targtdir keyword in the Compiler section.

COMPILER_TARGETUNITDIR
If set, this directory is added as the output directory of the compiler, where all units and executables are written, i.e. it gets -FU prepended.It is set by the targtdir keyword in the Dirs section.

COMPILER_UNITDIR
is a list of unit directories, separated by spaces. Each directory in the list is prepended with -Fu and is added to the compiler options. Set by the unitdir keyword in the Compiler section.

GCCLIBDIR
(LINUX only) is set to the directory where libgcc.a is. If needgcclib is set to True in the Libs section, then this directory is added to the compiler commandline with -Fl.

OTHERLIBDIR
is a space-separated list of library paths. Each directory in the list is prepended with -Fl and added to the compiler options. If it is not defined on linux, then the contents of the /etc/ld.so.conf file is added.

The following directories are used for installs:

INSTALL_BASEDIR
is the base for all directories where units are installed. By default, On LINUX, this is set to $(INSTALL_PREFIX)/lib/fpc/$(RELEASEVER).
On other systems, it is set to $(PREFIXINSTALLDIR). You can also set it with the basedir variable in the Install section.

INSTALL_BINDIR
is set to $(INSTALL_BASEDIR)/bin on LINUX, and
$(INSTALL_BASEDIR)/bin/$(OS_TARGET) on other systems. This is the place where binaries are installed.

INSTALL_DATADIR
The directory where data files are installed. Set by the Data key in the Install section.

INSTALL_LIBDIR
is set to $(INSTALL_PREFIX)/lib on LINUX,
and $(INSTALL_UNITDIR) on other systems.

INSTALL_PREFIX
is set to /usr/local on LINUX, /pp on DOS or WINDOWS NT. Set by the prefix keyword in the Install section.

INSTALL_UNITDIR
is where units will be installed. This is set to
$(INSTALL_BASEDIR)/units/$(OS_TARGET). If the units are compiled as a package, $(PACKAGE_NAME) is added to the directory.

2 Target variables

The second set of variables controls the targets that are constructed by the makefile. They are created by fpcmake, so you can use them in your rules, but you shouldn't assign values to them yourself.

TARGET_DIRS
This is the list of directories that make will descend into when compiling. Set by the Dirs key in the Target section?

TARGET_EXAMPLES
The list of examples programs that must be compiled. Set by the examples key in the Target section.

TARGET_EXAMPLEDIRS
the list of directories that make will descend into when compiling examples. Set by the exampledirs key in the Target section.

TARGET_LOADERS
is a list of space-separated names that identify loaders to be compiled. This is mainly used in the compiler's RTL sources. It is set by the loaders keyword in the Targets section.

TARGET_PROGRAMS
This is a list of executable names that will be compiled. the makefile appends $(EXEEXT) to these names. It is set by the programs keyword in the Target section.

TARGET_UNITS
This is a list of unit names that will be compiled. The makefile appends $(PPUEXT) to each of these names to form the unit file name. The sourcename is formed by adding $(PASEXT). It is set by the units keyword in the Target section.

ZIPNAME
is the name of the archive that will be created by the makefile. It is set by the zipname keyword in the Zip section.

ZIPTARGET
is the target that is built before the archive is made. this target is built first. If successful, the zip archive will be made. It is set by the ziptarget keyword in the Zip section.

3 Compiler command-line variables

The following variables control the compiler command-line:

CPU_SOURCE
the target CPU type is added as a define to the compiler command line. This is determined by the Makefile itself.

CPU_TARGET
the target CPU type is added as a define to the compiler command line. This is determined by the Makefile itself.

OS_SOURCE
What platform the makefile is used on. Detected automatically.

OS_TARGET
What platform will be compiled for. Added to the compiler command-line with a -T prepended.

4 Program names

The following variables are program names, used in makefile targets.

AS
The assembler. Default set to as.
COPY
a file copy program. Default set to cp -fp.
COPYTREE
a directory tree copy program. Default set to cp -frp.
CMP
a program to compare files. Default set to cmp.
DEL
a file removal program. Default set to rm -f.
DELTREE
a directory removal program. Default set to rm -rf.
DATE
a program to display the date.
DIFF
a program to produce diff files.
ECHO
an echo program.
FPC
the Free Pascal compiler executable. Default set to ppc386.exe
INSTALL
a program to install files. Default set to install -m 644 on LINUX.
INSTALLEXE
a program to install executable files. Default set to install -m 755 on LINUX.
LD
The linker. Default set to ld.
LDCONFIG
(LINUX only) the program used to update the loader cache.
MKDIR
a program to create directories if they don't exist yet. Default set to install -m 755 -d
MOVE
a file move program. Default set to mv -f
PP
the Free Pascal compiler executable. Default set to ppc386.exe
PPAS
the name of the shell script created by the compiler if the -s option is specified. This command will be executed after compilation, if the -s option was detected among the options.
PPUMOVE
the program to move units into one big unit library.
PWD
the pwd program.
SED
a stream-line editor program. Default set to sed.
UPX
an executable packer to compress your executables into self-extracting compressed executables.
ZIPPROG
a zip program to compress files. zip targets are made with this program

5 File extensions

The following variables denote extensions of files. These variables include the . (dot) of the extension. They are appended to object names.

ASMEXT
is the extension of assembler files produced by the compiler.
LOADEREXT
is the extension of the assembler files that make up the executable startup code.
OEXT
is the extension of the object files that the compiler creates.
PACKAGESUFFIX
is a suffix that is appended to package names in zip targets. This serves so packages can be made for different OSes.
PPLEXT
is the extension of shared library unit files.
PPUEXT
is the extension of default units.
RSTEXT
is the extension of the .rst resource string files.
SHAREDLIBEXT
is the extension of shared libraries.
SMARTEXT
is the extension of smartlinked unit assembler files.
STATICLIBEXT
is the extension of static libraries.

6 Target files

The following variables are defined to make targets and rules easier:

COMPILER
is the complete compiler commandline, with all options added, after all Makefile variables have been examined.
DATESTR
contains the date.
UNITPPUFILES
a list of unit files that will be made. This is just the list of unit objects, with the correct unit extension appended.

8 Rules and targets created by fpcmake

The makefile.fpc defines a series of targets, which can be called by your own targets. They have names that resemble default names (such as 'all', 'clean'), only they have fpc_ prepended.

1 Pattern rules

The makefile makes the following pattern rules:

units
how to make a pascal unit form a pascal source file.
executables
how to make an executable from a pascal source file.
object file
how to make an object file from an assembler file.

2 Build rules

The following build targets are defined:

fpc_all
target that builds all units and executables as well as loaders. If DEFAULTUNITS is defined, executables are excluded from the targets.
fpc_debug
the same as fpc_all, only with debug information included.
fpc_exes
target to make all executables in EXEOBJECTS.
fpc_loaders
target to make all files in LOADEROBJECTS.
fpc_packages
target to make all packages that are needed to make the files.
fpc_shared
target that makes all units as dynamic libraries.
fpc_smart
target that makes all units as smartlinked units.
fpc_units
target to make all units in UNITOBJECTS.

3 Cleaning rules

The following cleaning targets are defined:

fpc_clean
cleans all files that result when fpc_all was made.
fpc_distclean
is the same as both previous target commands, but also deletes all object, unit and assembler files that are present.

4 archiving rules

The following archiving targets are defined:

fpc_zipdistinstall
Target to make a distribution install of the package.
fpc_zipinstall
Target to make an install zip of the compiled units of the package.
fpc_zipexampleinstall
Target to make a zip of the example files.
fpc_zipsourceinstall
Target to make a zip of the source files.
The zip is made uzing the ZIPEXE program. Under LINUX, a .tar.gz file is created.

5 Installation rules

fpc_distinstall
target which calls the install and exampleinstall targets.
fpc_install
target to install the units.
fpc_sourceinstall
target to install the sources (in case a distribution is made)
fpc_exampleinstall
target to install the examples. (in case a distribution is made)

6 Informative rules

There is only one target which produces information about the used variables, rules and targets: fpc_info.

The following information about the makefile is presented:




2004-02-13