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 `ftoption.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
38    locations where  these were allocated.   It is always a  very good
39    idea to define this in  development builds.  This works with _any_
40    program linked to FreeType, but requires a big deal of memory (the
41    debugging memory  manager never  frees the blocks  to the  heap in
42    order to detect double frees).
43
44    When  FT2_DEBUG_MEMORY isn't  defined  at  runtime, the  debugging
45    memory 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
52debugging its 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
75    parentheses 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
85    component being run.
86
87    The developer  should always  define FT_COMPONENT  as appropriate,
88    for 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
95    the internal  file `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
98    check   the    undefined   or   the   unused    trace   macro   by
99    `src/tools/chktrcmp.py'.
100
101    Each such component is assigned a `debug level', ranging from 0 to
102    7,  through   the  use  of  the   FT2_DEBUG  environment  variable
103    (described below) when a program linked with FreeType starts.
104
105    When FT_TRACE is  called, its level is compared to  the one of the
106    corresponding component.  Messages with trace levels *higher* than
107    the corresponding component level are filtered and never printed.
108
109    This means  that trace messages  with level 0 are  always printed,
110    those with  level 2 are only  printed when the component  level is
111    *at least* 2.
112
113    The  second parameter  to  FT_TRACE must  contain parentheses  and
114    correspond to a printf-like call, as in
115
116      FT_TRACE( 2, ( "your %s is not %s\n", "foo", "bar" ) )
117
118    The   shortcut  macros   FT_TRACE0,  FT_TRACE1,   FT_TRACE2,  ...,
119    FT_TRACE7 can  be used with  constant level indices, and  are much
120    cleaner to use, as in
121
122      FT_TRACE2(( "your %s is not %s\n", "foo", "bar" ));
123
124
125III. Environment variables
126--------------------------
127
128The  following  environment  variables control  debugging  output  and
129behaviour of FreeType at runtime.
130
131
132  FT2_DEBUG
133
134    This  variable   is  only  used   when  FreeType  is   built  with
135    FT_DEBUG_LEVEL_TRACE  defined.  It  contains a  list of  component
136    level definitions, following this format:
137
138      component1:level1 component2:level2 component3:level3 ...
139
140    where `componentX' is the name  of a tracing component, as defined
141    in `fttrace.h', but without the  `trace_' prefix.  `levelX' is the
142    corresponding level to use at runtime.
143
144    `any'  is a  special component  name that  will be  interpreted as
145    `any/all components'.  For example, the following definitions
146
147      set FT2_DEBUG=any:2 memory:5 io:4        (on Windows)
148      export FT2_DEBUG="any:2 memory:5 io:4"   (on Linux with bash)
149
150    both stipulate that all components should have level 2, except for
151    the memory and  io components which will be set  to trace levels 5
152    and 4, respectively.
153
154
155  FT2_DEBUG_MEMORY
156
157    This environment variable,  when defined, tells FreeType  to use a
158    debugging memory manager that will  track leaking memory blocks as
159    well as other common errors like double frees.  It is also capable
160    of  reporting _where_  the  leaking blocks  were allocated,  which
161    considerably  saves  time  when  debugging new  additions  to  the
162    library.
163
164    This  code  is only  compiled  when  FreeType  is built  with  the
165    FT_DEBUG_MEMORY macro #defined in  `ftoption.h' though, it will be
166    ignored in other builds.
167
168
169  FT2_ALLOC_TOTAL_MAX
170
171    This variable is  ignored if FT2_DEBUG_MEMORY is  not defined.  It
172    allows  you  to  specify  a  maximum  heap  size  for  all  memory
173    allocations performed  by FreeType.  This  is very useful  to test
174    the robustness  of the  font engine  and programs  that use  it in
175    tight memory conditions.
176
177    If it is undefined, or if its value is not strictly positive, then
178    no allocation bounds are checked at runtime.
179
180
181  FT2_ALLOC_COUNT_MAX
182
183    This variable is  ignored if FT2_DEBUG_MEMORY is  not defined.  It
184    allows  you to  specify  a maximum  number  of memory  allocations
185    performed    by    FreeType    before    returning    the    error
186    FT_Err_Out_Of_Memory.  This  is useful  for debugging  and testing
187    the engine's robustness.
188
189    If it is undefined, or if its value is not strictly positive, then
190    no allocation bounds are checked at runtime.
191
192------------------------------------------------------------------------
193
194Copyright 2002-2018 by
195David Turner, Robert Wilhelm, and Werner Lemberg.
196
197This  file is  part  of the  FreeType  project, and  may  only be  used,
198modified,  and  distributed under  the  terms  of  the FreeType  project
199license, LICENSE.TXT.  By continuing  to use, modify, or distribute this
200file  you indicate that  you have  read the  license and  understand and
201accept it fully.
202
203
204--- end of DEBUG ---
205