1How 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
9I. 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
25II. 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
41III. 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
69IV. 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
140Copyright 2003, 2005, 2006 by
141David Turner, Robert Wilhelm, and Werner Lemberg.
142
143This  file is  part of  the FreeType  project, and  may only  be used,
144modified,  and distributed  under the  terms of  the  FreeType project
145license,  LICENSE.TXT.  By  continuing to  use, modify,  or distribute
146this file you  indicate that you have read  the license and understand
147and accept it fully.
148
149
150--- end of CUSTOMIZE ---
151