thirdparty/freetype-2.3.12/docs/CUSTOMIZE

   1 How to customize the compilation of the library
   2 ===============================================
   3
   4   FreeType  is highly  customizable  to fit  various  needs, and  this
   5   document  describes  how  it  is  possible  to  select  options  and
   6   components at compilation time.
   7
   8
   9 I. Configuration macros
  10
  11   The  file found  in `include/freetype/config/ftoption.h'  contains a
  12   list  of  commented configuration  macros  that  can  be toggled  by
  13   developers  to  indicate  which  features  should  be  active  while
  14   building the library.
  15
  16   These  options range  from debug  level to  availability  of certain
  17   features,   like  native   TrueType  hinting   through   a  bytecode
  18   interpreter.
  19
  20   We  invite you  to read  this file  for more  information.   You can
  21   change the  file's content to suit  your needs, or  override it with
  22   one of the techniques described below.
  23
  24
  25 II. Modules list
  26
  27   If you  use GNU make  please edit the top-level  file `modules.cfg'.
  28   It contains a  list of available FreeType modules  and extensions to
  29   be compiled.  Change it to suit your own preferences.  Be aware that
  30   certain modules  depend on  others, as described  in the  file.  GNU
  31   make  uses `modules.cfg'  to  generate `ftmodule.h'  (in the  object
  32   directory).
  33
  34   If  you don't  use  GNU make  you  have to  manually  edit the  file
  35   `include/freetype/config/ftmodule.h'  (which is  *not* used  with if
  36   compiled with GNU make) to  add or remove the drivers and components
  37   you want  to compile into  the library.  See `INSTALL.ANY'  for more
  38   information.
  39
  40
  41 III. System interface
  42
  43   FreeType's  default interface to  the system  (i.e., the  parts that
  44   deal  with  memory  management   and  i/o  streams)  is  located  in
  45   `src/base/ftsystem.c'.
  46
  47   The current  implementation uses standard C library  calls to manage
  48   memory  and to read  font files.   It is  however possible  to write
  49   custom implementations to suit specific systems.
  50
  51   To  tell the  GNU Make-based  build system  to use  a  custom system
  52   interface, you have to  define the environment variable FTSYS_SRC to
  53   point to the relevant implementation:
  54
  55     on Unix:
  56
  57       ./configure <your options>
  58       export FTSYS_SRC=foo/my_ftsystem.c
  59       make
  60       make install
  61
  62     on Windows:
  63
  64       make setup <compiler>
  65       set FTSYS_SRC=foo/my_ftsystem.c
  66       make
  67
  68
  69 IV. Overriding default configuration and module headers
  70
  71   It  is possible  to override  the default  configuration  and module
  72   headers without  changing the original files.  There  are three ways
  73   to do that:
  74
  75
  76   1. With GNU make
  77
  78     [This is actually a combination of method 2 and 3.]
  79
  80     Just put your custom  `ftoption.h' file into the objects directory
  81     (normally  `<topdir>/objs'),  which  GNU  make  prefers  over  the
  82     standard location.   No action is needed  for `ftmodule.h' because
  83     it is generated automatically in the objects directory.
  84
  85
  86   2. Using the C include path
  87
  88     Use the  C include path  to ensure that  your own versions  of the
  89     files are used at compile time when the lines
  90
  91       #include FT_CONFIG_OPTIONS_H
  92       #include FT_CONFIG_MODULES_H
  93
  94     are      compiled.       Their      default      values      being
  95     <freetype/config/ftoption.h> and <freetype/config/ftmodule.h>, you
  96     can do something like:
  97
  98       custom/
  99         freetype/
 100           config/
 101             ftoption.h    => custom options header
 102             ftmodule.h    => custom modules list
 103
 104       include/            => normal FreeType 2 include
 105         freetype/
 106           ...
 107
 108     then change the C include path to always give the path to `custom'
 109     before the FreeType 2 `include'.
 110
 111
 112   3. Redefining FT_CONFIG_OPTIONS_H and FT_CONFIG_MODULES_H
 113
 114     Another way to do the same thing is to redefine the macros used to
 115     name  the configuration  headers.  To  do  so, you  need a  custom
 116     `ft2build.h' whose content can be as simple as:
 117
 118       #ifndef __FT2_BUILD_MY_PLATFORM_H__
 119       #define __FT2_BUILD_MY_PLATFORM_H__
 120
 121       #define FT_CONFIG_OPTIONS_H  <custom/my-ftoption.h>
 122       #define FT_CONFIG_MODULES_H  <custom/my-ftmodule.h>
 123
 124       #include <freetype/config/ftheader.h>
 125
 126       #endif /* __FT2_BUILD_MY_PLATFORM_H__ */
 127
 128     Place those files in a separate directory, e.g.,
 129
 130       custom/
 131         ft2build.h           => custom version described above
 132         my-ftoption.h        => custom options header
 133         my-ftmodule.h        => custom modules list header
 134
 135     and change  the C include path  to ensure that  `custom' is always
 136     placed before the FT2 `include' during compilation.
 137
 138 ----------------------------------------------------------------------
 139
 140 Copyright 2003, 2005, 2006 by
 141 David Turner, Robert Wilhelm, and Werner Lemberg.
 142
 143 This  file is  part of  the FreeType  project, and  may only  be used,
 144 modified,  and distributed  under the  terms of  the  FreeType project
 145 license,  LICENSE.TXT.  By  continuing to  use, modify,  or distribute
 146 this file you  indicate that you have read  the license and understand
 147 and accept it fully.
 148
 149
 150 --- end of CUSTOMIZE ---