E. Using fpcmake

E.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.

E.2 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 it's 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. any previously existing Makefile will be erased.

E.3 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:

[targets]
units=mysql_com mysql_version mysql
examples=testdb

[dirs]
fpcdir=../..

[rules]
mysql$(PPUEXT): mysql$(PASEXT) mysql_com$(PPUEXT)
testdb$(EXEEXT): testdb$(PASEXT) mysql$(PPUEXT)

The following sections are recognized (in alphabetical order):

E.3.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.

E.3.2 Defaults

The defaults section contains some default settings. The following keywords are recognized:

defaultdir

defaultbuilddir

defaultinstalldir

defaultzipinstalldir

defaultcleandir

defaultrule

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.

defaulttarget

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.

defaultcpu

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.

E.3.3 Dirs

In this section you can specify the location of several directories which the Makefile could need for compiling other packages or for finding the units.

The following keywords are recognised:

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.

packagedir

Specifies the directory where all the package source directories are. By default this equals $(FPCDIR)/packages.

toolkitdir

Specifies the directory where toolkit source directories are.

componentdir

Specifies the directory where component source directories are.

unitdir

A colon-separated list of directories that must be added to the unit search path of the compiler.

libdir

A colon-separated list of directories that must be added to the library search path of the compiler.

objdir

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.

sourcesdir

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.

incdir

A colon-separated list of directories that must be added to the include file search path of the compiler.

E.3.4 Info

This section can be used to customize the information generating targets that fpcmake generates. It is simply a series of boolean values that specify whether a certain part of the info target will be generated. The following keywords are recognised:

infoconfig

Specifies whether configuration info should be shown. By default this is True.

infodirs

Specifies whether a list of subdirectories to be treated will be shown. By degault this is False.

infotools

Specifies whether a list of tools that are used by the makefile will be shown. By default this is False.

infoinstall

Specifies whether the installation rules will be shown. By default this is True.

infoobjects

Specifies whether the Makefile objects will be shown, i.e. a list of all units and programs that will be built by make.

E.3.5 Install

Contains instructions for installation of your units and programs. The following keywords are recognized:

dirprefix

is the directory below wchich 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.

dirbase

The directory that is used as the base directory for the installation of units. Default this is dirprefix appended with /lib/fpc/FPC_VERSION for LINUX or simply the dirprefix on other platforms.

Units will be installed in the subdirectory units/$(OS_TARGET) of the dirbase entry.

E.3.6 Libs

This section specifies what units should be merged into a library, and what external libraries are needed. It can contain the following keywords:

libname

the name of the library that should be created.

libunits

a comma-separated list of units that should be moved into one library.

needgcclib

a boolean value that specifies whether the gcc library is needed. This will make sure that the path to the GCC library is inserted in the library search path.

needotherlib

(LINUX only) a boolean value that tells the makefile that it should add all library directories from the ld.so.conf file to the compiler command-line.

E.3.7 Packages

Which packages must be used. This section can contain the following keywords:

packages

A comma-separated list of packages that are needed to compile the targets. Valid for all platforms. In order to differentiate between platforms, you can prepend the keyword packages with the OS you are compiling for, e.g. linuxpackages if you want the makefile to use the listed packages on linux only.

fcl

This is a boolean value (0 or 1) that indicates whether the FCL is used.

rtl

This is a boolean value (0 or 1) that indicates whether the RTL should be recompiled.

E.3.8 Postsettings

Anything that is in this section will be inserted as-is in the makefile after the makefile rules that are generated by fpcmake, but before the general configuration rules. In this section, you cannot use variables that are defined by fpcmake rules, but you can define additional rules and configuration variables.

E.3.9 Presettings

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 you cannot use any variables that are normally defined by fpcmake rules.

E.3.10 Rules

In this section you can insert dependency rules and any other targets you wish to have. Do not insert 'default rules' here.

E.3.11 Sections

Here you can specify which 'rule sections' should be included in the Makefile. The sections consist of a series of boolean keywords; each keyword decies whether a particular section will be written to the makefile. By default, all sections are written.

