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 to print error messages during program execution. This will not 16 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 and 22 FT_TRACE. This also includes the variants FT_TRACE0, FT_TRACE1, 23 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 will dump memory statistics, 37 including the list of leaked memory blocks with the source locations 38 where these were allocated. It is 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 unaffected. 46 47 48II. Debugging macros 49-------------------- 50 51Several macros can be used within the FreeType sources to help debugging 52its code: 53 54 55 1. FT_ERROR(( ... )) 56 57 This macro is used to send debug messages that indicate relatively 58 serious errors (like broken font files), but will not stop the 59 execution of the running program. Its code is compiled only when 60 either FT_DEBUG_LEVEL_ERROR or FT_DEBUG_LEVEL_TRACE are defined in 61 `ftoption.h'. 62 63 Note that you have to use a printf-like signature, but with double 64 parentheses, like in 65 66 FT_ERROR(( "your %s is not %s\n", "foo", "bar" )); 67 68 69 2. FT_ASSERT( condition ) 70 71 This macro is used to check strong assertions at runtime. If its 72 condition isn't TRUE, the program will abort with a panic message. 73 Its code is compiled when either FT_DEBUG_LEVEL_ERROR or 74 FT_DEBUG_LEVEL_TRACE are defined. You don't need double parentheses 75 here. For example 76 77 FT_ASSERT( ptr != NULL ); 78 79 80 3. FT_TRACE( level, (message...) ) 81 82 The FT_TRACE macro is used to send general-purpose debugging 83 messages during program execution. This macro uses an *implicit* 84 macro named FT_COMPONENT used to name the current FreeType component 85 being run. 86 87 The developer should always define FT_COMPONENT as appropriate, for 88 example as in 89 90 #undef FT_COMPONENT 91 #define FT_COMPONENT trace_io 92 93 The value of the FT_COMPONENT macro is an enumeration named 94 trace_XXXX where XXXX is one of the component names defined in the 95 internal file `freetype/internal/fttrace.h'. If you modify FreeType 96 source and insert new trace_XXXX macro, you must register it in 97 fttrace.h. If you insert or remove many trace macros, you can check 98 the undefined or the unused trace macro by src/tools/chktrcmp.py. 99 100 Each such component is assigned a `debug level', ranging from 0 101 to 7, through the use of the FT2_DEBUG environment variable 102 (described below) when a program linked with FreeType starts. 103 104 When FT_TRACE is called, its level is compared to the one of the 105 corresponding component. Messages with trace levels *higher* than 106 the corresponding component level are filtered and never printed. 107 108 This means that trace messages with level 0 are always printed, 109 those with level 2 are only printed when the component level is *at 110 least* 2. 111 112 The second parameter to FT_TRACE must contain parentheses and 113 correspond to a printf-like call, as in 114 115 FT_TRACE( 2, ( "your %s is not %s\n", "foo", "bar" ) ) 116 117 The shortcut macros FT_TRACE0, FT_TRACE1, FT_TRACE2, ..., FT_TRACE7 118 can be used with constant level indices, and are much cleaner to 119 use, as in 120 121 FT_TRACE2(( "your %s is not %s\n", "foo", "bar" )); 122 123 124III. Environment variables 125-------------------------- 126 127The following environment variables control debugging output and 128behaviour of FreeType at runtime. 129 130 131 FT2_DEBUG 132 133 This variable is only used when FreeType is built with 134 FT_DEBUG_LEVEL_TRACE defined. It contains a list of component level 135 definitions, following this format: 136 137 component1:level1 component2:level2 component3:level3 ... 138 139 where `componentX' is the name of a tracing component, as defined in 140 `fttrace.h', but without the `trace_' prefix. `levelX' is the 141 corresponding level to use at runtime. 142 143 `any' is a special component name that will be interpreted as 144 `any/all components'. For example, the following definitions 145 146 set FT2_DEBUG=any:2 memory:5 io:4 (on Windows) 147 export FT2_DEBUG="any:2 memory:5 io:4" (on Linux with bash) 148 149 both stipulate that all components should have level 2, except for 150 the memory and io components which will be set to trace levels 5 and 151 4, respectively. 152 153 154 FT2_DEBUG_MEMORY 155 156 This environment variable, when defined, tells FreeType to use a 157 debugging memory manager that will track leaking memory blocks as 158 well as other common errors like double frees. It is also capable 159 of reporting _where_ the leaking blocks were allocated, which 160 considerably saves time when debugging new additions to the library. 161 162 This code is only compiled when FreeType is built with the 163 FT_DEBUG_MEMORY macro #defined in `ftoption.h' though, it will be 164 ignored in other builds. 165 166 167 FT2_ALLOC_TOTAL_MAX 168 169 This variable is ignored if FT2_DEBUG_MEMORY is not defined. It 170 allows you to specify a maximum heap size for all memory allocations 171 performed by FreeType. This is very useful to test the robustness 172 of the font engine and programs that use it in tight memory 173 conditions. 174 175 If it is undefined, or if its value is not strictly positive, then 176 no allocation bounds are checked at runtime. 177 178 179 FT2_ALLOC_COUNT_MAX 180 181 This variable is ignored if FT2_DEBUG_MEMORY is not defined. It 182 allows you to specify a maximum number of memory allocations 183 performed by FreeType before returning the error 184 FT_Err_Out_Of_Memory. This is useful for debugging and testing the 185 engine's robustness. 186 187 If it is undefined, or if its value is not strictly positive, then 188 no allocation bounds are checked at runtime. 189 190------------------------------------------------------------------------ 191 192Copyright 2002, 2003, 2004, 2005, 2009 by 193David Turner, Robert Wilhelm, and Werner Lemberg. 194 195This file is part of the FreeType project, and may only be used, 196modified, and distributed under the terms of the FreeType project 197license, LICENSE.TXT. By continuing to use, modify, or distribute this 198file you indicate that you have read the license and understand and 199accept it fully. 200 201 202--- end of DEBUG --- 203