Subsections

- 1 Introduction
- 2 Functionality
- 3 Usage
- 4 Format of the configuration file
  - 1 clean
  - 2 compiler
  - 3 Default
  - 4 Dist
  - 5 Install
  - 6 Package
  - 7 Prerules
  - 8 Requires
  - 9 Rules
  - 10 Target
- 5 Programs needed to use the generated makefile
- 6 Variables that affect the generated makefile
  - 1 Directory variables
  - 2 Compiler command-line variables
- 7 Variables set by fpcmake
  - 1 Directory variables
  - 2 Target variables
  - 3 Compiler command-line variables
  - 4 Program names
  - 5 File extensions
  - 6 Target files
- 8 Rules and targets created by fpcmake
  - 1 Pattern rules
  - 2 Build rules
  - 3 Cleaning rules
  - 4 archiving rules
  - 5 Installation rules
  - 6 Informative rules

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

## 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:

- Directory variables.
- Compiler command-line variables.

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:

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

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:

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