6 |
|
|
7 |
There are several ways to enable debugging features in a FreeType 2 |
There are several ways to enable debugging features in a FreeType 2 |
8 |
builds. This is controlled through the definition of special macros |
builds. This is controlled through the definition of special macros |
9 |
located in the file "ftoptions.h". The macros are: |
located in the file `ftoptions.h'. The macros are: |
10 |
|
|
11 |
|
|
12 |
FT_DEBUG_LEVEL_ERROR |
FT_DEBUG_LEVEL_ERROR |
23 |
FT_TRACE2, ..., FT_TRACE7. |
FT_TRACE2, ..., FT_TRACE7. |
24 |
|
|
25 |
The trace macros are used to send debugging messages when an |
The trace macros are used to send debugging messages when an |
26 |
appropriate "debug level" is configured at runtime through the |
appropriate `debug level' is configured at runtime through the |
27 |
FT2_DEBUG environment variable (more on this later). |
FT2_DEBUG environment variable (more on this later). |
28 |
|
|
29 |
FT_DEBUG_MEMORY |
FT_DEBUG_MEMORY |
51 |
Several macros can be used within the FreeType sources to help debugging |
Several macros can be used within the FreeType sources to help debugging |
52 |
its code: |
its code: |
53 |
|
|
54 |
|
|
55 |
1. FT_ERROR(( ... )) |
1. FT_ERROR(( ... )) |
56 |
|
|
57 |
This macro is used to send debug messages that indicate relatively |
This macro is used to send debug messages that indicate relatively |
58 |
serious errors (like broken font files), but will not stop the |
serious errors (like broken font files), but will not stop the |
59 |
execution of the running program. Its code is compiled only when |
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 |
either FT_DEBUG_LEVEL_ERROR or FT_DEBUG_LEVEL_TRACE are defined in |
61 |
"ftoption.h". |
`ftoption.h'. |
62 |
|
|
63 |
Note that you have to use a printf-like signature, but with double |
Note that you have to use a printf-like signature, but with double |
64 |
parentheses, like in: |
parentheses, like in |
65 |
|
|
66 |
FT_ERROR(( "your %s is not %s\n", "foo", "bar" )); |
FT_ERROR(( "your %s is not %s\n", "foo", "bar" )); |
67 |
|
|
71 |
This macro is used to check strong assertions at runtime. If its |
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. |
condition isn't TRUE, the program will abort with a panic message. |
73 |
Its code is compiled when either FT_DEBUG_LEVEL_ERROR or |
Its code is compiled when either FT_DEBUG_LEVEL_ERROR or |
74 |
FT_DEBUG_LEVEL_TRACE are defined. You don't need double-parentheses |
FT_DEBUG_LEVEL_TRACE are defined. You don't need double parentheses |
75 |
here. For example: |
here. For example |
76 |
|
|
77 |
FT_ASSERT( ptr != NULL ); |
FT_ASSERT( ptr != NULL ); |
78 |
|
|
79 |
|
|
80 |
3. FT_TRACE( level, (message...) ) |
3. FT_TRACE( level, (message...) ) |
81 |
|
|
82 |
The FT_TRACE macro is used to send general-purpose debugging |
The FT_TRACE macro is used to send general-purpose debugging |
83 |
messages during program execution. This macro uses an *implicit* |
messages during program execution. This macro uses an *implicit* |
84 |
macro named FT_COMPONENT used to name the current FreeType component |
macro named FT_COMPONENT used to name the current FreeType component |
85 |
being run. |
being run. |
86 |
|
|
87 |
The developer should always define FT_COMPONENT as appropriate, for |
The developer should always define FT_COMPONENT as appropriate, for |
88 |
example as in: |
example as in |
89 |
|
|
90 |
#undef FT_COMPONENT |
#undef FT_COMPONENT |
91 |
#define FT_COMPONENT trace_io |
#define FT_COMPONENT trace_io |
92 |
|
|
93 |
The value of the FT_COMPONENT macro is an enumeration named |
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 |
trace_XXXX where XXXX is one of the component names defined in the |
95 |
internal file <freetype/internal/fttrace.h>. |
internal file `freetype/internal/fttrace.h'. |
96 |
|
|
97 |
Each such component is assigned a "debug level", ranging from 0 |
Each such component is assigned a `debug level', ranging from 0 |
98 |
to 7, through the use of the FT2_DEBUG environment variable |
to 7, through the use of the FT2_DEBUG environment variable |
99 |
(described below) when a program linked with FreeType starts. |
(described below) when a program linked with FreeType starts. |
100 |
|
|
101 |
When FT_TRACE is called, its level is compared to the one of the |
When FT_TRACE is called, its level is compared to the one of the |
107 |
least* 2. |
least* 2. |
108 |
|
|
109 |
The second parameter to FT_TRACE must contain parentheses and |
The second parameter to FT_TRACE must contain parentheses and |
110 |
correspond to a printf-like call, as in: |
correspond to a printf-like call, as in |
111 |
|
|
112 |
FT_TRACE( 2, ( "your %s is not %s\n", "foo", "bar" ) ) |
FT_TRACE( 2, ( "your %s is not %s\n", "foo", "bar" ) ) |
113 |
|
|
114 |
The shortcut macros FT_TRACE0, FT_TRACE1, FT_TRACE2_, ... FT_TRACE7 |
The shortcut macros FT_TRACE0, FT_TRACE1, FT_TRACE2, ..., FT_TRACE7 |
115 |
can be used with constant level indices, and are much cleaner to |
can be used with constant level indices, and are much cleaner to |
116 |
use, as in |
use, as in |
117 |
|
|
122 |
-------------------------- |
-------------------------- |
123 |
|
|
124 |
The following environment variables control debugging output and |
The following environment variables control debugging output and |
125 |
behaviour of FreeType at runtime: |
behaviour of FreeType at runtime. |
126 |
|
|
127 |
|
|
128 |
FT2_DEBUG |
FT2_DEBUG |
129 |
|
|
133 |
|
|
134 |
component1:level1 component2:level2 component3:level3 ... |
component1:level1 component2:level2 component3:level3 ... |
135 |
|
|
136 |
where "componentX" is the name of a tracing component, as defined in |
where `componentX' is the name of a tracing component, as defined in |
137 |
"fttrace.h", but without the "trace_" prefix. "levelX" is the |
`fttrace.h', but without the `trace_' prefix. `levelX' is the |
138 |
corresponding level to use at runtime. |
corresponding level to use at runtime. |
139 |
|
|
140 |
"any" is a special component name that will be interpreted as |
`any' is a special component name that will be interpreted as |
141 |
"any/all components". For example, the following definitions |
`any/all components'. For example, the following definitions |
142 |
|
|
143 |
set FT2_DEBUG=any:2 memory:5 io:4 (on Windows) |
set FT2_DEBUG=any:2 memory:5 io:4 (on Windows) |
144 |
export FT2_DEBUG="any:2 memory:5 io:4" (on Linux with bash) |
export FT2_DEBUG="any:2 memory:5 io:4" (on Linux with bash) |
145 |
|
|
146 |
both stipulate that all components should have level 2, except for |
both stipulate that all components should have level 2, except for |
147 |
the memory and io components which will be set to trace levels 5 |
the memory and io components which will be set to trace levels 5 and |
148 |
and 4, respectively. |
4, respectively. |
149 |
|
|
150 |
|
|
151 |
FT2_DEBUG_MEMORY |
FT2_DEBUG_MEMORY |
152 |
|
|
157 |
considerably saves time when debugging new additions to the library. |
considerably saves time when debugging new additions to the library. |
158 |
|
|
159 |
This code is only compiled when FreeType is built with the |
This code is only compiled when FreeType is built with the |
160 |
FT_DEBUG_MEMORY macro #defined in "ftoption.h" though, it will be |
FT_DEBUG_MEMORY macro #defined in `ftoption.h' though, it will be |
161 |
ignored in other builds. |
ignored in other builds. |
162 |
|
|
163 |
|
|
164 |
FT2_ALLOC_TOTAL_MAX |
FT2_ALLOC_TOTAL_MAX |
165 |
|
|
166 |
This variable is ignored if FT2_DEBUG_MEMORY is not defined. It |
This variable is ignored if FT2_DEBUG_MEMORY is not defined. It |
172 |
If it is undefined, or if its value is not strictly positive, then |
If it is undefined, or if its value is not strictly positive, then |
173 |
no allocation bounds are checked at runtime. |
no allocation bounds are checked at runtime. |
174 |
|
|
175 |
|
|
176 |
FT2_ALLOC_COUNT_MAX |
FT2_ALLOC_COUNT_MAX |
177 |
|
|
178 |
This variable is ignored if FT2_DEBUG_MEMORY is not defined. It |
This variable is ignored if FT2_DEBUG_MEMORY is not defined. It |
182 |
engine's robustness. |
engine's robustness. |
183 |
|
|
184 |
If it is undefined, or if its value is not strictly positive, then |
If it is undefined, or if its value is not strictly positive, then |
185 |
no allocation bounsd are checked at runtime. |
no allocation bounds are checked at runtime. |
186 |
|
|
187 |
------------------------------------------------------------------------ |
------------------------------------------------------------------------ |
188 |
|
|
189 |
Copyright 2002, 2003, 2004 by |
Copyright 2002, 2003, 2004, 2005 by |
190 |
David Turner, Robert Wilhelm, and Werner Lemberg. |
David Turner, Robert Wilhelm, and Werner Lemberg. |
191 |
|
|
192 |
This file is part of the FreeType project, and may only be used, |
This file is part of the FreeType project, and may only be used, |
193 |
modified, and distributed under the terms of the FreeType project |
modified, and distributed under the terms of the FreeType project |
194 |
license, LICENSE.TXT. By continuing to use, modify, or distribute this |
license, LICENSE.TXT. By continuing to use, modify, or distribute this |
195 |
file you indicate that you have read the license and understand and |
file you indicate that you have read the license and understand and |
196 |
accept it fully. |
accept it fully. |
197 |
|
|
198 |
|
|