1Debugging within the FreeType sources
2=====================================
3
4I. Configuration macros
5-----------------------
6
7There  are several ways  to enable  debugging features  in a  FreeType 2
8builds.   This is controlled  through the  definition of  special macros
9located in the file `ftoptions.h'.  The macros are:
10
11
12  FT_DEBUG_LEVEL_ERROR
13
14    #define this macro  if you want to compile  the FT_ERROR macro calls
15    to  print error messages  during program  execution.  This  will not
16    stop  the  program.   Very  useful  to  spot  invalid  fonts  during
17    development and to code workarounds for them.
18
19  FT_DEBUG_LEVEL_TRACE
20
21    #define this macro  if you want to compile  both macros FT_ERROR and
22    FT_TRACE.   This also  includes the  variants  FT_TRACE0, FT_TRACE1,
23    FT_TRACE2, ..., FT_TRACE7.
24
25    The  trace  macros are  used  to  send  debugging messages  when  an
26    appropriate  `debug  level' is  configured  at  runtime through  the
27    FT2_DEBUG environment variable (more on this later).
28
29  FT_DEBUG_MEMORY
30
31    If  this macro is  #defined, the  FreeType engine  is linked  with a
32    small  but  effective  debugging  memory  manager  that  tracks  all
33    allocations and frees that are performed within the font engine.
34
35    When  the  FT2_DEBUG_MEMORY   environment  variable  is  defined  at
36    runtime,  a call  to FT_Done_FreeType  will dump  memory statistics,
37    including the list of leaked memory blocks with the source locations
38    where these were allocated.  It is always a very good idea to define
39    this in development builds.  This works with _any_ program linked to
40    FreeType, but  requires a big  deal of memory (the  debugging memory
41    manager never frees the blocks to the heap in order to detect double
42    frees).
43
44    When FT2_DEBUG_MEMORY isn't defined at runtime, the debugging memory
45    manager is ignored, and performance is unaffected.
46
47
48II. Debugging macros
49--------------------
50
51Several macros can be used within the FreeType sources to help debugging
52its code:
53
54
55  1. FT_ERROR(( ... ))
56
57    This macro is  used to send debug messages  that indicate relatively
58    serious  errors (like  broken font  files),  but will  not stop  the
59    execution of  the running program.   Its code is compiled  only when
60    either FT_DEBUG_LEVEL_ERROR  or FT_DEBUG_LEVEL_TRACE are  defined in
61    `ftoption.h'.
62
63    Note that you  have to use a printf-like  signature, but with double
64    parentheses, like in
65
66      FT_ERROR(( "your %s is not %s\n", "foo", "bar" ));
67
68
69  2. FT_ASSERT( condition )
70
71    This macro  is used to check  strong assertions at  runtime.  If its
72    condition isn't TRUE,  the program will abort with  a panic message.
73    Its   code   is  compiled   when   either  FT_DEBUG_LEVEL_ERROR   or
74    FT_DEBUG_LEVEL_TRACE are defined.  You don't need double parentheses
75    here.  For example
76
77      FT_ASSERT( ptr != NULL );
78
79
80  3. FT_TRACE( level, (message...) )
81
82    The  FT_TRACE  macro  is  used  to  send  general-purpose  debugging
83    messages during  program execution.   This macro uses  an *implicit*
84    macro named FT_COMPONENT used to name the current FreeType component
85    being run.
86
87    The developer should always  define FT_COMPONENT as appropriate, for
88    example as in
89
90      #undef  FT_COMPONENT
91      #define FT_COMPONENT  trace_io
92
93    The  value  of  the  FT_COMPONENT  macro  is  an  enumeration  named
94    trace_XXXX where XXXX  is one of the component  names defined in the
95    internal file `freetype/internal/fttrace.h'.  If you modify FreeType
96    source  and insert  new trace_XXXX macro,  you  must register  it in
97    fttrace.h. If you insert or remove many trace macros,  you can check
98    the undefined or the unused trace macro by src/tools/chktrcmp.py.
99
100    Each  such component  is assigned  a `debug  level', ranging  from 0
101    to  7,  through  the  use  of  the  FT2_DEBUG  environment  variable
102    (described below) when a program linked with FreeType starts.
103
104    When FT_TRACE  is called, its  level is compared  to the one  of the
105    corresponding component.   Messages with trace  levels *higher* than
106    the corresponding component level are filtered and never printed.
107
108    This  means that  trace messages  with level  0 are  always printed,
109    those with level 2 are only  printed when the component level is *at
110    least* 2.
111
112    The  second  parameter  to  FT_TRACE must  contain  parentheses  and
113    correspond to a printf-like call, as in
114
115      FT_TRACE( 2, ( "your %s is not %s\n", "foo", "bar" ) )
116
117    The shortcut macros  FT_TRACE0, FT_TRACE1, FT_TRACE2, ..., FT_TRACE7
118    can be  used with  constant level indices,  and are much  cleaner to
119    use, as in
120
121     FT_TRACE2(( "your %s is not %s\n", "foo", "bar" ));
122
123
124III. Environment variables
125--------------------------
126
127The  following  environment   variables  control  debugging  output  and
128behaviour of FreeType at runtime.
129
130
131  FT2_DEBUG
132
133    This   variable  is   only  used   when  FreeType   is   built  with
134    FT_DEBUG_LEVEL_TRACE defined.  It contains a list of component level
135    definitions, following this format:
136
137       component1:level1 component2:level2 component3:level3 ...
138
139    where `componentX' is the name of a tracing component, as defined in
140    `fttrace.h',  but  without the  `trace_'  prefix.   `levelX' is  the
141    corresponding level to use at runtime.
142
143    `any'  is a  special  component  name that  will  be interpreted  as
144    `any/all components'.  For example, the following definitions
145
146       set FT2_DEBUG=any:2 memory:5 io:4        (on Windows)
147       export FT2_DEBUG="any:2 memory:5 io:4"   (on Linux with bash)
148
149    both stipulate that  all components should have level  2, except for
150    the memory and io components which will be set to trace levels 5 and
151    4, respectively.
152
153
154  FT2_DEBUG_MEMORY
155
156    This  environment variable, when  defined, tells  FreeType to  use a
157    debugging memory  manager that will  track leaking memory  blocks as
158    well as other  common errors like double frees.   It is also capable
159    of  reporting  _where_  the  leaking blocks  were  allocated,  which
160    considerably saves time when debugging new additions to the library.
161
162    This  code  is  only  compiled  when  FreeType  is  built  with  the
163    FT_DEBUG_MEMORY macro  #defined in  `ftoption.h' though, it  will be
164    ignored in other builds.
165
166
167  FT2_ALLOC_TOTAL_MAX
168
169    This  variable is ignored  if FT2_DEBUG_MEMORY  is not  defined.  It
170    allows you to specify a maximum heap size for all memory allocations
171    performed by FreeType.   This is very useful to  test the robustness
172    of  the  font  engine and  programs  that  use  it in  tight  memory
173    conditions.
174
175    If it is  undefined, or if its value is  not strictly positive, then
176    no allocation bounds are checked at runtime.
177
178
179  FT2_ALLOC_COUNT_MAX
180
181    This  variable is ignored  if FT2_DEBUG_MEMORY  is not  defined.  It
182    allows  you  to  specify  a  maximum number  of  memory  allocations
183    performed    by     FreeType    before    returning     the    error
184    FT_Err_Out_Of_Memory.  This is useful  for debugging and testing the
185    engine's robustness.
186
187    If it is  undefined, or if its value is  not strictly positive, then
188    no allocation bounds are checked at runtime.
189
190------------------------------------------------------------------------
191
192Copyright 2002, 2003, 2004, 2005, 2009 by
193David Turner, Robert Wilhelm, and Werner Lemberg.
194
195This  file is  part  of the  FreeType  project, and  may  only be  used,
196modified,  and  distributed under  the  terms  of  the FreeType  project
197license, LICENSE.TXT.  By continuing  to use, modify, or distribute this
198file  you indicate that  you have  read the  license and  understand and
199accept it fully.
200
201
202--- end of DEBUG ---
203