The Tor Browser / file comparison

comparison: modules/freetype2/docs/DEBUG

modules/freetype2/docs/DEBUG

changeset 0
6474c204b198
equal deleted inserted replaced
-1:000000000000 0:3210324b7fca
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 `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
38 locations where these were allocated. It is always a very good
39 idea to define this in development builds. This works with _any_
40 program linked to FreeType, but requires a big deal of memory (the
41 debugging memory manager never frees the blocks to the heap in
42 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), 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
75 parentheses 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
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 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
95 the internal file `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
98 check the undefined or the unused trace macro by
99 `src/tools/chktrcmp.py'.
100
101 Each such component is assigned a `debug level', ranging from 0 to
102 7, through the use of the FT2_DEBUG environment variable
103 (described below) when a program linked with FreeType 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 and never printed.
108
109 This means that trace messages with level 0 are always printed,
110 those with level 2 are only printed when the component level is
111 *at least* 2.
112
113 The second parameter to FT_TRACE must contain parentheses and
114 correspond to a printf-like call, as in
115
116 FT_TRACE( 2, ( "your %s is not %s\n", "foo", "bar" ) )
117
118 The shortcut macros FT_TRACE0, FT_TRACE1, FT_TRACE2, ...,
119 FT_TRACE7 can be used with constant level indices, and are much
120 cleaner to use, as in
121
122 FT_TRACE2(( "your %s is not %s\n", "foo", "bar" ));
123
124
125 III. Environment variables
126 --------------------------
127
128 The following environment variables control debugging output and
129 behaviour of FreeType at runtime.
130
131
132 FT2_DEBUG
133
134 This variable is only used when FreeType is built with
135 FT_DEBUG_LEVEL_TRACE defined. It contains a list of component
136 level definitions, following this format:
137
138 component1:level1 component2:level2 component3:level3 ...
139
140 where `componentX' is the name of a tracing component, as defined
141 in `fttrace.h', but without the `trace_' prefix. `levelX' is the
142 corresponding level to use at runtime.
143
144 `any' is a special component name that will be interpreted as
145 `any/all components'. For example, the following definitions
146
147 set FT2_DEBUG=any:2 memory:5 io:4 (on Windows)
148 export FT2_DEBUG="any:2 memory:5 io:4" (on Linux with bash)
149
150 both stipulate that all components should have level 2, except for
151 the memory and io components which will be set to trace levels 5
152 and 4, respectively.
153
154
155 FT2_DEBUG_MEMORY
156
157 This environment variable, when defined, tells FreeType to use a
158 debugging memory manager that will track leaking memory blocks as
159 well as other common errors like double frees. It is also capable
160 of reporting _where_ the leaking blocks were allocated, which
161 considerably saves time when debugging new additions to the
162 library.
163
164 This code is only compiled when FreeType is built with the
165 FT_DEBUG_MEMORY macro #defined in `ftoption.h' though, it will be
166 ignored in other builds.
167
168
169 FT2_ALLOC_TOTAL_MAX
170
171 This variable is ignored if FT2_DEBUG_MEMORY is not defined. It
172 allows you to specify a maximum heap size for all memory
173 allocations performed by FreeType. This is very useful to test
174 the robustness of the font engine and programs that use it in
175 tight memory conditions.
176
177 If it is undefined, or if its value is not strictly positive, then
178 no allocation bounds are checked at runtime.
179
180
181 FT2_ALLOC_COUNT_MAX
182
183 This variable is ignored if FT2_DEBUG_MEMORY is not defined. It
184 allows you to specify a maximum number of memory allocations
185 performed by FreeType before returning the error
186 FT_Err_Out_Of_Memory. This is useful for debugging and testing
187 the engine's robustness.
188
189 If it is undefined, or if its value is not strictly positive, then
190 no allocation bounds are checked at runtime.
191
192 ------------------------------------------------------------------------
193
194 Copyright 2002-2005, 2009, 2013 by
195 David Turner, Robert Wilhelm, and Werner Lemberg.
196
197 This file is part of the FreeType project, and may only be used,
198 modified, and distributed under the terms of the FreeType project
199 license, LICENSE.TXT. By continuing to use, modify, or distribute this
200 file you indicate that you have read the license and understand and
201 accept it fully.
202
203
204 --- end of DEBUG ---

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial