2. Library compilation
Once you're satisfied with the version of config.mk that
has been copied to your current directory, you can simply re-invoke
gnu make with no arguments. The top-level Makefile will
automatically detect the config sub-makefile in the current directory,
and use it to drive the library compilation. The latter can be seen
as a series of different steps decribed here:
Compiling the ftsystem component
It encapsulates all low-level operations (memory management +
i/o access) for the library. Its default version, located in
./src/base/ftsystem.c uses the ANSI C library but
system-specific implementations are also available to
improve performance (e.g. memory-mapped files on Unix).
Compiling the base layer and optional components
They provide the library's high-level API as well as various useful
routines for client applications. Many features of the base layer can
be activated or not depending on a configuration file named
ftoption.h
Compiling the modules
Each module is used to support a specific font format (it is then
called a font driver), or to provide helper services to
the drivers (e.g. the auto-hinter). They are all located in
sub-directories of ./src, like ./src/truetype,
./src/type1.
Compiling the ftinit component
This one is in charge of implementing FT_Init_FreeType,
the library initialisation routine. It also selects what modules
are activated when a new library instance is created.
II. Details of the build setup.
When the top-level Makefile is invoked, it looks for a
file named config.mk in the current directory.
If this file is found, it is used directly to build the library
(skip to Section III for details then).
Otherwise, the file ./config/detect.mk is included
by the top-level Makefile and parsed. Its purpose is to drive the
platform-detection phase, by:
Defining the PLATFORM variable, which indicates
what the currently detected platform is. It is initially
set to the default value "ansi".
Searching for a detect.mk file in all
subdirectories of ./config.
Each such file is included and parsed. Each of these files must
try to detect if the host platform is a system it knows
about. If so, it changes the value of the PLATFORM variable
accordingly.
Copying the selected configuration submakefile to the current directory
under the name config.mk.
This is illustrated by the following graphics :
Each system-specific detect.mk works as follows:
It checks that the value of PLATFORM is currently set
to ansi, which indicates that no platform was detected
for now. If this isn't true, it doesn't do anything
Otherwise, it runs a series of test to see wether it is on a
system it knows about. Here are a few examples of tests:
|
Unix
|
checks for a file named /sbin/init, and runs, when it found
it, a 'configure' script to generate the relevant config sub-makefile
|
|
Dos
|
checks for the COMSPEC environment variable, then tries to
run the "ver" command on the current shell to check that there
is a "Dos" substring in its output; if not, it tries to find the
substring "MDOS\COMMAND" in COMSPEC, which indicates
a Dos session under OS/2.
|
|
Win32
|
if the environment variable OS is defined and has the value
Windows_NT, or if COMSPEC is defined and the
"ver" returns a string that contains Windows in it,
we're on a Win32 system.
|
It sets the value of PLATFORM to a new value corresponding
to its platform.
It then tries to select a configuration
sub-makefile, depending on the current platform and any optional
make target (like "visualc" or "devel", etc..). Note that it can
even generate the file, as on Unix through Autoconf/Automake.
It copies the selected configuration sub-makefile to the current
directory, under the name config.mk
If one wants to support a new platform in the build system, it simply needs
to provide:
- A new subdirectory, in ./config, with a file named
detect.mk in it, containing relevant checks for the system.
- One or more configuration sub-makefiles that will get copied to
config.mk at build setup time. You can use the one in
./config/ansi/config.mk as a template.
Similary, supporting a new compiler on an existing system simply means:
- Writing a new config sub-makefile that contains definitions used to
specify the compiler and flags for the build.
- Change your ./config/system/detect.mk to recognize
a new optional build target that will copy your new config sub-makefile
instead of the default one.
III. Details of the library compilation.
When the top-level Makefile is invoked, it looks for a file named
config.mk in the current directory. If one is found, it
defines the BUILD_FREETYPE variable, then includes and parses it.
The structure of this file is the following:
First, it defines a series of Make variables that describe
the host environment, like the compiler, compilation flags,
object file suffix, the directory where all object files are
placed, etc..
If BUILD_FREETYPE is defined, it includes the file
./config/freetype.mk, which is in charge of
defining all the rules used to build the library object files.
(The test is useful to use the config.mk file to
compile other projects that rely on FreeType 2, like its
demonstration programs).
Finally, it defines the rule(s) used to link FreeType 2 object files
into a library file (e.g. libfreetype.a, freetype.lib,
freetype.dll, ...). Unfortunately, the command line interface of link tools is
a lot less standardized than those of compilers, which
explains why this rule must be defined in the system-specific
config.mk.
The following is an explanation of what ./config/freetype.mk
does to build the library objects:
a. Include paths
To avoid namespace pollution, the freetype directory prefix
is used to include all public header files of the library. This means
that a client application will typically use lines like:
#include <freetype/freetype.h>
#include <freetype/ftglyph.h>
to include one the FreeType 2 public header files. freetype.mk
uses a variable named INCLUDES to hold the inclusion
paths list, and thus starts by adding ./include to it. However,
nothing prevents
freetype.mk uses a variable named INCLUDES
to hold directory inclusion-path to be used when compiling the library.
It always add ./include to this variable, which means
b. Configuration header files:
Three header files used to configure the compilation of the
FreeType 2 library. Their default versions are all located in the
directory ./include/freetype/config/, even though
project specific versions can be provided on a given build, as
described later:
#include <freetype/config/ftoption.h>
This file contains a set of configuration macro definitions that
can be toggled to activate or deactivate certain features of the
library. By changing one of these definitions, it is possible to
compile only the features that are needed for a specific
project. Note that by default, all options are enabled.
You might need to provide an alternative version of ftoption.h
for one of your own projects.
#include <freetype/config/ftconfig.h>
This file includes ftoption.h but also contains some automatic
macro definitions used to indicate some important system-specific
features (e.g: word size in bytes, DLL export prefix macros, etc..).
You shouldn't normally need to change or provide an alternative
version of this file.
#include <freetype/config/ftmodule.h>
This file is very special, as it is normally machine-generated, and
used by the ftinit component that is described below. To
understand it, one must reminds that FreeType 2 has an extremely
modular design and that it's possible to change, at run-time,
the modules it's using. The ftmodule.h file simply contains
the list of modules that are registered with each new instance of
the library.
Note that the file can be re-generated automatically by invoking
make setup from the top-level directory. The re-generated
list contains all the modules that were found in subdirectories of
./src.
Note that we strongly advise you to avoid modifying the config files
within the FreeType 2 source directory hierarchy. Rather, it's possible
to specify alternative versions through the help of a build-specific
include path that is include before ./include in the inclusion
path.
For example, imagine that your platform, named foo, needs a
specific version of ftoption.h
a. Compiling the ftsystem component:
FreeType 2 encapsulates all low-level operations (i.e. memory management
and i/o access) within a single component called ftsystem.
Its default implementation uses the ANSI C Library and is located
in ./src/base/ftsystem.c.
However, some alternate, system-specific, implementations of
ftsystem are provided with the library in order to support more
efficient and advanced features. As an example, the file
./config/unix/ftsystem.c is an implementation that
uses memory-mapped files rather than the slow ANSI fopen,
fread and fseek, boosting performance significantly.
The build system is thus capable of managing alternate implementations
of ftsystem
b. Compiling the base layer and optional components:
The high-level API of the library is provided by a component called the
base layer, whose source is located in ./src/base. This
directory also contains one or more components that are optional, i.e.
that are not required by the library but provide valuable routines to
client applications.
The features of the base library and other components are selected through
a single configuration file named
./include/freetype/config/ftoption.h. It contains a list
of commented configuration macro definitions, that can be toggled to
activate or de-activate a certain feature or component at build time.
For example, the code in ./src/base/ftdebug.c will be compiled
only if one of these two macros are defined in ftoption.h:
FT_DEBUG_LEVEL_ERROR or FT_DEBUG_LEVEL_TRACE
c. Compiling the modules:
Once the base layer is completed, the build system starts to compile each
additional module independently. These are simply defined as all source
code located in a sub-directory of ./src that contains a file
named rules., for example:
src/sfnt, src/truetype, src/type1, ...
The rules. file simply contains directives used by the
build system to compile the corresponding module into a single object
file.
d. Compiling the ftinit component:
The file ./src/base/ftinit.c is special because it is used
to implement the library initialisation function FT_Init_FreeType.
Typically, you will end up with all object files, as well as the
corresponding library file, residing in the freetype2/obj
directory.
1. Purpose of the configuration sub-makefile
2. Managing module dependencies
3.
IV. Managing the modules list
The build system features some important points, which are all detailed
in the following sections:
- Automatic host platform detection
The first time the top Makefile is invoked, it will
run a series of rules to detect your platform. It will then
create a system-specific configuration sub-Makefile in the
current directory, called config.mk. You can now
invoke the top Makefile a second time to compile the
library directly.
The configuration sub-makefile can be regenerated any time
by invoking "make setup", which will re-run the
detection rules even if a config.mk is already present.
- User-selectable builds
- Automatic detection of font drivers
FreeType is made of a "base" layer that invokes several
separately-compiled modules. Each module is a given
font driver, in charge of supporting a given font format.
The list of font drivers is located in the file
"freetype2/config/system/ftmodule.h", however
it can be regenerated on-demand. Adding a new module to the
FreeType source tree is thus as easy as:
- create a new directory in "freetype2/src" and
put the new driver's source code and sub-makefiles there.
- invoke the top Makefile with target
"modules" (as in "make modules"),
as this will automatically regenerate the list of
available drivers by detecting the new directory and
its content.
II. Host Platform Detection
When the top-level Makefile is invoked, it looks for a
file named config.mk in the current directory. If this
file is found, it is used to build the library
(see Section III).
Otherwise, the file freetype2/config/detect.mk is included
and parsed. Its purpose is to:
- Define the PLATFORM variable, which indicates
what is the currently detected platform. It is initially
set to the default value "ansi".
- It searches for a detect.mk file in all
subdirectories of freetype2/config. Each such
file is included and parsed. Each of these files must
try to detect if the host platform is a system it knows
about. If so, it changes the value of the PLATFORM
accordingly.
This is illustrated by the following graphics :
Note that each system-specific detect.mk is in charge
of copying a valid configuration makefile to the current directory
(i.e. the one where make was invoked), depending on the
current targets. For example, the Win32 detect.mk will
be able to detect a "visualc" or "lcc" target,
as described in section I. Similarly, the OS/2 detect.mk
can detect targets like "borlandc", "watcom"
or "visualage", etc..
III. Building the library
When the top-level Makefile is invoked and that it finds
a config.mk file in the current directory, it defines
the variable BUILD_FREETYPE, then includes and parses the
configuration sub-makefile.
The latter defines a number of important variables that describe
the compilation process to the build system. Among other things:
- the extension to be used for object files and library files
(i.e. .o and .a on Unix, .obj
and .lib on Dos-Windows-OS/2, etc..).
- the directory where all object files will be stored
(usually freetype2/obj), as well as the one
containing the library file (usually the same as for
objects).
- the command line compiler, and its compilation flags for
indicating a new include path (usually "-I"),
a new macro declaration (usually "-D") or
the target object file (usually "-o ")
Once these variable are defined, config.mk test for the
definition of the BUILD_FREETYPE variable. If it exists,
the makefile then includes "freetype2/config/freetype.mk"
which contains the rules required to compile the library.
Note that freetype.mk also scans the subdirectories of
"freetype2/src" for a file called "rules.mk".
Each rules.mk contains, as it names suggests, the rules
required to compile a given font driver or module.
Once all this parsing is done, the library can be compiled. Usually,
each font driver is compiled as a standalone object file (e.g.
sfnt.o, truetype.o and type1.o).
This process can be illustrated by the following graphics:
IIV. Managing the list of modules
The makefile freetype.mk only determines how to compile
each one of the modules that are located in the sub-directories of
freetype2/src.
However, when the function FT_Init_FreeType is invoked at
the start of an application, it must create a new FT_Library
object, and registers all known font drivers to it by
repeatly calling FT_Add_Driver.
The list of known drivers is located in the file
"freetype2/config/system/ftmodule.h", and is used
exclusively by the internal function FT_Default_Drivers. The
list in ftmodule.h must be re-generated each time you add
or remove a module from freetype2/src.
This is normally performed by invoking the top-level Makefile
with the modules target, as in:
This will trigger a special rule that will re-generate
ftmodule.h. To do so, the Makefile will parse all module
directories for a file called "module.mk". Each
module.mk is a tiny sub-Makefile used to add a single
module to the driver list.
This is illustrated by the following graphics:
Note that the new list of modules is displayed in a very human-friendly
way after a "make modules". Here's an example with the current
source tree (on 11 Jan 2000):
Regenerating the font drivers list in ./config/unix/ftmodule.h
* driver: sfnt ( pseudo-driver for TrueType & OpenType formats )
* driver: truetype ( Windows/Mac font files with extension *.ttf or *.ttc )
* driver: type1 ( Postscript font files with extension *.pfa or *.pfb )
-- done --
V. Building the demonstration programs
Several demonstration programs are located in the
"freetype2/demos" directory hierarchy. This directory also
includes a tiny graphics sub-system that is able to blit glyphs to
a great variety of surfaces, as well as display these in various
graphics libraries or windowed environments.
This section describes how the demonstration programs are compiled,
using the configuration freetype2/config.mk and their own
freetype2/demos/Makefile.
To compile the demonstration programs, after the library,
simply go to freetype2/demos then invoke GNU make with no
arguments.
The top-level Makefile will detect the config.mk in the
upper directory and include it. Because it doesn't define
the BUILD_FREETYPE variable, this will not force the
inclusion of freetype2/config/freetype.mk as described in
the previous section.
the Makefile will then include the makefile called
"freetype2/demos/graph/rules.mk". The graphics rules.mk
defines the rules required to compile the graphics sub-system.
Because the graphics syb-system is also designed modularly, it is able
to use any number of "modules" to display surfaces on the screen.
The graphics modules are located in the subdirectories of
freetype2/demos/config. Each such directory contains a file
named rules.mk which is in charge of:
- detecting wether the corresponding graphics library is
available at the time of compilation.
- if it is, alter the compilation rules to include the graphics
module in the build of the graph library.
When the graph library is built in demos/obj, the
demonstration programs executables are generated by the top-level
Makefile.
This is illustrated by the following graphics:
