update for HEAD-2003050101

[reactos.git] / lib / freetype / docs / CUSTOMIZE

diff --git a/lib/freetype/docs/CUSTOMIZE b/lib/freetype/docs/CUSTOMIZE
new file mode 100644 (file)
index 0000000..397c2c3
--- /dev/null
+++ b/lib/freetype/docs/CUSTOMIZE
@@ -0,0 +1,117 @@
+How to customize the compilation of the library:
+================================================
+
+ FreeType is highly customizable to fit various needs, and this document
+ details how it is possible to select options and components at compilation
+ time.
+
+
+I. Configuration macros:
+
+  the file found in "include/freetype/config/ftoption.h" contains a list
+  of commented configuration macros that can be toggled by developers to
+  indicate which features to activate in their build of the library.
+  
+  these options range from debug level to availability of certain
+  features, like native TrueType hinting through a bytecode interpreter.
+  
+  we invite you to read this file for more information. You can change
+  the file's content to suit your needs, or override it with one of the
+  techniques described below..
+
+  
+II. Modules list:
+
+  the file found in "include/freetype/config/ftmodule.h" contains a list
+  of names corresponding to the modules / font drivers to be statically
+  compiled in the FreeType library during the build.
+
+  you can change it to suit your own preferences. Be aware that certain
+  modules depend on others, as described by the file "modules.txt" in
+  this directory.
+
+  you can modify the file's content to suit your needs, or override it
+  at compile time with one of the methods described below
+
+
+III. System interface:
+
+  FreeType's default interface to the system (i.e. the parts that deal with
+  memory management and i/o streams) is located in "src/base/ftsystem.c".
+  
+  the current implementation uses standard C library calls to manage
+  memory and read font files. It is however possible to write custom
+  implementations to suit specific systems.
+
+  to tell the GNU Make-based build system to use a custom system interface,
+  you'll need to define the environment variable FTSYS_SRC to point to
+  the relevant implementation, like in:
+  
+      on Unix:
+        ./configure <youroptions>
+        export FTSYS_SRC=foo/my_ftsystem.c
+        make
+        make install
+   
+      on Windows:
+        make setup <compiler>
+        set FTSYS_SRC=foo/my_ftsystem.c
+        make
+     
+     
+IV. Overriding default  configuration and module headers:
+
+  it is possible to over-ride the default configuration and module headers
+  without changing the original files. There are two ways to do that:
+
+  1. Using the C include path:
+  
+    use the C include path to ensure that your own versions of the
+    files are used at compile time when the lines:
+    
+       #include FT_CONFIG_OPTIONS_H
+       #include FT_CONFIG_MODULES_H
+
+    are compiled. Their default values being <freetype/config/ftoption.h>
+    and <freetype/config/ftmodule.h>, you can do something like:
+
+       custom/
+         freetype/
+           config/
+             ftoption.h    => custom options header
+             ftmodule.h    => custom modules list
+             
+       include/            => normal FreeType 2 include
+          freetype/
+            ...
+
+   then change the C include path to always give the path to "custom"
+   before the FreeType 2 "include"
+
+
+  2. Re-defining FT_CONFIG_OPTIONS_H and FT_CONFIG_MODULES_H
+  
+   another way to do the same thing is to re-define the macros used
+   to name the configuration headers. To do so, you'll need a custom
+   "ft2build.h", whose content can be as simple as:
+   
+          #ifndef __FT2_BUILD_GENERIC_H__
+          #define __FT2_BUILD_GENERIC_H__
+
+          #define  FT_CONFIG_OPTIONS_H   <custom/my-ftoption.h>
+          #define  FT_CONFIG_MACROS_H    <custom/my-ftmodule.h>
+
+          #include <freetype/config/ftheader.h>
+
+          #endif /* __FT2_BUILD_GENERIC_H__ */
+   
+   place them in:
+   
+       custom/
+          ft2build.h           => custom version described above
+          my-ftoption.h        => custom options header
+          my-ftmodule.h        => custom modules list header
+
+   and change the C include path to ensure that "custom" is always placed
+   before the FT2 "include" during compilation.
+