1 Debugging within the FreeType sources 2 ===================================== 3 4 I. Configuration macros 5 ----------------------- 6 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 `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 48 II. Debugging macros 49 -------------------- 50 51 Several macros can be used within the FreeType sources to help 52 debugging its 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) without stopping 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 61 defined in `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 aborts 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 75 parentheses here. 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', which names the current FreeType 85 component being run. 86 87 The developer should always define `FT_COMPONENT' as appropriate, 88 for example as in 89 90 #undef FT_COMPONENT 91 #define FT_COMPONENT io 92 93 The value of the `FT_COMPONENT' macro is one of the component 94 names defined in the internal file `internal/fttrace.h'. If you 95 modify the FreeType source code and insert a new `FT_COMPONENT' 96 macro, you must register it in `fttrace.h'. If you insert or 97 remove many trace macros, you can test for undefined or unused 98 trace macros with the script `src/tools/chktrcmp.py'. 99 100 Each such component is assigned a `debug level', ranging from 101 value 0 to 7, through the use of the `FT2_DEBUG' environment 102 variable (described below) when a program linked with FreeType 103 starts. 104 105 When `FT_TRACE' is called, its level is compared to the one of the 106 corresponding component. Messages with trace levels *higher* than 107 the corresponding component level are filtered out and never 108 printed. This means that trace messages with level 0 are always 109 printed, those with level 2 are only printed when the component 110 level is *at least* 2, etc. 111 112 The second parameter to `FT_TRACE' must contain parentheses and 113 corresponds 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', ..., 118 `FT_TRACE7' can be used with constant level indices, and are much 119 cleaner to use, as in 120 121 FT_TRACE2(( "your %s is not %s\n", "foo", "bar" )); 122 123 124 III. Environment variables 125 -------------------------- 126 127 The following environment variables control debugging output and 128 behaviour 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 135 level 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 140 in `fttrace.h'. `levelX' is the corresponding level to use at 141 runtime. 142 143 `any' is a special component name that is interpreted as `any/all 144 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 are set to the trace levels 5 151 and 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 tracks leaking memory blocks as well 158 as other common errors like double frees. It is also capable of 159 reporting _where_ the leaking blocks were allocated, which 160 considerably saves time when debugging new additions to the 161 library. 162 163 This code is only compiled when FreeType is built with the 164 `FT_DEBUG_MEMORY' macro #defined in `ftoption.h' though, it is 165 ignored in other builds. 166 167 168 FT2_ALLOC_TOTAL_MAX 169 170 This variable is ignored if `FT2_DEBUG_MEMORY' is not defined. It 171 allows you to specify a maximum heap size for all memory 172 allocations performed by FreeType. This is very useful to test 173 the robustness of the font engine and programs that use it in 174 tight memory conditions. 175 176 If it is undefined, or if its value is not strictly positive, no 177 allocation bounds are checked at runtime. 178 179 180 FT2_ALLOC_COUNT_MAX 181 182 This variable is ignored if `FT2_DEBUG_MEMORY' is not defined. It 183 allows you to specify a maximum number of memory allocations 184 performed by FreeType before returning the error 185 `FT_Err_Out_Of_Memory'. This is useful for debugging and testing 186 the engine's robustness. 187 188 If it is undefined, or if its value is not strictly positive, no 189 allocation bounds are checked at runtime. 190 191 192 FT2_KEEP_ALIVE 193 194 This variable is ignored if `FT2_DEBUG_MEMORY' is not defined. 195 `Keep alive' means that freed blocks aren't released to the heap. 196 This is useful to detect double-frees or weird heap corruption, 197 reporting the source code location of the original allocation and 198 deallocation in case of a problem. It uses large amounts of 199 memory, however. 200 201 If it is undefined, or if its value is not strictly positive, 202 freed blocks are released at runtime. 203 204 ------------------------------------------------------------------------ 205 206 Copyright (C) 2002-2020 by 207 David Turner, Robert Wilhelm, and Werner Lemberg. 208 209 This file is part of the FreeType project, and may only be used, 210 modified, and distributed under the terms of the FreeType project 211 license, LICENSE.TXT. By continuing to use, modify, or distribute this 212 file you indicate that you have read the license and understand and 213 accept it fully. 214 215 216 --- end of DEBUG --- 217
Indexes created Mon Oct 26 00:26:21 UTC 2026