|
|
|
|
@ -6,7 +6,7 @@ I. Configuration macros |
|
|
|
|
|
|
|
|
|
There are several ways to enable debugging features in a FreeType 2 |
|
|
|
|
builds. This is controlled through the definition of special macros |
|
|
|
|
located in the file "ftoptions.h". The macros are: |
|
|
|
|
located in the file `ftoptions.h'. The macros are: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
FT_DEBUG_LEVEL_ERROR |
|
|
|
|
@ -23,7 +23,7 @@ located in the file "ftoptions.h". The macros are: |
|
|
|
|
FT_TRACE2, ..., FT_TRACE7. |
|
|
|
|
|
|
|
|
|
The trace macros are used to send debugging messages when an |
|
|
|
|
appropriate "debug level" is configured at runtime through the |
|
|
|
|
appropriate `debug level' is configured at runtime through the |
|
|
|
|
FT2_DEBUG environment variable (more on this later). |
|
|
|
|
|
|
|
|
|
FT_DEBUG_MEMORY |
|
|
|
|
@ -51,16 +51,17 @@ II. Debugging macros |
|
|
|
|
Several macros can be used within the FreeType sources to help debugging |
|
|
|
|
its code: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
1. FT_ERROR(( ... )) |
|
|
|
|
|
|
|
|
|
This macro is used to send debug messages that indicate relatively |
|
|
|
|
serious errors (like broken font files), but will not stop the |
|
|
|
|
execution of the running program. Its code is compiled only when |
|
|
|
|
either FT_DEBUG_LEVEL_ERROR or FT_DEBUG_LEVEL_TRACE are defined in |
|
|
|
|
"ftoption.h". |
|
|
|
|
`ftoption.h'. |
|
|
|
|
|
|
|
|
|
Note that you have to use a printf-like signature, but with double |
|
|
|
|
parentheses, like in: |
|
|
|
|
parentheses, like in |
|
|
|
|
|
|
|
|
|
FT_ERROR(( "your %s is not %s\n", "foo", "bar" )); |
|
|
|
|
|
|
|
|
|
@ -70,31 +71,31 @@ its code: |
|
|
|
|
This macro is used to check strong assertions at runtime. If its |
|
|
|
|
condition isn't TRUE, the program will abort with a panic message. |
|
|
|
|
Its code is compiled when either FT_DEBUG_LEVEL_ERROR or |
|
|
|
|
FT_DEBUG_LEVEL_TRACE are defined. You don't need double-parentheses |
|
|
|
|
here. For example: |
|
|
|
|
FT_DEBUG_LEVEL_TRACE are defined. You don't need double parentheses |
|
|
|
|
here. For example |
|
|
|
|
|
|
|
|
|
FT_ASSERT( ptr != NULL ); |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
3. FT_TRACE( level, (message...) ) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The FT_TRACE macro is used to send general-purpose debugging |
|
|
|
|
messages during program execution. This macro uses an *implicit* |
|
|
|
|
macro named FT_COMPONENT used to name the current FreeType component |
|
|
|
|
being run. |
|
|
|
|
|
|
|
|
|
The developer should always define FT_COMPONENT as appropriate, for |
|
|
|
|
example as in: |
|
|
|
|
example as in |
|
|
|
|
|
|
|
|
|
#undef FT_COMPONENT |
|
|
|
|
#define FT_COMPONENT trace_io |
|
|
|
|
|
|
|
|
|
The value of the FT_COMPONENT macro is an enumeration named |
|
|
|
|
trace_XXXX where XXXX is one of the component names defined in the |
|
|
|
|
internal file <freetype/internal/fttrace.h>. |
|
|
|
|
internal file `freetype/internal/fttrace.h'. |
|
|
|
|
|
|
|
|
|
Each such component is assigned a "debug level", ranging from 0 |
|
|
|
|
to 7, through the use of the FT2_DEBUG environment variable |
|
|
|
|
Each such component is assigned a `debug level', ranging from 0 |
|
|
|
|
to 7, through the use of the FT2_DEBUG environment variable |
|
|
|
|
(described below) when a program linked with FreeType starts. |
|
|
|
|
|
|
|
|
|
When FT_TRACE is called, its level is compared to the one of the |
|
|
|
|
@ -106,11 +107,11 @@ its code: |
|
|
|
|
least* 2. |
|
|
|
|
|
|
|
|
|
The second parameter to FT_TRACE must contain parentheses and |
|
|
|
|
correspond to a printf-like call, as in: |
|
|
|
|
correspond to a printf-like call, as in |
|
|
|
|
|
|
|
|
|
FT_TRACE( 2, ( "your %s is not %s\n", "foo", "bar" ) ) |
|
|
|
|
|
|
|
|
|
The shortcut macros FT_TRACE0, FT_TRACE1, FT_TRACE2_, ... FT_TRACE7 |
|
|
|
|
The shortcut macros FT_TRACE0, FT_TRACE1, FT_TRACE2, ..., FT_TRACE7 |
|
|
|
|
can be used with constant level indices, and are much cleaner to |
|
|
|
|
use, as in |
|
|
|
|
|
|
|
|
|
@ -121,7 +122,8 @@ III. Environment variables |
|
|
|
|
-------------------------- |
|
|
|
|
|
|
|
|
|
The following environment variables control debugging output and |
|
|
|
|
behaviour of FreeType at runtime: |
|
|
|
|
behaviour of FreeType at runtime. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
FT2_DEBUG |
|
|
|
|
|
|
|
|
|
@ -131,19 +133,20 @@ behaviour of FreeType at runtime: |
|
|
|
|
|
|
|
|
|
component1:level1 component2:level2 component3:level3 ... |
|
|
|
|
|
|
|
|
|
where "componentX" is the name of a tracing component, as defined in |
|
|
|
|
"fttrace.h", but without the "trace_" prefix. "levelX" is the |
|
|
|
|
where `componentX' is the name of a tracing component, as defined in |
|
|
|
|
`fttrace.h', but without the `trace_' prefix. `levelX' is the |
|
|
|
|
corresponding level to use at runtime. |
|
|
|
|
|
|
|
|
|
"any" is a special component name that will be interpreted as |
|
|
|
|
"any/all components". For example, the following definitions |
|
|
|
|
`any' is a special component name that will be interpreted as |
|
|
|
|
`any/all components'. For example, the following definitions |
|
|
|
|
|
|
|
|
|
set FT2_DEBUG=any:2 memory:5 io:4 (on Windows) |
|
|
|
|
export FT2_DEBUG="any:2 memory:5 io:4" (on Linux with bash) |
|
|
|
|
|
|
|
|
|
both stipulate that all components should have level 2, except for |
|
|
|
|
the memory and io components which will be set to trace levels 5 |
|
|
|
|
and 4, respectively. |
|
|
|
|
the memory and io components which will be set to trace levels 5 and |
|
|
|
|
4, respectively. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
FT2_DEBUG_MEMORY |
|
|
|
|
|
|
|
|
|
@ -154,9 +157,10 @@ behaviour of FreeType at runtime: |
|
|
|
|
considerably saves time when debugging new additions to the library. |
|
|
|
|
|
|
|
|
|
This code is only compiled when FreeType is built with the |
|
|
|
|
FT_DEBUG_MEMORY macro #defined in "ftoption.h" though, it will be |
|
|
|
|
FT_DEBUG_MEMORY macro #defined in `ftoption.h' though, it will be |
|
|
|
|
ignored in other builds. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
FT2_ALLOC_TOTAL_MAX |
|
|
|
|
|
|
|
|
|
This variable is ignored if FT2_DEBUG_MEMORY is not defined. It |
|
|
|
|
@ -168,6 +172,7 @@ behaviour of FreeType at runtime: |
|
|
|
|
If it is undefined, or if its value is not strictly positive, then |
|
|
|
|
no allocation bounds are checked at runtime. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
FT2_ALLOC_COUNT_MAX |
|
|
|
|
|
|
|
|
|
This variable is ignored if FT2_DEBUG_MEMORY is not defined. It |
|
|
|
|
@ -177,17 +182,17 @@ behaviour of FreeType at runtime: |
|
|
|
|
engine's robustness. |
|
|
|
|
|
|
|
|
|
If it is undefined, or if its value is not strictly positive, then |
|
|
|
|
no allocation bounsd are checked at runtime. |
|
|
|
|
no allocation bounds are checked at runtime. |
|
|
|
|
|
|
|
|
|
------------------------------------------------------------------------ |
|
|
|
|
|
|
|
|
|
Copyright 2002, 2003, 2004 by |
|
|
|
|
Copyright 2002, 2003, 2004, 2005 by |
|
|
|
|
David Turner, Robert Wilhelm, and Werner Lemberg. |
|
|
|
|
|
|
|
|
|
This file is part of the FreeType project, and may only be used, |
|
|
|
|
modified, and distributed under the terms of the FreeType project |
|
|
|
|
license, LICENSE.TXT. By continuing to use, modify, or distribute this |
|
|
|
|
file you indicate that you have read the license and understand and |
|
|
|
|
This file is part of the FreeType project, and may only be used, |
|
|
|
|
modified, and distributed under the terms of the FreeType project |
|
|
|
|
license, LICENSE.TXT. By continuing to use, modify, or distribute this |
|
|
|
|
file you indicate that you have read the license and understand and |
|
|
|
|
accept it fully. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Werner Lemberg
20 years ago