Commit 3aeb4c05f27936a4d334a9b230ec7ee003ce11a1
2000-01-11T20:00:05
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..
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381
diff --git a/docs/internals/build-system.html b/docs/internals/build-system.html
new file mode 100644
index 0000000..b80f2c1
--- /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>
+© 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>
+
diff --git a/docs/internals/demo-programs.png b/docs/internals/demo-programs.png
new file mode 100644
index 0000000..692b277
Binary files /dev/null and b/docs/internals/demo-programs.png differ
diff --git a/docs/internals/drivers-list.png b/docs/internals/drivers-list.png
new file mode 100644
index 0000000..b5a5274
Binary files /dev/null and b/docs/internals/drivers-list.png differ
diff --git a/docs/internals/library-compilation.png b/docs/internals/library-compilation.png
new file mode 100644
index 0000000..a12505b
Binary files /dev/null and b/docs/internals/library-compilation.png differ
diff --git a/docs/internals/platform-detection.png b/docs/internals/platform-detection.png
new file mode 100644
index 0000000..9a504b4
Binary files /dev/null and b/docs/internals/platform-detection.png differ