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