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