Added a new document to docs/internals that describes
the Build System clearly. I hope this will help other developers in adding platform-detection makefiles for additional systems..
This commit is contained in:
David Turner
parent
426b20af02
commit
3aeb4c05f2
359
docs/internals/build-system.html
Normal file
359
docs/internals/build-system.html
Normal file
@ -0,0 +1,359 @@
|
||||
<!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 :///david@freetype.org">david@freetype.org</a>)<br>
|
||||
© 2000 The FreeType Development Team
|
||||
(<a href="mailto:devel@freetype.org">devel@freetype.org</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>
|
||||
|
||||
BIN
docs/internals/demo-programs.png
Normal file
BIN
docs/internals/demo-programs.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 2.9 KiB |
BIN
docs/internals/drivers-list.png
Normal file
BIN
docs/internals/drivers-list.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 1.9 KiB |
BIN
docs/internals/library-compilation.png
Normal file
BIN
docs/internals/library-compilation.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 1.8 KiB |
BIN
docs/internals/platform-detection.png
Normal file
BIN
docs/internals/platform-detection.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 1.8 KiB |
Loading…
Reference in New Issue
Block a user