You can have the following boolean keywords in this section.

none

If this is set to true, then no sections are written.

units

If set to False, fpcmake omits the rules for compiling units.

exes

If set to False, fpcmake omits the rules for compiling executables.

loaders

If set to False, fpcmake omits the rules for assembling assembler files.

examples

If set to False, fpcmake omits the rules for compiling examples.

package

If set to False, fpcmake omits the rules for making packages.

compile

If set to False, fpcmake omits the generic rules for compiling pascal files.

depend

If set to False, fpcmake omits the dependency rules.

install

If set to False, fpcmake omits the rules for installing everything.

sourceinstall

If set to False, fpcmake omits the rules for installing the sources.

zipinstall

If set to False, fpcmake omits the rules for installing archives.

clean

If set to False, fpcmake omits the rules for cleaning the directories.

libs

If set to False, fpcmake omits the rules for making libraries.

command

If set to False, fpcmake omits the rules for composing the command-line based on the various variables.

exts

If set to False, fpcmake omits the rules for making libraries.

dirs

If set to False, fpcmake omits the rules for running make in subdirectories..

tools

If set to False, fpcmake omits the rules for running some tools as the erchiver, UPX and zip.

info

If set to False, fpcmake omits the rules for generating information.

E.3.12 Targets

In this section you can define the various targets. The following keywords can be used there:

dirs

A space separated list of directories where make should also be run.

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.

rst

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.

E.3.13 Tools

In this section you can specify which tools are needed. Definitions to use each of the listed tools will be inserted in the makefile, depending on the setting in this section.

Each keyword is a boolean keyword; you can switch the use of a tool on or off with it.

The following keywords are recognised:

toolppdep

Use ppdep, the dependency tool. True by default.

toolppumove

Use ppumove, the Free Pascal unit mover. True by default.

toolppufiles

Use the ppufile tool to determine dependencies of unit files. True by default.

toolsed

Use sed the stream line editor. False by default.

tooldata2inc

Use the data2inc tool to create include files from data files. False by default.

tooldiff

Use the GNU diff tool. False by default.

toolcmp

Use the cmp file comparer tool. False by default.

toolupx

Use the upx executable packer.True by default.

tooldate

use the date date displaying tool. True by default.

toolzip

Use the zip file archiver. This is used by the zip targets. True by default.

E.3.14 Zip

This section can be used to make zip files from the compiled units and programs. By default all compiled units are zipped. The zip behaviour can be influenced with the presettings and postsettings sections.

The following keywords can be used in this unit:

zipname

this file is the name of the zip file that will be produced.

ziptarget

is the name of a makefile target that will be executed before the zip is made. By default this is the install target.

E.4 Programs needed to use the generated makefile

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.

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 gnuutils.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. Used if toolcmp is True.

diff

a file comparer. Used if tooldiff is True.

ppdep

the ppdep depency lister. Used if toolppdep is True. Distributed with Free Pascal.

ppufiles

the ppufiles unit file dependency lister. Used if toolppufiles is True. Distributed with Free Pascal.

ppumove

the Free Pascal unit mover. Used if toolppumove is True. Distributed with Free Pascal.

sed

the sed program. Used if toolsed is True.

upx

the UPX executable packer. Used if toolupx is True.

zip

the zip archiver program. Used if toolzip is True.

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.

E.5 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 several groups:

• Environment variables.
• Directory variables.
• Compiler command-line variables.

Each group will be discussed separately.

E.5.1 Environment variables

In principle, fpcmake doesn't expect any environment variable to be set. Optionally, you can set the variable FPCMAKEINI which should contain the name of a file with the basic rules that fpcmake will generate.

By default, fpcmake has a compiled-in copy of fpcmake.ini, which contains the basic rules, so there should be no need to set this variable. You can set it however, if you wish to change the way in which fpcmake works and creates rules.

The initial fpcmake.ini file can be found in the utils source package on the Free Pascal ftp site.

E.5.2 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.

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.

E.5.3 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:

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 do not get -d prepended.

E.6 Variables set by fpcmake

