misc/libfreetype/docs/CUSTOMIZE
changeset 5172 88f2e05288ba
equal deleted inserted replaced
5171:f9283dc4860d 5172:88f2e05288ba
       
     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 ---