ref: 3aeb4c05f27936a4d334a9b230ec7ee003ce11a1
parent: 426b20af0295158039376dde713bc9985f57f7ab
author: David Turner <[email protected]>
date: Tue Jan 11 15:00:05 EST 2000
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..
--- /dev/null
+++ b/docs/internals/build-system.html
@@ -1,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 :///[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>
+
binary files /dev/null b/docs/internals/demo-programs.png differ
binary files /dev/null b/docs/internals/drivers-list.png differ
binary files /dev/null b/docs/internals/library-compilation.png differ
binary files /dev/null b/docs/internals/platform-detection.png differ