All of the following variables are only set by fpcmake, if they aren't already defined. This means that you can override them by setting them on the make commandline, or setting them in the presettings section. But most of them are correctly determined by the generated Makefile or set by your settings in the configuration file.

The following sets of variables are defined:

• Directory variables.
• Program names.
• File extensions.
• Target files.

Each of these sets is discussed in the subsequent:

E.6.1 Directory variables

The following 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 '.'.

BASEINSTALLDIR

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

BININSTALLDIR

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

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.

LIBINSTALLDIR

is set to $(BASEINSTALLDIR) on LINUX,
and $(BASEINSTALLDIR)/lib on other systems.

NEEDINCDIR

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 Dirs section.

NEEDLIBDIR

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 Dirs section.

NEEDOBJDIR

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 Dirs section.

NEEDUNITDIR

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 Dirs section.

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 Dirs section.

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.

PREFIXINSTALLDIR

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

UNITINSTALLDIR

is where units will be installed. This is set to
$(BASEINSTALLDIR)/$(UNITPREFIX)
on LINUX. On other systems, it is set to
$(BASEINSTALLDIR)/$(UNITPREFIX)/$(OS_TARGET).

E.6.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.

EXEOBJECTS

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 Targets section.

LOADEROBJECTS

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.

UNITOBJECTS

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 Targets 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.

E.6.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.

LIBNAME

if a shared library is requested this is the name of the shared library to produce. Don't add lib to this, the compiler will do that. It is set by the libname keyword in the Libs section.

NEEDGCCLIB

if this variable is defined, then the path to libgcc is added to the library path. It is set by the needgcclib keyword in the Libs section.

NEEDOTHERLIB

(LINUX only) If this is defined, then the makefile will append all directories that appear in /etc/ld.so.conf to the library path. It is set by the needotherlib keyword in the Libs section.

OS_TARGET

What platform you want to compile for. Added to the compiler command-line with a -T prepended.

E.6.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.

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.

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

E.6.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.

PASEXT

is the extension of pascal files used in the compile rules. It is determined by looking at the first EXEOBJECTS source file or the first UNITOBJECTS files.

PPLEXT

is the extension of shared library unit files.

PPUEXT

is the extension of default units.

SHAREDLIBEXT

is the extension of shared libraries.

SMARTEXT

is the extension of smartlinked unit assembler files.

STATICLIBEXT

is the extension of static libraries.

E.6.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.

EXEFILES

is a list of executables that will be created by the makefile.

EXEOFILES

is a list of executable object files that will be created by the makefile.

LOADEROFILES

is a list of object files that will be made from the loader assembler files. This is mainly for use in the compiler's RTL sources.

UNITPPUFILES

a list of unit files that will be made. This is just the list of unit objects, with the correct unit extension appended.

UNITOFILES

a list of unit object files that will be made. This is just the list of unit objects, with the correct object file extension appended.

E.7 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.

E.7.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.

E.7.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_exes

target to make all executables in EXEOBJECTS.

fpc_loaders

target to make all files in LOADEROBJECTS.

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.

E.7.3 Cleaning rules

The following cleaning targets are defined:

fpc_clean

cleans all files that result when fpc_all was made.

fpc_cleanall

is the same as both previous target commands, but also deletes all object, unit and assembler files that are present.

E.7.4 archiving rules

The following archiving targets are defined:

fpc_zipinstall

will create an archive file (it's name is taken from $(ZIPNAME)) from the compiled units.

fpc_zipsourceinstall

will create an archive file (it's name is taken from $(ZIPNAME)), from the sources.

The zip is made uzing the ZIPEXE program. Under LINUX, a .tar.gz file is created.

E.7.5 Informative rules

The following targets produce information about the makefile:

fpc_cfginfo

gives general configuration information: the location of the makefile, the compiler version, target OS, CPU.

fpc_dirinfo

gives the directories, used by the compiler.

fpc_info

executes all other info targets.

fpc_installinfo

gives all directories where files will be installed.

fpc_objectinfo

lists all objects that will be made.

fpc_toolsinfo

lists all defined tools.