Subsections
E. Using fpcmake
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
- Compile units and programs, fit for testing or for final distribution.
- Compile example units and programs separately.
- Install compiled units and programs in standard locations.
- Make archives for distribution of the generated programs and units.
- 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
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.
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):
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.
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
-
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.
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.
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 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.
- 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.
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.
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.
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.
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.
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.
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.
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:
- Directory variables.
- Compiler command-line variables.
Each group will be discussed separately.
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.
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.
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:
- Directory variables.
- Program names.
- File extensions.
- Target files.
Each of these sets is discussed in the subsequent:
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.
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.
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.
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
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.
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.
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.
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.
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.
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.
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.
- 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)
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:
- general configuration information: the location of
the makefile, the compiler version, target OS, CPU.
- the directories, used by the compiler.
- all directories where files will be installed.
- all objects that will be made.
- all defined tools.
2002-04-25