ref: ed7f62aca5eab9d808daf0879607779bd2670173
dir: /docs/design/build-system.html/
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="Author" content="David Turner">
<meta name="GENERATOR" content="Mozilla/4.5 [fr] (Win98; I) [Netscape]">
<title>FreeType 2 Internals - I/O Frames</title>
</head>
<body>
<body text="#000000"
bgcolor="#FFFFFF"
link="#0000EF"
vlink="#51188E"
alink="#FF0000">
<center>
<h1>
FreeType 2.0 Build System</h1></center>
<center>
<h3>
© 2000 David Turner (<a href="fichier :///[email protected]">[email protected]</a>)<br>
© 2000 The FreeType Development Team
(<a href="mailto:[email protected]">[email protected]</a>)
</h3></center>
<p><br>
<hr WIDTH="100%">
<br>
<h2>Introduction:</h2>
<ul>
This document describes the new build system that was introduced
with FreeType 2.
</ul>
<p><hr><p>
<h2>I. Features and Background:</h2>
<ul>
The FreeType 2 build system is a set of Makefiles and sub-Makefiles that
are used to build the library on a very large variety of systems. To
understand it properly, it must be noticed that:<p>
<ul>
<li>The build system is made of a <em>single Makefile</em>,
dispatched over several directories with the help of the
<tt>include</tt> directive. Technically speaking, it is
composed of the top-level "<tt>freetype2/Makefile</tt>"
which includes several other sub-Makefiles, whose extension
is always "<tt>.mk</tt>". Examples are:<p>
<ul>
<tt>freetype2/config/freetype.mk</tt><br>
<tt>freetype2/config/<em>system</em>/detect.mk</tt><br>
<tt>freetype2/src/<em>module</em>/rules.mk</tt><br>
etc..
</ul>
<p>
<font size="+2" color="red">
We <em>strongly</em> recommend the following article:<p>
<center>
<a href="http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html">
Recursive Make Considered Dangerous
</a>
</center>
</font>
<p>
To understand why such a layout was chosen.
<p>
<li>The build system works <em>exclusively</em> with
<b>GNU Make</b>. Reason is that it is the only make utility
that has all the features required to implement the build
system as described below. Moreover, it is already ported
to hundreds of various distinct platforms and is widely and
freely available.
<p>
<em>You don't need a Unix-like shell on your platform</em>.
For example, FreeType 2 already compiles on Unix, Dos, Windows
and OS/2 right "out of the box" (assuming you have GNU Make
installed).
<p>
Note that we have <em>no plans</em> to support a different
make tool, as you'll rapidly understand by reading this
document or looking at the Makefiles themselves.
<p>
</ul>
<p>
The build system features some important points, which are all detailed
in the following sections:<p>
<ul>
<li><b>Automatic host platform detection</b><br>
The first time the top <tt>Makefile</tt> 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 <b><tt>config.mk</tt></b>. You can now
invoke the top <tt>Makefile</tt> a second time to compile the
library directly.
<p>
The configuration sub-makefile can be regenerated any time
by invoking "<tt>make setup</tt>", which will re-run the
detection rules even if a <tt>config.mk</tt> is already present.
<p>
<li><b>User-selectable builds</b><br>
The system-specific <b><tt>config.mk</tt></b> created when
running <tt>make</tt> for the first time contains various
definitions, including compiler, compiler flags, object files
directories, etc.. However, a given platform has often several
compilers available, each with a different name and flags to be
used. Rather than trying to detect the compiler in the build
system, users can also specify which compiler they use when
running <tt>make</tt>.
<p>
For example, on Win32 platforms:<p>
<ul>
<table>
<tr valign="top">
<td><b><tt>make setup</tt></b>
<td>Will generate a <tt>config.mk</tt> that
can be used to compile the library with
<b><tt>gcc</tt></b> (<em>which is the default
compiler for most supported platforms</em>).
<tr valign="top">
<td><b><tt>make setup visualc</tt></b>
<td>Will generate a different <tt>config.mk</tt>
that can be used to compile the library
with the Visual C++ command-line compiler.
<tr valign="top">
<td><b><tt>make setup lcc</tt></b>
<td>Will generate a different <tt>config.mk</tt>
that can be used to compile the library
with the Win32-LCC compiler.
</table>
</ul>
<p>
<li><b>Automatic detection of font drivers</b><br>
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.
<p>
The list of font drivers is located in the file
"<tt>freetype2/config/<em>system</em>/ftmodule.h</tt>", however
it can be regenerated on-demand. Adding a new module to the
FreeType source tree is thus as easy as:<p>
<ul>
<li>create a new directory in "<tt>freetype2/src</tt>" and
put the new driver's source code and sub-makefiles there.
<p>
<li>invoke the top <tt>Makefile</tt> with target
"<tt>modules</tt>" (as in "<tt>make modules</tt>"),
as this will automatically regenerate the list of
available drivers by detecting the new directory and
its content.
</ul>
<p>
</ul>
</ul>
<p><hr><p>
<h2>II. Host Platform Detection</h2>
<ul>
When the top-level <tt>Makefile</tt> is invoked, it looks for a
file named <tt>config.mk</tt> in the current directory. If this
file is found, it is used to build the library
(see <a href="library">Section III</a>).
<p>
Otherwise, the file <tt>freetype2/config/detect.mk</tt> is included
and parsed. Its purpose is to:<p>
<ul>
<li>Define the <tt>PLATFORM</tt> variable, which indicates
what is the currently detected platform. It is initially
set to the default value "<tt>ansi</tt>".
<p>
<li>It searches for a <tt>detect.mk</tt> file in all
subdirectories of <tt>freetype2/config</tt>. 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 <tt>PLATFORM</tt>
accordingly.
</ul>
<p>
This is illustrated by the following graphics :<p>
<center>
<img src="platform-detection.png" border=0>
</center>
<p>
Note that each system-specific <tt>detect.mk</tt> is in charge
of copying a valid configuration makefile to the current directory
(i.e. the one where <tt>make</tt> was invoked), depending on the
current targets. For example, the Win32 <tt>detect.mk</tt> will
be able to detect a "<tt>visualc</tt>" or "<tt>lcc</tt>" target,
as described in section I. Similarly, the OS/2 <tt>detect.mk</tt>
can detect targets like "<tt>borlandc</tt>", "<tt>watcom</tt>"
or "<tt>visualage</tt>", etc..
</ul>
<p><hr><p>
<h2>III. Building the library</h2>
<ul>
When the top-level <tt>Makefile</tt> is invoked and that it finds
a <tt>config.mk</tt> file in the current directory, it defines
the variable <tt>BUILD_FREETYPE</tt>, then includes and parses the
configuration sub-makefile.
<p>
The latter defines a number of important variables that describe
the compilation process to the build system. Among other things:<p>
<ul>
<li>the extension to be used for object files and library files
(i.e. <tt>.o</tt> and <tt>.a</tt> on Unix, <tt>.obj</tt>
and <tt>.lib</tt> on Dos-Windows-OS/2, etc..).
<p>
<li>the directory where all object files will be stored
(usually <tt>freetype2/obj</tt>), as well as the one
containing the library file (usually the same as for
objects).
<p>
<li>the command line compiler, and its compilation flags for
indicating a new include path (usually "<tt>-I</tt>"),
a new macro declaration (usually "<tt>-D</tt>") or
the target object file (usually "<tt>-o </tt>")
</ul>
<p>
Once these variable are defined, <tt>config.mk</tt> test for the
definition of the <tt>BUILD_FREETYPE</tt> variable. If it exists,
the makefile then includes "<tt>freetype2/config/freetype.mk</tt>"
which contains the rules required to compile the library.
<p>
Note that <tt>freetype.mk</tt> also scans the subdirectories of
"<tt>freetype2/src</tt>" for a file called "<tt>rules.mk</tt>".
Each <tt>rules.mk</tt> contains, as it names suggests, the rules
required to compile a given font driver or module.
<p>
Once all this parsing is done, the library can be compiled. Usually,
each font driver is compiled as a standalone object file (e.g.
<tt>sfnt.o</tt>, <tt>truetype.o</tt> and <tt>type1.o</tt>).
<p>
This process can be illustrated by the following graphics:<p>
<center>
<img src="library-compilation.png" border=0>
</center>
<p>
</ul>
<p><hr><p>
<h2>IIV. Managing the list of modules</h2>
<ul>
The makefile <tt>freetype.mk</tt> only determines how to compile
each one of the modules that are located in the sub-directories of
<tt>freetype2/src</tt>.
<p>
However, when the function <tt>FT_Init_FreeType</tt> is invoked at
the start of an application, it must create a new <tt>FT_Library</tt>
object, and registers all <em>known</em> font drivers to it by
repeatly calling <tt>FT_Add_Driver</tt>.
<p>
The list of <em>known</em> drivers is located in the file
"<tt>freetype2/config/<em>system</em>/ftmodule.h</tt>", and is used
exclusively by the internal function <tt>FT_Default_Drivers</tt>. The
list in <tt>ftmodule.h</tt> must be re-generated each time you add
or remove a module from <tt>freetype2/src</tt>.
<p>
This is normally performed by invoking the top-level <tt>Makefile</tt>
with the <tt>modules</tt> target, as in:<p>
<ul>
<tt>make modules</tt>
</ul>
<p>
This will trigger a special rule that will re-generate
<tt>ftmodule.h</tt>. To do so, the Makefile will parse all module
directories for a file called "<tt>module.mk</tt>". Each
<tt>module.mk</tt> is a tiny sub-Makefile used to add a single
module to the driver list.
<p>
This is illustrated by the following graphics:<p>
<center>
<img src="drivers-list.png" border=0>
</center>
<p>
Note that the new list of modules is displayed in a very human-friendly
way after a "<tt>make modules</tt>". Here's an example with the current
source tree (on 11 Jan 2000):<p>
<ul><pre>
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 --
</pre></ul>
</ul>
<p><hr><p>
<h2>V. Building the demonstration programs</h2>
<ul>
Several demonstration programs are located in the
"<tt>freetype2/demos</tt>" 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.
<p>
This section describes how the demonstration programs are compiled,
using the configuration <tt>freetype2/config.mk</tt> and their own
<tt>freetype2/demos/Makefile</tt>.
<p>
To compile the demonstration programs, <em>after the library</em>,
simply go to <tt>freetype2/demos</tt> then invoke GNU make with no
arguments.
<p>
The top-level Makefile will detect the <tt>config.mk</tt> in the
<em>upper</em> directory and include it. Because it doesn't define
the <tt>BUILD_FREETYPE</tt> variable, this will not force the
inclusion of <tt>freetype2/config/freetype.mk</tt> as described in
the previous section.
<p>
the <tt>Makefile</tt> will then include the makefile called
"<tt>freetype2/demos/graph/rules.mk</tt>". The graphics <tt>rules.mk</tt>
defines the rules required to compile the graphics sub-system.
<p>
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
<tt>freetype2/demos/config</tt>. Each such directory contains a file
named <tt>rules.mk</tt> which is in charge of:<p>
<ul>
<li>detecting wether the corresponding graphics library is
available at the time of compilation.
<p>
<li>if it is, alter the compilation rules to include the graphics
module in the build of the <tt>graph</tt> library.
</ul>
<p>
When the <tt>graph</tt> library is built in <tt>demos/obj</tt>, the
demonstration programs executables are generated by the top-level
Makefile.
<p>
This is illustrated by the following graphics:<p>
<center>
<img src="demo-programs.png" border="0">
</center>
</ul>
<p><hr>