1 Debugging within the FreeType sources:
2 ======================================
4 I. Configuration macros
5 -----------------------
7 There are several ways to enable debugging features in a FreeType 2
8 builds. This is controlled through the definition of special macros
9 located in the file "ftoptions.h". The macros are:
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 workarounds for them.
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.
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).
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.
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
44 When FT2_DEBUG_MEMORY isn't defined at runtime, the debugging memory
45 manager is ignored, and performance is un-affected.
51 Several macros can be used within the FreeType sources to help debugging
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
62 Note that you must use with a printf-like signature, but with double
65 FT_ERROR(( "your %s is not %s\n", "foo", "bar" ));
68 2. FT_ASSERT( condition )
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
76 FT_ASSERT( ptr != NULL );
79 3. FT_TRACE( level, (message...) )
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
86 The developer should always define FT_COMPONENT as appropriate, for
90 #define FT_COMPONENT trace_io
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>.
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.
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.
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
108 The second parameter to FT_TRACE must contain parentheses and
109 correspond to a print-like call, as in:
111 FT_TRACE( 2, ( "your %s is not %s\n", "foo", "bar" ) )
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
117 FT_TRACE2(( "your %s is not %s\n", "foo", "bar" ));
120 III. Environment variables
121 --------------------------
123 The following environment variables control debugging output and
124 behaviour of FreeType at runtime:
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:
133 component1:level1 component2:level2 component3:level3 ...
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.
139 "any" is a special component name that will be interpreted as
140 "any/all components". For example, the following definitions
142 set FT2_DEBUG=any:2 memory:5 io:4 (on Windows)
143 export FT2_DEBUG="any:2 memory:5 io:4" (on Linux)
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
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.
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.
164 this variable is ignored if FT2_DEBUG_MEMORY is not defined. It allows
165 you to specify a maximum heap size for all memory allocations performed
166 by FreeType. This is very useful to test the robustness of the font
167 engine and programs that use it in tight memory conditions.
169 If it is undefined, or if its value is not strictly positive, then no
170 allocation bounds are checked at runtime.
175 this variable is ignored if FT2_DEBUG_MEMORY is not defined. It allows
176 you to sepcify a maximum number of memory allocations performed by
177 FreeType before returning the error FT_Err_Out_Of_Memory. This is
178 useful for debugging and testing the engine's robustness.
180 If it is undefined, or if its value is not strictly positive, then no
181 allocation bounsd are checked at runtime.