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