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 15 calls to print error messages during program execution. This does 16 not 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' 22 and `FT_TRACE'. This also includes the variants `FT_TRACE0', 23 `FT_TRACE1', `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' dumps memory statistics, 37 including the list of leaked memory blocks and optionally with the 38 source locations where these were allocated. It is always a very 39 good idea to define this in development builds. This works with 40 _any_ program linked to FreeType, but requires a big deal of 41 memory (the debugging memory manager never frees the blocks to the 42 heap in 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 FT_DEBUG_LOGGING 48 49 #define this macro for enhanced logging support; it automatically 50 sets `FT_DEBUG_LEVEL_TRACE' and `FT_DEBUG_LEVEL_ERROR'. 51 52 If defined, `FT_TRACE' and `FT_ERROR' can send tracing and 53 debugging messages to a file. The location of the log file has to 54 be set with the `FT_LOGGING_FILE' environment variable (more on 55 this later). 56 57 The main enhancements are the possibility of logging the time and 58 the name of the `FT_COMPONENT' macro together with the affected 59 `FT_TRACE' or `FT_ERROR' calls. See below how to activate this in 60 the `FT2_DEBUG' environment variable. 61 62 63II. Debugging macros 64-------------------- 65 66Several macros can be used within the FreeType sources to help 67debugging its code: 68 69 70 1. FT_ERROR(( ... )) 71 72 This macro is used to send debug messages that indicate relatively 73 serious errors (like broken font files) without stopping the 74 execution of the running program. Its code is compiled only when 75 either `FT_DEBUG_LEVEL_ERROR' or `FT_DEBUG_LEVEL_TRACE' are 76 defined in `ftoption.h'. 77 78 Note that you have to use a printf-like signature, but with double 79 parentheses, like in 80 81 FT_ERROR(( "your %s is not %s\n", "foo", "bar" )); 82 83 84 2. FT_ASSERT( condition ) 85 86 This macro is used to check strong assertions at runtime. If its 87 condition isn't TRUE, the program aborts with a panic message. 88 Its code is compiled when either `FT_DEBUG_LEVEL_ERROR' or 89 `FT_DEBUG_LEVEL_TRACE' are defined. You don't need double 90 parentheses here. Example: 91 92 FT_ASSERT( ptr != NULL ); 93 94 95 3. FT_TRACE( level, (message...) ) 96 97 The `FT_TRACE' macro is used to send general-purpose debugging 98 messages during program execution. This macro uses an *implicit* 99 macro named `FT_COMPONENT', which names the current FreeType 100 component being run. 101 102 The developer should always define `FT_COMPONENT' as appropriate, 103 for example as in 104 105 #undef FT_COMPONENT 106 #define FT_COMPONENT io 107 108 The value of the `FT_COMPONENT' macro is one of the component 109 names defined in the internal file `internal/fttrace.h'. If you 110 modify the FreeType source code and insert a new `FT_COMPONENT' 111 macro, you must register it in `fttrace.h'. If you insert or 112 remove many trace macros, you can test for undefined or unused 113 trace macros with the script `src/tools/chktrcmp.py'. 114 115 Each such component is assigned a `debug level', ranging from 116 value 0 to 7, through the use of the `FT2_DEBUG' environment 117 variable (described below) when a program linked with FreeType 118 starts. 119 120 When `FT_TRACE' is called, its level is compared to the one of the 121 corresponding component. Messages with trace levels *higher* than 122 the corresponding component level are filtered out and never 123 printed. This means that trace messages with level 0 are always 124 printed, those with level 2 are only printed when the component 125 level is *at least* 2, etc. 126 127 The second parameter to `FT_TRACE' must contain parentheses and 128 corresponds to a printf-like call, as in 129 130 FT_TRACE( 2, ( "your %s is not %s\n", "foo", "bar" ) ) 131 132 The shortcut macros `FT_TRACE0', `FT_TRACE1', `FT_TRACE2', ..., 133 `FT_TRACE7' can be used with constant level indices, and are much 134 cleaner to use, as in 135 136 FT_TRACE2(( "your %s is not %s\n", "foo", "bar" )); 137 138 139III. Environment variables 140-------------------------- 141 142The following environment variables control debugging output and 143behaviour of FreeType at runtime. 144 145 146 FT2_DEBUG 147 148 This variable is only used when FreeType is built with 149 `FT_DEBUG_LEVEL_TRACE' defined. It contains a list of component 150 level definitions, following this format: 151 152 component1:level1 component2:level2 component3:level3 ... 153 154 where `componentX' is the name of a tracing component, as defined 155 in `fttrace.h'. `levelX' is the corresponding level to use at 156 runtime. 157 158 `any' is a special component name that is interpreted as `any/all 159 components'. For example, the following definitions 160 161 set FT2_DEBUG=any:2 memory:5 io:4 (on Windows) 162 export FT2_DEBUG="any:2 memory:5 io:4" (on Linux with bash) 163 164 both stipulate that all components should have level 2, except for 165 the memory and io components, which are set to the trace levels 5 166 and 4, respectively. 167 168 If `FT_DEBUG_LOGGING' is defined, two more options are available. 169 170 * -v: Print also the name of FreeType's component from which the 171 current log is produced, together with the tracing level. 172 173 * -t: Print also the time. 174 175 Here are some examples how the output might look like. 176 177 FT2_DEBUG="any:7 memory:5 -vt" 178 179 => [20:32:02:44969 ttload:2] table directory loaded 180 181 FT2_DEBUG="any:7 memory:5 -t" 182 183 => [20:32:02:44969] table directory loaded 184 185 FT2_DEBUG="any:7 memory:5 -v" 186 187 => [ttload:2] table directory loaded 188 189 190 FT_LOGGING_FILE 191 192 This variable is only used if FreeType is built with the 193 `FT_DEBUG_LOGGING' macro defined. It contains the path to the 194 file where the user wants to put his log file. If it is not set, 195 FreeType uses stderr. 196 197 Examples: 198 199 On UNIX-like systems with bash: 200 export FT_LOGGING_FILE="/tmp/freetype2.log" 201 202 On Windows: 203 set FT_LOGGING_FILE=C:\Users\AppData\Local\Temp\freetype2.log 204 205 206 FT2_DEBUG_MEMORY 207 208 This environment variable, when defined, tells FreeType to use a 209 debugging memory manager that tracks leaking memory blocks as well 210 as other common errors like double frees. It is also capable of 211 reporting _where_ the leaking blocks were allocated, which 212 considerably saves time when debugging new additions to the 213 library. 214 215 This code is only compiled when FreeType is built with the 216 `FT_DEBUG_MEMORY' macro #defined in `ftoption.h' though, it is 217 ignored in other builds. 218 219 220 FT2_ALLOC_TOTAL_MAX 221 222 This variable is ignored if `FT2_DEBUG_MEMORY' is not defined. It 223 allows you to specify a maximum heap size for all memory 224 allocations performed by FreeType. This is very useful to test 225 the robustness of the font engine and programs that use it in 226 tight memory conditions. 227 228 If it is undefined, or if its value is not strictly positive, no 229 allocation bounds are checked at runtime. 230 231 232 FT2_ALLOC_COUNT_MAX 233 234 This variable is ignored if `FT2_DEBUG_MEMORY' is not defined. It 235 allows you to specify a maximum number of memory allocations 236 performed by FreeType before returning the error 237 `FT_Err_Out_Of_Memory'. This is useful for debugging and testing 238 the engine's robustness. 239 240 If it is undefined, or if its value is not strictly positive, no 241 allocation bounds are checked at runtime. 242 243 244 FT2_KEEP_ALIVE 245 246 This variable is ignored if `FT2_DEBUG_MEMORY' is not defined. 247 `Keep alive' means that freed blocks aren't released to the heap. 248 This is useful to detect double-frees or weird heap corruption, 249 reporting the source code location of the original allocation and 250 deallocation in case of a problem. It uses large amounts of 251 memory, however. 252 253 If it is undefined, or if its value is not strictly positive, 254 freed blocks are released at runtime. 255 256 257IV. Additional Capabilities with `FT_DEBUG_LOGGING' 258--------------------------------------------------- 259 260If `FT_DEBUG_LOGGING' is defined, four APIs are available to provide 261additional debugging support. Use 262 263 #include <freetype/ftlogging.h> 264 265to access them. 266 267 FT_Trace_Set_Level( const char* level ) 268 269 By default, FreeType uses the tracing levels set in the 270 `FT2_DEBUG' environment variable. Use this function to override 271 the value with `level'. Use value `NULL' to disable tracing. 272 273 FT_Trace_Set_Default_Level(): 274 275 Reset the tracing levels to the default value, i.e., the value of 276 the `FT2_DEBUG' environment variable or no tracing if not set. 277 278 FT_Set_Log_Handler( ft_custom_log_handler handler ): 279 280 Use `handler' as a custom handler for formatting tracing and error 281 messages. The `ft_custom_log_handler' typedef has the following 282 prototype. 283 284 void 285 (*ft_custom_log_handler)( const char* ft_component, 286 const char* fmt, 287 va_list args ); 288 289 `ft_component' is the current component like `ttload', `fmt' is the 290 first argument of `FT_TRACE' or `FT_ERROR', and `args' holds the 291 remaining arguments. 292 293 FT_Set_Default_Log_Handler(): 294 295 Reset the log handler to the default version. 296 297 298------------------------------------------------------------------------ 299 300Copyright (C) 2002-2022 by 301David Turner, Robert Wilhelm, and Werner Lemberg. 302 303This file is part of the FreeType project, and may only be used, 304modified, and distributed under the terms of the FreeType project 305license, LICENSE.TXT. By continuing to use, modify, or distribute this 306file you indicate that you have read the license and understand and 307accept it fully. 308 309 310--- end of DEBUG --- 311