Hash :
015a9b8d
Author :
Date :
2020-12-07T10:27:42
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 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310
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 `ftoption.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 does
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' dumps memory statistics,
including the list of leaked memory blocks and optionally 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.
FT_DEBUG_LOGGING
#define this macro for enhanced logging support; it automatically
sets `FT_DEBUG_LEVEL_TRACE' and `FT_DEBUG_LEVEL_ERROR'.
If defined, `FT_TRACE' and `FT_ERROR' can send tracing and
debugging messages to a file. The location of the log file has to
be set with the `FT_LOGGING_FILE' environment variable (more on
this later).
The main enhancements are the possibility of logging the time and
the name of the `FT_COMPONENT' macro together with the affected
`FT_TRACE' or `FT_ERROR' calls. See below how to activate this in
the `FT2_DEBUG' environment variable.
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) without stopping 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 aborts 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. 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', which names 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 io
The value of the `FT_COMPONENT' macro is one of the component
names defined in the internal file `internal/fttrace.h'. If you
modify the FreeType source code and insert a new `FT_COMPONENT'
macro, you must register it in `fttrace.h'. If you insert or
remove many trace macros, you can test for undefined or unused
trace macros with the script `src/tools/chktrcmp.py'.
Each such component is assigned a `debug level', ranging from
value 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 out 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, etc.
The second parameter to `FT_TRACE' must contain parentheses and
corresponds 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'. `levelX' is the corresponding level to use at
runtime.
`any' is a special component name that is 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 are set to the trace levels 5
and 4, respectively.
If `FT_DEBUG_LOGGING' is defined, two more options are available.
* -v: Print also the name of FreeType's component from which the
current log is produced.
* -t: Print also the time.
Here are some examples how the output might look like.
FT2_DEBUG="any:7 memory:5 -vt"
=> [20:32:02:44969 ttload] table directory loaded
FT2_DEBUG="any:7 memory:5 -t"
=> [20:32:02:44969] table directory loaded
FT2_DEBUG="any:7 memory:5 -v"
=> [ttload] table directory loaded
FT_LOGGING_FILE
This variable is only used if FreeType is built with the
`FT_DEBUG_LOGGING' macro defined. It contains the path to the
file where the user wants to put his log file. If it is not set,
FreeType uses stderr.
Examples:
On UNIX-like systems with bash:
export FT_LOGGING_FILE="/tmp/freetype2.log"
On Windows:
set FT_LOGGING_FILE=C:\Users\AppData\Local\Temp\freetype2.log
FT2_DEBUG_MEMORY
This environment variable, when defined, tells FreeType to use a
debugging memory manager that tracks 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 is
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, 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, no
allocation bounds are checked at runtime.
FT2_KEEP_ALIVE
This variable is ignored if `FT2_DEBUG_MEMORY' is not defined.
`Keep alive' means that freed blocks aren't released to the heap.
This is useful to detect double-frees or weird heap corruption,
reporting the source code location of the original allocation and
deallocation in case of a problem. It uses large amounts of
memory, however.
If it is undefined, or if its value is not strictly positive,
freed blocks are released at runtime.
IV. Additional Capabilities with `FT_DEBUG_LOGGING'
---------------------------------------------------
If `FT_DEBUG_LOGGING' is defined, four APIs are available to provide
additional debugging support. Use
#include<freetype/ftlogging.h>
to access them.
FT_Trace_Set_Level( const char* level )
By default, FreeType uses the tracing levels set in the
`FT2_DEBUG' environment variable. Use this function to override
the value with `level'. Use value `NULL' to disable tracing.
FT_Trace_Set_Default_Level():
Reset the tracing levels to the default value, i.e., the value of
the `FT2_DEBUG' environment variable or no tracing if not set.
FT_Set_Log_Handler( ft_custom_log_handler handler ):
Use `handler' as a custom handler for formatting tracing and error
messages. The `ft_custom_log_handler' typedef has the following
prototype.
void
(*ft_custom_log_handler)( const char* ft_component,
const char* fmt,
va_list args );
`ft_component' is the current component like `ttload', `fmt' is the
first argument of `FT_TRACE' or `FT_ERROR', and `args' holds the
remaining arguments.
FT_Set_Default_Log_Handler():
Reset the log handler to the default version.
------------------------------------------------------------------------
Copyright (C) 2002-2020 by
David Turner, Robert Wilhelm, and Werner Lemberg.
This file is part of the FreeType project, and may only be used,
modified, and distributed under the terms of the FreeType project
license, LICENSE.TXT. By continuing to use, modify, or distribute this
file you indicate that you have read the license and understand and
accept it fully.
--- end of DEBUG ---