From 3aeb4c05f27936a4d334a9b230ec7ee003ce11a1 Mon Sep 17 00:00:00 2001
From: David Turner <david@freetype.org>
Date: Tue, 11 Jan 2000 20:00:05 +0000
Subject: [PATCH] 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..

---
 docs/internals/build-system.html       | 359 +++++++++++++++++++++++++
 docs/internals/demo-programs.png       | Bin 0 -> 2935 bytes
 docs/internals/drivers-list.png        | Bin 0 -> 1899 bytes
 docs/internals/library-compilation.png | Bin 0 -> 1894 bytes
 docs/internals/platform-detection.png  | Bin 0 -> 1808 bytes
 5 files changed, 359 insertions(+)
 create mode 100644 docs/internals/build-system.html
 create mode 100644 docs/internals/demo-programs.png
 create mode 100644 docs/internals/drivers-list.png
 create mode 100644 docs/internals/library-compilation.png
 create mode 100644 docs/internals/platform-detection.png
diff --git a/docs/internals/build-system.html b/docs/internals/build-system.html
new file mode 100644
index 000000000..b80f2c160
--- /dev/null
+++ b/docs/internals/build-system.html
@@ -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>
+&copy; 2000 David Turner (<a href="fichier :///david@freetype.org">david@freetype.org</a>)<br>
+&copy; 2000 The FreeType Development Team
+(<a href="mailto:devel@freetype.org">devel@freetype.org</a>)
+</h3></center>
+
+<p><br>
+<hr WIDTH="100%">
+<br>&nbsp;
+<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&nbsp;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&nbsp;setup&nbsp;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&nbsp;setup&nbsp;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&nbsp;</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>
+
diff --git a/docs/internals/demo-programs.png b/docs/internals/demo-programs.png
new file mode 100644
index 0000000000000000000000000000000000000000..692b27771781184bb857b32b83645dc2934e8da8
GIT binary patch
literal 2935
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

literal 0
HcmV?d00001

diff --git a/docs/internals/drivers-list.png b/docs/internals/drivers-list.png
new file mode 100644
index 0000000000000000000000000000000000000000..b5a52748a5a98963738c880f8139ab42b3b8a82b
GIT binary patch
literal 1899
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

literal 0
HcmV?d00001

diff --git a/docs/internals/library-compilation.png b/docs/internals/library-compilation.png
new file mode 100644
index 0000000000000000000000000000000000000000..a12505b01ec8bc86a90dbe21201a63ae268235dc
GIT binary patch
literal 1894
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

literal 0
HcmV?d00001

diff --git a/docs/internals/platform-detection.png b/docs/internals/platform-detection.png
new file mode 100644
index 0000000000000000000000000000000000000000..9a504b45e7ea7c58bfb1588e3176ca6b40de9e42
GIT binary patch
literal 1808
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

literal 0
HcmV?d00001


`make setup` +	Will generate a `config.mk` that + can be used to compile the library with + `gcc` (which is the default + compiler for most supported platforms). + +
`make setup visualc` +	Will generate a different `config.mk` + that can be used to compile the library + with the Visual C++ command-line compiler. + +
`make setup lcc` +	Will generate a different `config.mk` + that can be used to compile the library + with the Win32-LCC compiler. +