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 used to print error messages during program execution. This will 16 not stop the program, but is very useful to spot invalid fonts 17 during development and code wordarounds for them. 18 19 FT_DEBUG_LEVEL_TRACE 20 21 #define this macro if you want to compile both the FT_ERROR macro 22 and the FT_TRACE one. This also includes the variants FT_TRACE0, 23 FT_TRACE1, FT_TRACE2, ..., FT_TRACE6. 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 engines 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's 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 un-affected. 46 47 48II. Debugging macros 49-------------------- 50 51Several macros can be used within the FreeType sources to help debugging 52its code: 53 54 1. FT_ERROR(( ... )) 55 56 This macro is used to send debug messages that indicate relatively 57 serious errors (like broken font files), but will not stop the 58 execution of the running program. Its code is compiled only when 59 either FT_DEBUG_LEVEL_ERROR or FT_DEBUG_LEVEL_TRACE are defined in 60 "ftoption.h". 61 62 Note that you must use with a printf-like signature, but with double 63 parentheses, like in: 64 65 FT_ERROR(( "your %s is not %s\n", "foo", "bar" )); 66 67 68 2. FT_ASSERT( condition ) 69 70 This macro is used to check strong assertions at runtime. If its 71 condition isn't TRUE, the program will abort with a panic message. 72 Its code is compiled when either FT_DEBUG_LEVEL_ERROR or 73 FT_DEBUG_LEVEL_TRACE are defined. You don't need double-parentheses 74 here. For example: 75 76 FT_ASSERT( ptr != NULL ); 77 78 79 3. FT_TRACE( level, (message...) ) 80 81 The FT_TRACE macro is used to send general-purpose debugging 82 messages during program execution. This macro uses an *implicit* 83 macro named FT_COMPONENT used to name the current FreeType component 84 being run. 85 86 The developer should always define FT_COMPONENT as appropriate, for 87 example as in: 88 89 #undef FT_COMPONENT 90 #define FT_COMPONENT trace_io 91 92 The value of the FT_COMPONENT macro is an enumeration named 93 trace_XXXX where XXXX is one of the component names defined in the 94 internal file <freetype/internal/fttrace.h>. 95 96 Each such component is assigned a "debug level", ranging from 0 to 6 97 when a program linked with FreeType starts, through the use of the 98 FT2_DEBUG environment variable, described later. 99 100 When FT_TRACE is called, its level is compared to the one of the 101 corresponding component. Messages with trace levels *higher* than 102 the corresponding component level are filtered and never printed. 103 104 This means that trace messages with level 0 are always printed, 105 those with level 2 are only printed when the component level is *at 106 least* 2. 107 108 The second parameter to FT_TRACE must contain parentheses and 109 correspond to a print-like call, as in: 110 111 FT_TRACE( 2, ( "your %s is not %s\n", "foo", "bar" ) ) 112 113 The shortcut macros FT_TRACE0, FT_TRACE1, FT_TRACE2_, ... FT_TRACE6 114 can be used with constant level indices, and are much cleaner to 115 use, as in 116 117 FT_TRACE2(( "your %s is not %s\n", "foo", "bar" )); 118 119 120III. Environment variables 121-------------------------- 122 123The following environment variables control debugging output and 124behaviour of FreeType at runtime: 125 126 127 FT2_DEBUG 128 129 This variable is only used when FreeType is built with 130 FT_DEBUG_LEVEL_TRACE defined. It contains a list of component level 131 definitions, following this format: 132 133 component1:level1 component2:level2 component3:level3 ... 134 135 where "componentX" is the name of a tracing component, as defined in 136 "fttrace.h", but without the "trace_" prefix, and "levelX" is the 137 corresponding level to use at runtime. 138 139 "any" is a special component name that will be interpreted as 140 "any/all components". For example, the following definitions 141 142 set FT2_DEBUG=any:2 memory:5 io:4 (on Windows) 143 export FT2_DEBUG="any:2 memory:5 io:4" (on Linux) 144 145 both stipulate that all components should have level 2, except for 146 the memory and io components which will be set to trace levels 5 and 147 4 respectively. 148 149 FT2_DEBUG_MEMORY 150 151 This environment variable, when defined, tells FreeType to use a 152 debugging memory manager that will track leaked memory blocks as 153 well as other common errors like double frees. It is also capable 154 of reporting _where_ the leaked blocks were allocated, which 155 considerably saves time when debugging new additions to the library. 156 157 This code is only compiled when FreeType is built with the 158 FT_DEBUG_MEMORY macro #defined in "ftoption.h" though, it will be 159 ignored in other builds. 160 161 162End of file 163