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 @@
+
+
+
+
+
+
+ FreeType 2 Internals - I/O Frames
+
+
+
+
+
+
+
+FreeType 2.0 Build System
+
+
+
+
+
+
+
+Introduction:
+
+ This document describes the new build system that was introduced
+ with FreeType 2.
+
+
+
+
+
I. Features and Background:
+
+ 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:
+
+ - The build system is made of a single Makefile,
+ dispatched over several directories with the help of the
+ include directive. Technically speaking, it is
+ composed of the top-level "freetype2/Makefile"
+ which includes several other sub-Makefiles, whose extension
+ is always ".mk". Examples are:
+
+ freetype2/config/freetype.mk
+ freetype2/config/system/detect.mk
+ freetype2/src/module/rules.mk
+ etc..
+
+
+
+ We strongly recommend the following article:
+
+
+ Recursive Make Considered Dangerous
+
+
+
+
+ To understand why such a layout was chosen.
+
+
+
- The build system works exclusively with
+ GNU Make. 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.
+
+ You don't need a Unix-like shell on your platform.
+ For example, FreeType 2 already compiles on Unix, Dos, Windows
+ and OS/2 right "out of the box" (assuming you have GNU Make
+ installed).
+
+ Note that we have no plans to support a different
+ make tool, as you'll rapidly understand by reading this
+ document or looking at the Makefiles themselves.
+
+
+
+
+
+ The build system features some important points, which are all detailed
+ in the following sections:
+
+ - Automatic host platform detection
+ The first time the top Makefile 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 config.mk. You can now
+ invoke the top Makefile a second time to compile the
+ library directly.
+
+ The configuration sub-makefile can be regenerated any time
+ by invoking "make setup", which will re-run the
+ detection rules even if a config.mk is already present.
+
+
+
+
- User-selectable builds
+ The system-specific config.mk created when
+ running make 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 make.
+
+ For example, on Win32 platforms:
+
+
+
+ | 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.
+ |
+
+
+
+
+
+
- Automatic detection of font drivers
+ 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.
+
+ The list of font drivers is located in the file
+ "freetype2/config/system/ftmodule.h", however
+ it can be regenerated on-demand. Adding a new module to the
+ FreeType source tree is thus as easy as:
+
+ - create a new directory in "freetype2/src" and
+ put the new driver's source code and sub-makefiles there.
+
+
+
- invoke the top Makefile with target
+ "modules" (as in "make modules"),
+ as this will automatically regenerate the list of
+ available drivers by detecting the new directory and
+ its content.
+
+
+
+
+
+
+
+
II. Host Platform Detection
+
+ When the top-level Makefile is invoked, it looks for a
+ file named config.mk in the current directory. If this
+ file is found, it is used to build the library
+ (see Section III).
+
+ Otherwise, the file freetype2/config/detect.mk is included
+ and parsed. Its purpose is to:
+
+ - Define the PLATFORM variable, which indicates
+ what is the currently detected platform. It is initially
+ set to the default value "ansi".
+
+
+
- It searches for a detect.mk file in all
+ subdirectories of freetype2/config. 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 PLATFORM
+ accordingly.
+
+
+ This is illustrated by the following graphics :
+
+ 
+
+
+ Note that each system-specific detect.mk is in charge
+ of copying a valid configuration makefile to the current directory
+ (i.e. the one where make was invoked), depending on the
+ current targets. For example, the Win32 detect.mk will
+ be able to detect a "visualc" or "lcc" target,
+ as described in section I. Similarly, the OS/2 detect.mk
+ can detect targets like "borlandc", "watcom"
+ or "visualage", etc..
+
+
+
+
+
III. Building the library
+
+ When the top-level Makefile is invoked and that it finds
+ a config.mk file in the current directory, it defines
+ the variable BUILD_FREETYPE, then includes and parses the
+ configuration sub-makefile.
+
+ The latter defines a number of important variables that describe
+ the compilation process to the build system. Among other things:
+
+ - the extension to be used for object files and library files
+ (i.e. .o and .a on Unix, .obj
+ and .lib on Dos-Windows-OS/2, etc..).
+
+
+
- the directory where all object files will be stored
+ (usually freetype2/obj), as well as the one
+ containing the library file (usually the same as for
+ objects).
+
+
+
- the command line compiler, and its compilation flags for
+ indicating a new include path (usually "-I"),
+ a new macro declaration (usually "-D") or
+ the target object file (usually "-o ")
+
+
+ Once these variable are defined, config.mk test for the
+ definition of the BUILD_FREETYPE variable. If it exists,
+ the makefile then includes "freetype2/config/freetype.mk"
+ which contains the rules required to compile the library.
+
+ Note that freetype.mk also scans the subdirectories of
+ "freetype2/src" for a file called "rules.mk".
+ Each rules.mk contains, as it names suggests, the rules
+ required to compile a given font driver or module.
+
+ Once all this parsing is done, the library can be compiled. Usually,
+ each font driver is compiled as a standalone object file (e.g.
+ sfnt.o, truetype.o and type1.o).
+
+ This process can be illustrated by the following graphics:
+
+ 
+
+
+
+
+
+
+
IIV. Managing the list of modules
+
+ The makefile freetype.mk only determines how to compile
+ each one of the modules that are located in the sub-directories of
+ freetype2/src.
+
+ However, when the function FT_Init_FreeType is invoked at
+ the start of an application, it must create a new FT_Library
+ object, and registers all known font drivers to it by
+ repeatly calling FT_Add_Driver.
+
+ The list of known drivers is located in the file
+ "freetype2/config/system/ftmodule.h", and is used
+ exclusively by the internal function FT_Default_Drivers. The
+ list in ftmodule.h must be re-generated each time you add
+ or remove a module from freetype2/src.
+
+ This is normally performed by invoking the top-level Makefile
+ with the modules target, as in:
+
+
+ This will trigger a special rule that will re-generate
+ ftmodule.h. To do so, the Makefile will parse all module
+ directories for a file called "module.mk". Each
+ module.mk is a tiny sub-Makefile used to add a single
+ module to the driver list.
+
+ This is illustrated by the following graphics:
+
+ 
+
+
+ Note that the new list of modules is displayed in a very human-friendly
+ way after a "make modules". Here's an example with the current
+ source tree (on 11 Jan 2000):
+
+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 --
+
+
+
+
+
+
+
V. Building the demonstration programs
+
+ Several demonstration programs are located in the
+ "freetype2/demos" 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.
+
+ This section describes how the demonstration programs are compiled,
+ using the configuration freetype2/config.mk and their own
+ freetype2/demos/Makefile.
+
+ To compile the demonstration programs, after the library,
+ simply go to freetype2/demos then invoke GNU make with no
+ arguments.
+
+ The top-level Makefile will detect the config.mk in the
+ upper directory and include it. Because it doesn't define
+ the BUILD_FREETYPE variable, this will not force the
+ inclusion of freetype2/config/freetype.mk as described in
+ the previous section.
+
+ the Makefile will then include the makefile called
+ "freetype2/demos/graph/rules.mk". The graphics rules.mk
+ defines the rules required to compile the graphics sub-system.
+
+ 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
+ freetype2/demos/config. Each such directory contains a file
+ named rules.mk which is in charge of:
+
+ - detecting wether the corresponding graphics library is
+ available at the time of compilation.
+
+
- if it is, alter the compilation rules to include the graphics
+ module in the build of the graph library.
+
+
+ When the graph library is built in demos/obj, the
+ demonstration programs executables are generated by the top-level
+ Makefile.
+
+ This is illustrated by the following graphics:
+
+ 
+
+
+
+
+
diff --git a/docs/internals/demo-programs.png b/docs/internals/demo-programs.png
new file mode 100644
index 000000000..692b27771
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 000000000..b5a52748a
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 000000000..a12505b01
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 000000000..9a504b45e
Binary files /dev/null and b/docs/internals/platform-detection.png differ