docs/CUSTOMIZE

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.