subsys/win32k/freetype/docs/design/build-system.html

   1 <!doctype html public "-//w3c//dtd html 4.0 transitional//en">
   2 <html>
   3 <head>
   4    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   5    <meta name="Author" content="David Turner">
   6    <meta name="GENERATOR" content="Mozilla/4.5 [fr] (Win98; I) [Netscape]">
   7    <title>FreeType 2 Internals - I/O Frames</title>
   8    <basefont face="Georgia, Arial, Helvetica, Geneva">
   9    <style content="text/css">
  10      P { text-align=justify }
  11      H1 { text-align=center }
  12      H2 { text-align=center }
  13      LI { text-align=justify }
  14    </style>
  15 </head>
  16
  17 <body text="#000000"
  18       bgcolor="#FFFFFF"
  19       link="#0000EF"
  20       vlink="#51188E"
  21       alink="#FF0000">
  22
  23 <center>
  24 <h1>FreeType 2.0 Build System</h1></center>
  25
  26 <center>
  27 <h3>
  28 &copy; 2000 David Turner (<a href="fichier :///david@freetype.org">david@freetype.org</a>)<br>
  29 &copy; 2000 The FreeType Development Team
  30 (<a href="mailto:devel@freetype.org">devel@freetype.org</a>)
  31 </h3></center>
  32
  33 <center><table width=650><tr><td>
  34
  35 <p><hr WIDTH="100%"></p>
  36
  37 <h2>Table of Content</h2>
  38
  39 <center><table><tr><td>
  40 <p><font size="+1"><a href="#introduction">Introduction</a></font></p>
  41 <p><font size="+1"><a href="#features">I. Features & Background</a></font></p>
  42 <ul>
  43   <li><a href="#features-1">1. Convenience, not Requirement</a>
  44   <li><a href="#features-2">2. Compiler and platform independence</a>
  45   <li><a href="#features-3">3. Uses GNU Make</a>
  46   <li><a href="#features-4">4. Automatic host platform detection</a>
  47   <li><a href="#features-5">5. User-selectable builds</a>
  48   <li><a href="#features-6">6. Robustness</a>
  49   <li><a href="#features-7">7. Simple modules management</a>
  50 </ul>
  51 <p><font size="+1"><a href="#overview">II. Overview of the build process</a></font></p>
  52 <ul>
  53   <p><li><a href="#overview-1">1. Build setup</a>
  54   <ul>
  55     <li><a href="#overview-1-a">a. Default build setup</a>
  56     <li><a href="#overview-1-b">b. Selecting another build configuration</a>
  57   </ul>
  58   </p>
  59
  60   <li><a href="#overview-2">2. Library compilation</a>
  61 </ul>
  62 <p><font size="+1"><a href="#setup">III. Build setup details</a></font></p>
  63 <p><font size="+1"><a href="#compilation">IV. Library compilation details</a></font></p>
  64 <ul>
  65     <li><a href="#compilation-1">a. Compiling the <tt>ftsystem</tt> component</a>
  66     <li><a href="#compilation-2">b. Compiling the base layer and optional components</a>
  67     <li><a href="#compilation-3">c. Compiling the modules</a>
  68     <li><a href="#compilation-4">d. Compiling the <tt>ftinit</tt> component</a>
  69   </ul>
  70 </ul>
  71 </td></tr></table></center>
  72
  73 <hr><a name="introduction">
  74 <h2>Introduction:</h2>
  75
  76   <p>This document describes the new build system that was introduced
  77      with FreeType 2.</p>
  78
  79 <p><hr></p>
  80 <a name="features">
  81 <h2>I. Features and Background:</h2>
  82
  83   <p>The FreeType 2 build system is a set of Makefiles and sub-Makefiles that
  84       are used to build the library on a very large variety of systems easily.
  85       One of its main features are the following:</p>
  86
  87   <a name="features-1">
  88   <h3>1. Convenience, not Requirement</h3>
  89 <ul>
  90   <p>Even though the build system is rather sophisticated, it simply is a
  91      convenience that was written simply to allow the compilation of the
  92      FreeType 2 library on as many platforms as possible, as easily as
  93      possible. However, it is not a requirement and the library can be
  94      compiled manually or in a graphical IDE without using it, with minimal
  95      efforts</p>
  96
  97   <p>(for more information on this topic, see the <tt>BUILD</tt>
  98      document that comes with your release of FreeType, in its <em>Detailed
  99      Compilation Guide</em> section).</p>
 100 </ul>
 101
 102   <a name="features-2">
 103   <h3>2. Compiler and platform independence</h3>
 104 <ul>
 105   <p>The FreeType 2 build system can be used with any compiler, on any platform.
 106      It is independent of object file suffix, executable file suffix, directory
 107      separator convention (i.e. "/" or "\"), and compiler flags for path
 108      inclusion, macro definition, output naming, ansi compliance, etc..</p>
 109
 110   <p>Supporting a new compiler is trivial and only requires writing a minimal
 111      configuration sub-makefile that contains several Makefile variables
 112      definitions that are later used by the rest of the build system. This is
 113      described in details later in the document.</p>
 114 </ul>
 115
 116   <a name="features-3">
 117   <h3>3. Uses GNU Make</h3>
 118 <ul>
 119  <p>The build system works <em>exclusively</em> with <b>GNU Make</b>. Reason
 120     is that it is the only make utility that has all the features required to
 121     implement the build system as described below. Moreover, it is already
 122     ported to hundreds of various distinct platforms and is widely and
 123     freely available.</p>
 124
 125  <p>It also uses the native command line shell. <em>You thus
 126     don't need a Unix-like shell on your platform</em>.
 127     For example, FreeType 2 already compiles on Unix, Dos, Windows
 128     and OS/2 right "out of the box" (assuming you have GNU Make
 129     installed).</p>
 130
 131  <p>Finally, note that the build system is <em>specifically</em> designed
 132     for gnu make and will <em>fail</em> with any other make tool. We have
 133     <em>no plans</em> to support a different tools, as you'll rapidly
 134     understand by reading this document or looking at the sub-makefiles
 135     themselves.</p>
 136 </ul>
 137
 138   <a name="features-4">
 139   <h3>4. Automatic host platform detection</h3>
 140 <ul>
 141    <p>When you launch the build system for the first time, by simply invoking
 142       GNU make in the top-level directory, it automatically tries to detect
 143       your current platform in order to choose the best configuration
 144       sub-makefile available. It then displays what it found. If everything
 145       is ok, you can then launch compilation of the library, by invoking make
 146       a second time.</p>
 147
 148    <p>The following platforms are currently automatically detected:</p>
 149    <ul>
 150      <li>Dos (plain-dos, windows in Dos mode, or Dos session under OS/2)
 151      <li>Windows 95, 98 + Windows NT (a.k.a win32)
 152      <li>OS/2
 153      <li>Unix (uses Autoconf/Automake)
 154    </ul>
 155
 156    <p>Note that adding support for a new platform requires writing a minimal
 157       number of very small files, and simply putting them in a new sub-directory
 158       of <tt>freetype2/config</tt>.</p>
 159 </ul>
 160
 161   <a name="features-5">
 162   <h3>5. User-selectable builds</h3>
 163 <ul>
 164  <p>The platform auto-detection rules try to setup the build for a default
 165     compiler (<em>gcc</em> for most platforms), with default build options
 166     for the library (which normally is
 167     <em>"all features enable, no debugging"</em>), as well as the default
 168     list of modules (which is <em>"all modules in <tt>freetype2/src</tt>"</em>)</p>
 169
 170  <p>There are cases where it is important to specify a different compiler,
 171     different build options or simply a different module list. The FreeType 2
 172     build system is designed in such a way that all of this is easily possible
 173     from the command line, <em>without having to touch a single file</em>.
 174     The latter is crucial when dealing with projects that need specific
 175     builds of the library without modifying a single file from the FreeType
 176     distribution.</p>
 177
 178  <p>The exact mechanism and implementation to do this is described later in
 179     this document. It allows, for example, to compile FreeType with any of
 180     the following compilers on Win32: gcc, Visual C++, Win32-LCC.</p>
 181 </ul>
 182
 183   <a name="features-6">
 184   <h3>6. Robustness</h3>
 185 <ul>
 186   <p>The build system uses a single top-level Makefile that includes
 187      one or more sub-makefiles to build the entire library (base layer
 188      plus all modules).
 189
 190   <font color="red">
 191     To understand why this is important, we <em>strongly</em> recommend
 192     the following article to all of our readers:</font></p>
 193   <p>
 194     <center>
 195       <font size="+2"><a href="http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html">
 196       Recursive Make Considered Dangerous
 197       </a>
 198       </font>
 199     </center>
 200   </p>
 201
 202   <p>As an example, here's a short list of files that make up the
 203      build system. Note that each sub-makefile contains rules corresponding
 204      to a very specific purpose, and that they all use the "<tt>.mk</tt>"
 205      suffix:</p>
 206   <ul>
 207     <li><tt>freetype2/Makefile</tt>
 208     <li><tt>freetype2/config/detect.mk</tt>
 209     <li><tt>freetype2/config/freetype.mk</tt>
 210     <li><tt>freetype2/config/<em>&lt;system&gt;</em>/detect.mk</tt>
 211     <li><tt>freetype2/src/<em>&lt;module&gt;</em>/rules.mk</tt>
 212     <li><tt>freetype2/src/<em>&lt;module&gt;</em>/module.mk</tt>
 213   </ul>
 214
 215 </ul>
 216
 217   <a name="features-7">
 218   <h3>7. Simple Module Management</h3>
 219 <ul>
 220   <p>FreeType 2 has a very modular design, and is made of a core
 221      <em>base layer</em> that provides its high-level API as well as
 222      generic services used by one or more <em>modules</em>.
 223
 224      Most modules are used to support a specific font format (like TrueType
 225      or Type 1), and they are called <em>font drivers</em>. However, some of
 226      them do not support font files directly, but rather provide helper
 227      services to the font drivers.</p>
 228
 229   <p>FreeType 2 is designed so that adding modules at run-time is possible
 230      and easy. Similarly, we expect many more modules to come in the near
 231      future and wanted a build system that makes such additions to the
 232      source package itself dead easy.
 233
 234      Indeed, all source code (base + modules) is located in the
 235      <tt>freetype2/src</tt> directory hierarchy. And the build system is
 236      capable of re-generating automatically the list of known modules
 237      from the contents of this directory. Hence, adding a new font driver
 238      to the FreeType sources simply requires to:</p>
 239
 240   <ul>
 241     <li><p>Add a new sub-directory to <tt>freetype2/src</tt>
 242     <li><p>Re-launch the build system</p>
 243   </ul>
 244
 245   <p>There is thus no need to edit a source file</p>
 246 </ul>
 247
 248 <p><hr><p>
 249 <a name="overview">
 250 <h2>II. Overview of the build process(es):</h2>
 251
 252 <p>Before describing in details how the build system works, it is essential
 253    to give a few examples of how it's used. This section presents
 254    what's the build process is to the typical developer:</p>
 255
 256 <p>Compiling the library is normally done in two steps: the first one
 257    configures the build according to the current platform and possible
 258    additional parameters, while the second simply compiles the library with
 259    the information gathered in the configuration step.</p>
 260
 261 <a name="overview-1">
 262 <h3>1. Build Setup</h3>
 263
 264  <a name="overview-1-a">
 265  <h4>a. Default build setup</h4>
 266 <ul>
 267  <p>To configure the build, simply invoke gnu make from the top-level FreeType
 268     directory. This will launch a series of rules that will detect your current
 269     host platform, and choose a configuration file for you. It will then display
 270     what it found. For example, here's the output of typing the command "make"
 271     on a win32 platform (assuming this calls GNU make):</p>
 272
 273 <pre><font color="blue">
 274     <font color="purple">C:\FreeType> make</font>
 275
 276     FreeType build system -- automatic system detection
 277
 278     The following settings are used:
 279
 280       platform                     win32
 281       compiler                     gcc
 282       configuration directory      ./config/win32
 283       configuration rules          ./config/win32/w32-gcc.mk
 284
 285     If this does not correspond to your system or settings please remove the file
 286     'config.mk' from this directory then read the INSTALL file for help.
 287
 288     Otherwise, simply type 'make' again to build the library.
 289
 290     <font color="purple">C:\FreeType></font>
 291 </font></pre>
 292
 293  <p>Note that this step copies the selected configuration file (here
 294     <tt>./config/win32/w32-gcc.mk</tt>) to <em>the current directory</em>, under
 295     the name <tt><b>config.mk</b></tt>. This file contains data that is used
 296     to drive the library compilation of the second step. It correspond to
 297     the platform and compiler selected by the auto-detection phase.</p>
 298
 299  <p>Note that you can re-generate the <tt><b>config.mk</b></tt> file anytime
 300     by invoking <tt>make setup</tt> whenever you need it, even when the file is
 301     already present in the current directory.</p>
 302
 303  <p>Finally, if your platform is not correctly detected, the build system will
 304     display and use configuration information for the virtual "ansi" platform.
 305     </p>
 306 </ul>
 307  <a name="overview-1-b">
 308  <h4>b. Selecting another build configuration</h4>
 309 <ul>
 310  <p>You may not be really satisfied by the configuration file selected by the
 311     auto-detection routines. Typically, you might be using a compiler that is
 312     not the default one for your platform. It is however possible to re-launch
 313     the build setup phase with an additional argument, used to specify a
 314     different compiler/config file. For example, you can type the following
 315     commands on Win32 systems:</p>
 316
 317  <p align=center><table width="80%"  cellpadding=10><tr valign=top><td>
 318  <p><b><tt>make&nbsp;setup</tt></b></p>
 319  </td><td>
 320  <p>re-run the platform detection phase, and select the default compiler for it.
 321  On Win32, this is <em>gcc</em>.</p>
 322  </td></tr><tr valign=top><td>
 323  <p><b><tt>make&nbsp;setup&nbsp;visualc</tt></b></p>
 324  </td><td>
 325  <p>re-run the platform detection phase, and select a config file that
 326     corresponds to the <em>Visual C++</em> compiler</p>
 327  </td></tr><tr valign=top><td>
 328  <p><b><tt>make&nbsp;setup&nbsp;lcc</tt></b></p>
 329  </td><td>
 330  <p>re-run the platform detection phase, and select a config file that
 331     corresponds to the <em>Win32-LCC</em> compiler</p>
 332  </td></tr></table>
 333  </p>
 334
 335  <p>Note that a specific configuration is selected with a command that
 336     looks like : <tt><b>make&nbsp;setup&nbsp;<em>compiler</em></b></tt>,
 337     where the <em><tt>compiler</tt></em> keywords depends on the platform.
 338     Moreover, each one of them corresponds to a specific configuration
 339     sub-makefile that is copied as <b><tt>config.mk</tt></b> in the current
 340     directory.</p>
 341 </ul>
 342
 343
 344 <a name="overview-2">
 345 <h3>2. Library compilation</h3>
 346
 347   <p>Once you're satisfied with the version of <b><tt>config.mk</tt></b> that
 348      has been copied to your current directory, you can simply re-invoke
 349      gnu make <em>with no arguments</em>. The top-level Makefile will
 350      automatically detect the config sub-makefile in the current directory,
 351      and use it to drive the library compilation. The latter can be seen
 352      as a series of different steps decribed here:</p>
 353
 354   <ul>
 355     <li><p><b>Compiling the <tt>ftsystem</tt> component</b><br><ul>
 356         It encapsulates all low-level operations (memory management +
 357         i/o access) for the library. Its default version, located in
 358         <tt>./src/base/ftsystem.c</tt> uses the ANSI C library but
 359         system-specific implementations are also available to
 360         improve performance (e.g. memory-mapped files on Unix).
 361         </ul></p>
 362
 363     <li><p><b>Compiling the <em>base layer</em> and optional components</b><br><ul>
 364         They provide the library's high-level API as well as various useful
 365         routines for client applications. Many features of the base layer can
 366         be activated or not depending on a configuration file named
 367         <tt>ftoption.h</tt>
 368         </ul></p>
 369
 370     <li><p><b>Compiling the <em>modules</em></b><br><ul>
 371         Each module is used to support a specific font format (it is then
 372         called a <em>font driver</em>), or to provide helper services to
 373         the drivers (e.g. the auto-hinter). They are all located in
 374         sub-directories of <tt>./src</tt>, like <tt>./src/truetype</tt>,
 375         <tt>./src/type1</tt>.
 376         </ul></p>
 377
 378     <li><p><b>Compiling the <tt>ftinit</tt> component</b><br><ul>
 379         This one is in charge of implementing <tt>FT_Init_FreeType</tt>,
 380         the library initialisation routine. It also selects what modules
 381         are activated when a new library instance is created.
 382         </ul></p>
 383   </ul>
 384 <p><hr><p>
 385 <a name="setup">
 386 <h2>II. Details of the build setup.</h2>
 387
 388  <p>When the top-level <tt>Makefile</tt> is invoked, it looks for a
 389     file named <b><tt>config.mk</tt></b> in the <em>current directory</em>.
 390     If this file is found, it is used directly to build the library
 391     (skip to <a href="library">Section III</a> for details then).</p>
 392
 393  <p>Otherwise, the file <b><tt>./config/detect.mk</tt></b> is included
 394     by the top-level <tt>Makefile</tt> and parsed. Its purpose is to drive the
 395     platform-detection phase, by:</p>
 396
 397  <ul>
 398      <li><p>Defining the <tt>PLATFORM</tt> variable, which indicates
 399             what the currently detected platform is. It is initially
 400             set to the default value "<tt><b>ansi</b></tt>".
 401             </p>
 402
 403      <li><p>Searching for a <tt>detect.mk</tt> file in <em>all
 404             subdirectories</em> of <b><tt>./config</tt></b>.
 405             Each such file is included and parsed. Each of these files must
 406             try to detect if the host platform is a system it knows
 407             about. If so, it changes the value of the <tt>PLATFORM</tt> variable
 408             accordingly.</p>
 409
 410      <li><p>Copying the selected configuration submakefile to the current directory
 411             under the name <tt><b>config.mk</b></tt>.</p>
 412  </ul>
 413  <p>This is illustrated by the following graphics :</p>
 414     <p><center>
 415         <img src="platform-detection.png" border=0>
 416     </center></p>
 417
 418  <p>Each system-specific <b><tt>detect.mk</tt></b> works as follows:</p>
 419  <ul>
 420    <li><p>It checks that the value of <tt>PLATFORM</tt> is currently set
 421           to <b>ansi</b>, which indicates that no platform was detected
 422           for now. If this isn't true, it doesn't do anything</p>
 423
 424    <li><p>Otherwise, it runs a series of test to see wether it is on a
 425           system it knows about. Here are a few examples of tests:</p>
 426
 427        <p><center><table width="80%" cellpadding=5><tr valign=top><td>
 428        <em><b>Unix</b></em>
 429        </td><td>
 430        <p>checks for a file named <tt>/sbin/init</tt>, and runs, when it found
 431        it, a 'configure' script to generate the relevant config sub-makefile</p>
 432        </td></tr><tr valign=top><td>
 433        <em><b>Dos</b></em>
 434        </td><td>
 435        <p>checks for the <tt>COMSPEC</tt> environment variable, then tries to
 436        run the "<tt>ver</tt>" command on the current shell to check that there
 437        is a "Dos" substring in its output; if not, it tries to find the
 438        substring "<tt>MDOS\COMMAND</tt>" in <tt>COMSPEC</tt>, which indicates
 439        a Dos session under OS/2.</p>
 440        </td></tr><tr valign=top><td>
 441        <em><b>Win32</b></em>
 442        </td><td>
 443        <p>if the environment variable <tt>OS</tt> is defined and has the value
 444        <tt>Windows_NT</tt>, or if <tt>COMSPEC</tt> is defined and the
 445        "<tt>ver</tt>" returns a string that contains <tt>Windows</tt> in it,
 446        we're on a Win32 system.</p>
 447        </td></tr></table></center>
 448        </p>
 449
 450    <li><p>It sets the value of <tt>PLATFORM</tt> to a new value corresponding
 451           to its platform.</p>
 452
 453    <li><p>It then tries to select a configuration
 454           sub-makefile, depending on the current platform and any optional
 455           make target (like "visualc" or "devel", etc..). Note that it can
 456           even generate the file, as on Unix through Autoconf/Automake.</p>
 457
 458    <li><p>It copies the selected configuration sub-makefile to the current
 459           directory, under the name <tt><b>config.mk</b></tt>
 460  </ul>
 461
 462  <p>If one wants to support a new platform in the build system, it simply needs
 463     to provide:</p>
 464
 465  <ul>
 466     <li>A new subdirectory, in <tt>./config</tt>, with a file named
 467         <tt>detect.mk</tt> in it, containing relevant checks for the system.
 468
 469     <li>One or more configuration sub-makefiles that will get copied to
 470         <tt>config.mk</tt> at build setup time. You can use the one in
 471         <tt>./config/ansi/config.mk</tt> as a template.
 472  </ul>
 473
 474  <p>Similary, supporting a new compiler on an existing system simply means:</p>
 475  <ul>
 476     <li>Writing a new config sub-makefile that contains definitions used to
 477         specify the compiler and flags for the build.
 478
 479     <li>Change your <tt>./config/<em>system</em>/detect.mk</tt> to recognize
 480         a new optional build target that will copy your new config sub-makefile
 481         instead of the default one.
 482  </ul>
 483
 484
 485 <p><hr><p>
 486 <h2>III. Details of the library compilation.</h2>
 487
 488 <p>When the top-level Makefile is invoked, it looks for a file named
 489    <tt>config.mk</tt> in the current directory. If one is found, it
 490    defines the <tt>BUILD_FREETYPE</tt> variable, then includes and parses it.
 491    The structure of this file is the following:
 492    </p>
 493
 494 <ul>
 495   <li><p>First, it defines a series of Make variables that describe
 496          the host environment, like the compiler, compilation flags,
 497          object file suffix, the directory where all object files are
 498          placed, etc..</p>
 499
 500   <li><p>If <tt>BUILD_FREETYPE</tt> is defined, it includes the file
 501          <tt><b>./config/freetype.mk</b></tt>, which is in charge of
 502          defining all the rules used to build the library object files.
 503          (The test is useful to use the <tt>config.mk</tt> file to
 504           compile other projects that rely on FreeType 2, like its
 505           demonstration programs).</p>
 506
 507   <li><p>Finally, it defines the rule(s) used to link FreeType 2 object files
 508          into a library file (e.g. <tt>libfreetype.a</tt>, <tt>freetype.lib</tt>,
 509          <tt>freetype.dll</tt>, ...). Unfortunately, the command line interface of link tools is
 510          a <em>lot less</em> standardized than those of compilers, which
 511          explains why this rule must be defined in the system-specific
 512          <tt>config.mk</tt>.</p>
 513 </ul>
 514
 515 <p>The following is an explanation of what <tt><b>./config/freetype.mk</b></tt>
 516    does to build the library objects:
 517    </p>
 518
 519 <h4>a. Include paths</h4>
 520 <ul>
 521  <p>To avoid namespace pollution, the <tt><em>freetype</em></tt> directory prefix
 522     is used to include all public header files of the library. This means
 523     that a client application will typically use lines like:</p>
 524
 525 <pre><font color="blue">
 526     #include &lt;freetype/freetype.h&gt;
 527     #include &lt;freetype/ftglyph.h&gt;
 528 </font></pre>
 529
 530  <p>to include one the FreeType 2 public header files. <tt>freetype.mk</tt>
 531     uses a variable named <tt><b>INCLUDES</b></tt> to hold the inclusion
 532     paths list, and thus starts by adding <tt>./include</tt> to it. However,
 533     nothing prevents
 534
 535  <p><tt>freetype.mk</tt> uses a variable named <tt><b>INCLUDES</b></tt>
 536     to hold directory inclusion-path to be used when compiling the library.
 537     It always add <tt>./include</tt> to this variable, which means
 538
 539 </ul>
 540
 541 <h4>b. Configuration header files:</h4>
 542 <ul>
 543   <p>Three header files used to configure the compilation of the
 544      FreeType 2 library. Their default versions are all located in the
 545      directory <tt><b>./include/freetype/config/</b></tt>, even though
 546      project specific versions can be provided on a given build, as
 547      described later:</p>
 548
 549   <ul>
 550     <p><b><tt>#include &lt;freetype/config/ftoption.h&gt;</tt></b><br><ul>
 551         This file contains a set of configuration macro definitions that
 552         can be toggled to activate or deactivate certain features of the
 553         library. By changing one of these definitions, it is possible to
 554         compile <em>only the features that are needed</em> for a specific
 555         project. Note that by default, all options are enabled.
 556         <br><br>
 557         You might need to provide an alternative version of <tt>ftoption.h</tt>
 558         for one of your own projects.
 559         </ul></p>
 560
 561     <p><b><tt>#include &lt;freetype/config/ftconfig.h&gt;</tt></b><br><ul>
 562         This file includes <tt>ftoption.h</tt> but also contains some automatic
 563         macro definitions used to indicate some important system-specific
 564         features (e.g: word size in bytes, DLL export prefix macros, etc..).
 565         <br><br>
 566         You shouldn't normally need to change or provide an alternative
 567         version of this file.
 568         </ul></p>
 569
 570
 571     <p><b><tt>#include &lt;freetype/config/ftmodule.h&gt;</tt></b><br><ul>
 572         This file is very special, as it is normally machine-generated, and
 573         used by the <tt>ftinit</tt> component that is described below. To
 574         understand it, one must reminds that FreeType 2 has an extremely
 575         modular design and that it's possible to change, <em>at run-time</em>,
 576         the modules it's using. The <tt>ftmodule.h</tt> file simply contains
 577         the list of modules that are registered with each new instance of
 578         the library.
 579         <br><br>
 580         Note that the file can be re-generated automatically by invoking
 581         <tt>make setup</tt> from the top-level directory. The re-generated
 582         list contains all the modules that were found in subdirectories of
 583         <tt>./src</tt>.
 584         </ul></p>
 585   </ul>
 586
 587   <p>Note that we strongly advise you to avoid modifying the config files
 588      within the FreeType 2 source directory hierarchy. Rather, it's possible
 589      to specify alternative versions through the help of a build-specific
 590      include path that is include before <tt>./include</tt> in the inclusion
 591      path.</p>
 592
 593   <p>For example, imagine that your platform, named <em>foo</em>, needs a
 594      specific version of <tt>ftoption.h</tt>
 595 </ul>
 596
 597   <h4>a. Compiling the <b><tt>ftsystem</tt></b> component:</h4>
 598 <ul>
 599   <p>FreeType 2 encapsulates all low-level operations (i.e. memory management
 600      and i/o access) within a single component called <tt><b>ftsystem</b></tt>.
 601      Its default implementation uses the <em>ANSI C Library</em> and is located
 602      in <tt>./src/base/ftsystem.c</tt>.</p>
 603
 604   <p>However, some alternate, system-specific, implementations of
 605      <tt>ftsystem</tt> are provided with the library in order to support more
 606      efficient and advanced features. As an example, the file
 607      <tt>./config/unix/ftsystem.c</tt> is an implementation that
 608      uses memory-mapped files rather than the slow ANSI <tt>fopen</tt>,
 609      <tt>fread</tt> and <tt>fseek</tt>, boosting performance significantly.</p>
 610
 611   <p>The build system is thus capable of managing alternate implementations
 612      of <tt>ftsystem</tt></p>
 613 </ul>
 614
 615   <h4>b. Compiling the base layer and optional components:</h4>
 616 <ul>
 617   <p>The high-level API of the library is provided by a component called the
 618      <em>base layer</em>, whose source is located in <tt>./src/base</tt>. This
 619      directory also contains one or more components that are optional, i.e.
 620      that are not required by the library but provide valuable routines to
 621      client applications.</p>
 622
 623   <p>The features of the base library and other components are selected through
 624      a single configuration file named
 625      <tt><b>./include/freetype/config/ftoption.h</b></tt>. It contains a list
 626      of commented configuration macro definitions, that can be toggled to
 627      activate or de-activate a certain feature or component at build time.</p>
 628
 629   <p>For example, the code in <tt>./src/base/ftdebug.c</tt> will be compiled
 630      only if one of these two macros are defined in <tt>ftoption.h</tt>:
 631      <tt>FT_DEBUG_LEVEL_ERROR</tt> or <tt>FT_DEBUG_LEVEL_TRACE</tt></p>
 632 </ul>
 633
 634   <h4>c. Compiling the modules:</h4>
 635 <ul>
 636   <p>Once the base layer is completed, the build system starts to compile each
 637      additional module independently. These are simply defined as all source
 638      code located in a sub-directory of <tt>./src</tt> that contains a file
 639      named <tt><b>rules.</b></tt>, for example:
 640      <tt>src/sfnt</tt>, <tt>src/truetype</tt>, <tt>src/type1</tt>, ...</p>
 641
 642   <p>The <tt><b>rules.</b></tt> file simply contains directives used by the
 643      build system to compile the corresponding module into a single object
 644      file.</p>
 645 </ul>
 646
 647   <h4>d. Compiling the <b><tt>ftinit</tt></b> component:</h4>
 648 <ul>
 649   <p>The file <tt><b>./src/base/ftinit.c</b></tt> is special because it is used
 650      to implement the library initialisation function <tt>FT_Init_FreeType</tt>.
 651      </p>
 652 </ul>
 653
 654   <p>Typically, you will end up with all object files, as well as the
 655      corresponding  library file, residing in the <tt>freetype2/obj</tt>
 656      directory.</p>
 657
 658
 659 <h3>1. Purpose of the configuration sub-makefile</h3>
 660
 661 <h3>2. Managing module dependencies</h3>
 662
 663 <h3>3. </h3>
 664
 665 <p><hr><p>
 666 <a name="modules">
 667 <h2>IV. Managing the modules list</h2>
 668
 669 <p><hr><p>
 670     The build system features some important points, which are all detailed
 671     in the following sections:<p>
 672     <ul>
 673         <li><b>Automatic host platform detection</b><br>
 674             The first time the top <tt>Makefile</tt> is invoked, it will
 675             run a series of rules to detect your platform. It will then
 676             create a system-specific configuration sub-Makefile in the
 677             current directory, called <b><tt>config.mk</tt></b>. You can now
 678             invoke the top <tt>Makefile</tt> a second time to compile the
 679             library directly.
 680             <p>
 681             The configuration sub-makefile can be regenerated any time
 682             by invoking "<tt>make setup</tt>", which will re-run the
 683             detection rules even if a <tt>config.mk</tt> is already present.
 684             <p>
 685
 686
 687         <li><b>User-selectable builds</b><br>
 688             <p>
 689
 690
 691
 692         <li><b>Automatic detection of font drivers</b><br>
 693             FreeType is made of a "base" layer that invokes several
 694             separately-compiled modules. Each module is a given
 695             font driver, in charge of supporting a given font format.
 696             <p>
 697             The list of font drivers is located in the file
 698             "<tt>freetype2/config/<em>system</em>/ftmodule.h</tt>", however
 699             it can be regenerated on-demand. Adding a new module to the
 700             FreeType source tree is thus as easy as:<p>
 701             <ul>
 702                 <li>create a new directory in "<tt>freetype2/src</tt>" and
 703                     put the new driver's source code and sub-makefiles there.
 704                     <p>
 705
 706                 <li>invoke the top <tt>Makefile</tt> with target
 707                     "<tt>modules</tt>" (as in "<tt>make modules</tt>"),
 708                     as this will automatically regenerate the list of
 709                     available drivers by detecting the new directory and
 710                     its content.
 711             </ul>
 712             <p>
 713     </ul>
 714 </ul>
 715
 716 <p><hr><p>
 717
 718 <h2>II. Host Platform Detection</h2>
 719 <ul>
 720     When the top-level <tt>Makefile</tt> is invoked, it looks for a
 721     file named <tt>config.mk</tt> in the current directory. If this
 722     file is found, it is used to build the library
 723     (see <a href="library">Section III</a>).
 724     <p>
 725     Otherwise, the file <tt>freetype2/config/detect.mk</tt> is included
 726     and parsed. Its purpose is to:<p>
 727     <ul>
 728         <li>Define the <tt>PLATFORM</tt> variable, which indicates
 729             what is the currently detected platform. It is initially
 730             set to the default value "<tt>ansi</tt>".
 731             <p>
 732
 733         <li>It searches for a <tt>detect.mk</tt> file in all
 734             subdirectories of <tt>freetype2/config</tt>. Each such
 735             file is included and parsed. Each of these files must
 736             try to detect if the host platform is a system it knows
 737             about. If so, it changes the value of the <tt>PLATFORM</tt>
 738             accordingly.
 739     </ul>
 740     <p>
 741     This is illustrated by the following graphics :<p>
 742     <center>
 743         <img src="platform-detection.png" border=0>
 744     </center>
 745     <p>
 746     Note that each system-specific <tt>detect.mk</tt> is in charge
 747     of copying a valid configuration makefile to the current directory
 748     (i.e. the one where <tt>make</tt> was invoked), depending on the
 749     current targets. For example, the Win32 <tt>detect.mk</tt> will
 750     be able to detect a "<tt>visualc</tt>" or "<tt>lcc</tt>" target,
 751     as described in section I. Similarly, the OS/2 <tt>detect.mk</tt>
 752     can detect targets like "<tt>borlandc</tt>", "<tt>watcom</tt>"
 753     or "<tt>visualage</tt>", etc..
 754 </ul>
 755
 756 <p><hr><p>
 757
 758 <h2>III. Building the library</h2>
 759 <ul>
 760     When the top-level <tt>Makefile</tt> is invoked and that it finds
 761     a <tt>config.mk</tt> file in the current directory, it defines
 762     the variable <tt>BUILD_FREETYPE</tt>, then includes and parses the
 763     configuration sub-makefile.
 764     <p>
 765     The latter defines a number of important variables that describe
 766     the compilation process to the build system. Among other things:<p>
 767     <ul>
 768         <li>the extension to be used for object files and library files
 769             (i.e. <tt>.o</tt> and <tt>.a</tt> on Unix, <tt>.obj</tt>
 770              and <tt>.lib</tt> on Dos-Windows-OS/2, etc..).
 771             <p>
 772
 773         <li>the directory where all object files will be stored
 774             (usually <tt>freetype2/obj</tt>), as well as the one
 775             containing the library file (usually the same as for
 776             objects).
 777             <p>
 778
 779         <li>the command line compiler, and its compilation flags for
 780             indicating a new include path (usually "<tt>-I</tt>"),
 781             a new macro declaration (usually "<tt>-D</tt>") or
 782             the target object file (usually "<tt>-o&nbsp;</tt>")
 783     </ul>
 784     <p>
 785     Once these variable are defined, <tt>config.mk</tt> test for the
 786     definition of the <tt>BUILD_FREETYPE</tt> variable. If it exists,
 787     the makefile then includes "<tt>freetype2/config/freetype.mk</tt>"
 788     which contains the rules required to compile the library.
 789     <p>
 790     Note that <tt>freetype.mk</tt> also scans the subdirectories of
 791     "<tt>freetype2/src</tt>" for a file called "<tt>rules.mk</tt>".
 792     Each <tt>rules.mk</tt> contains, as it names suggests, the rules
 793     required to compile a given font driver or module.
 794     <p>
 795     Once all this parsing is done, the library can be compiled. Usually,
 796     each font driver is compiled as a standalone object file (e.g.
 797     <tt>sfnt.o</tt>, <tt>truetype.o</tt> and <tt>type1.o</tt>).
 798     <p>
 799     This process can be illustrated by the following graphics:<p>
 800     <center>
 801         <img src="library-compilation.png" border=0>
 802     </center>
 803     <p>
 804 </ul>
 805
 806 <p><hr><p>
 807
 808 <h2>IIV. Managing the list of modules</h2>
 809 <ul>
 810     The makefile <tt>freetype.mk</tt> only determines how to compile
 811     each one of the modules that are located in the sub-directories of
 812     <tt>freetype2/src</tt>.
 813     <p>
 814     However, when the function <tt>FT_Init_FreeType</tt> is invoked at
 815     the start of an application, it must create a new <tt>FT_Library</tt>
 816     object, and registers all <em>known</em> font drivers to it by
 817     repeatly calling <tt>FT_Add_Driver</tt>.
 818     <p>
 819     The list of <em>known</em> drivers is located in the file
 820     "<tt>freetype2/config/<em>system</em>/ftmodule.h</tt>", and is used
 821     exclusively by the internal function <tt>FT_Default_Drivers</tt>. The
 822     list in <tt>ftmodule.h</tt> must be re-generated each time you add
 823     or remove a module from <tt>freetype2/src</tt>.
 824     <p>
 825     This is normally performed by invoking the top-level <tt>Makefile</tt>
 826     with the <tt>modules</tt> target, as in:<p>
 827     <ul>
 828         <tt>make modules</tt>
 829     </ul>
 830     <p>
 831     This will trigger a special rule that will re-generate
 832     <tt>ftmodule.h</tt>. To do so, the Makefile will parse all module
 833     directories for a file called "<tt>module.mk</tt>". Each
 834     <tt>module.mk</tt> is a tiny sub-Makefile used to add a single
 835     module to the driver list.
 836     <p>
 837     This is illustrated by the following graphics:<p>
 838     <center>
 839         <img src="drivers-list.png" border=0>
 840     </center>
 841     <p>
 842     Note that the new list of modules is displayed in a very human-friendly
 843     way after a "<tt>make modules</tt>". Here's an example with the current
 844     source tree (on 11 Jan 2000):<p>
 845     <ul><pre>
 846 Regenerating the font drivers list in ./config/unix/ftmodule.h
 847 * driver:  sfnt      ( pseudo-driver for TrueType & OpenType formats )
 848 * driver:  truetype  ( Windows/Mac font files with extension *.ttf or *.ttc )
 849 * driver:  type1     ( Postscript font files with extension *.pfa or *.pfb )
 850 -- done --
 851     </pre></ul>
 852
 853 </ul>
 854
 855 <p><hr><p>
 856
 857 <h2>V. Building the demonstration programs</h2>
 858 <ul>
 859     Several demonstration programs are located in the
 860     "<tt>freetype2/demos</tt>" directory hierarchy. This directory also
 861     includes a tiny graphics sub-system that is able to blit glyphs to
 862     a great variety of surfaces, as well as display these in various
 863     graphics libraries or windowed environments.
 864     <p>
 865     This section describes how the demonstration programs are compiled,
 866     using the configuration <tt>freetype2/config.mk</tt> and their own
 867     <tt>freetype2/demos/Makefile</tt>.
 868     <p>
 869     To compile the demonstration programs, <em>after the library</em>,
 870     simply go to <tt>freetype2/demos</tt> then invoke GNU make with no
 871     arguments.
 872     <p>
 873     The top-level Makefile will detect the <tt>config.mk</tt> in the
 874     <em>upper</em> directory and include it. Because it doesn't define
 875     the <tt>BUILD_FREETYPE</tt> variable, this will not force the
 876     inclusion of <tt>freetype2/config/freetype.mk</tt> as described in
 877     the previous section.
 878     <p>
 879     the <tt>Makefile</tt> will then include the makefile called
 880     "<tt>freetype2/demos/graph/rules.mk</tt>". The graphics <tt>rules.mk</tt>
 881     defines the rules required to compile the graphics sub-system.
 882     <p>
 883     Because the graphics syb-system is also designed modularly, it is able
 884     to use any number of "modules" to display surfaces on the screen.
 885     The graphics modules are located in the subdirectories of
 886     <tt>freetype2/demos/config</tt>. Each such directory contains a file
 887     named <tt>rules.mk</tt> which is in charge of:<p>
 888     <ul>
 889         <li>detecting wether the corresponding graphics library is
 890             available at the time of compilation.
 891             <p>
 892         <li>if it is, alter the compilation rules to include the graphics
 893             module in the build of the <tt>graph</tt> library.
 894     </ul>
 895     <p>
 896     When the <tt>graph</tt> library is built in <tt>demos/obj</tt>, the
 897     demonstration programs executables are generated by the top-level
 898     Makefile.
 899     <p>
 900     This is illustrated by the following graphics:<p>
 901     <center>
 902         <img src="demo-programs.png" border="0">
 903     </center>
 904 </ul>
 905
 906 <p><hr>
 907 </td></tr></table></center>
 908 </body>
 909 </html>
 910