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    used to  print error messages  during program execution.   This will
16    not  stop the  program, but  is very  useful to  spot  invalid fonts
17    during development and code wordarounds for them.
18
19  FT_DEBUG_LEVEL_TRACE
20
21    #define this  macro if you want  to compile both  the FT_ERROR macro
22    and the  FT_TRACE one.  This  also includes the  variants FT_TRACE0,
23    FT_TRACE1, FT_TRACE2, ..., FT_TRACE6.
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  engines 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's  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 un-affected.
46
47
48II. Debugging macros
49--------------------
50
51Several macros can be used within the FreeType sources to help debugging
52its code:
53
54  1. FT_ERROR(( ... ))
55
56    This macro is  used to send debug messages  that indicate relatively
57    serious  errors (like  broken font  files),  but will  not stop  the
58    execution of  the running program.   Its code is compiled  only when
59    either FT_DEBUG_LEVEL_ERROR  or FT_DEBUG_LEVEL_TRACE are  defined in
60    "ftoption.h".
61
62    Note that you must use with a printf-like signature, but with double
63    parentheses, like in:
64
65      FT_ERROR(( "your %s is not %s\n", "foo", "bar" ));
66
67
68  2. FT_ASSERT( condition )
69
70    This macro  is used to check  strong assertions at  runtime.  If its
71    condition isn't TRUE,  the program will abort with  a panic message.
72    Its   code   is  compiled   when   either  FT_DEBUG_LEVEL_ERROR   or
73    FT_DEBUG_LEVEL_TRACE are defined.  You don't need double-parentheses
74    here.  For example:
75
76      FT_ASSERT( ptr != NULL );
77
78
79  3. FT_TRACE( level, (message...) )
80
81    The  FT_TRACE  macro  is  used  to  send  general-purpose  debugging
82    messages during  program execution.   This macro uses  an *implicit*
83    macro named FT_COMPONENT used to name the current FreeType component
84    being run.
85
86    The developer should always  define FT_COMPONENT as appropriate, for
87    example as in:
88
89      #undef  FT_COMPONENT
90      #define FT_COMPONENT  trace_io
91
92    The  value  of  the  FT_COMPONENT  macro  is  an  enumeration  named
93    trace_XXXX where XXXX  is one of the component  names defined in the
94    internal file <freetype/internal/fttrace.h>.
95
96    Each such component is assigned a "debug level", ranging from 0 to 6
97    when a program  linked with FreeType starts, through  the use of the
98    FT2_DEBUG environment variable, described later.
99
100    When FT_TRACE  is called, its  level is compared  to the one  of the
101    corresponding component.   Messages with trace  levels *higher* than
102    the corresponding component level are filtered and never printed.
103
104    This  means that  trace messages  with level  0 are  always printed,
105    those with level 2 are only  printed when the component level is *at
106    least* 2.
107
108    The  second  parameter  to  FT_TRACE must  contain  parentheses  and
109    correspond to a print-like call, as in:
110
111      FT_TRACE( 2, ( "your %s is not %s\n", "foo", "bar" ) )
112
113    The shortcut macros  FT_TRACE0, FT_TRACE1, FT_TRACE2_, ... FT_TRACE6
114    can be  used with  constant level indices,  and are much  cleaner to
115    use, as in
116
117     FT_TRACE2(( "your %s is not %s\n", "foo", "bar" ));
118
119
120III. Environment variables
121--------------------------
122
123The  following  environment   variables  control  debugging  output  and
124behaviour of FreeType at runtime:
125
126
127  FT2_DEBUG
128
129    This   variable  is   only  used   when  FreeType   is   built  with
130    FT_DEBUG_LEVEL_TRACE defined.  It contains a list of component level
131    definitions, following this format:
132
133       component1:level1 component2:level2 component3:level3 ...
134
135    where "componentX" is the name of a tracing component, as defined in
136    "fttrace.h", but  without the "trace_"  prefix, and "levelX"  is the
137    corresponding level to use at runtime.
138
139    "any"  is a  special  component  name that  will  be interpreted  as
140    "any/all components".  For example, the following definitions
141
142       set FT2_DEBUG=any:2 memory:5 io:4        (on Windows)
143       export FT2_DEBUG="any:2 memory:5 io:4"   (on Linux)
144
145    both stipulate that  all components should have level  2, except for
146    the memory and io components which will be set to trace levels 5 and
147    4 respectively.
148
149  FT2_DEBUG_MEMORY
150
151    This  environment variable, when  defined, tells  FreeType to  use a
152    debugging  memory manager that  will track  leaked memory  blocks as
153    well as other  common errors like double frees.   It is also capable
154    of  reporting  _where_  the  leaked  blocks  were  allocated,  which
155    considerably saves time when debugging new additions to the library.
156
157    This  code  is  only  compiled  when  FreeType  is  built  with  the
158    FT_DEBUG_MEMORY macro  #defined in  "ftoption.h" though, it  will be
159    ignored in other builds.
160
161
162End of file
163