Werner Lemberg
23 years ago
parent
2ed0ddbca8
commit
c5f6cd72f6
28 changed files with 900 additions and 696 deletions
@ -1,164 +1,162 @@ |
||||
Debugging within the FreeType sources: |
||||
====================================== |
||||
|
||||
I. Configuration macros: |
||||
======================== |
||||
I. Configuration macros |
||||
----------------------- |
||||
|
||||
There are several ways to enable debugging features in a FreeType 2 builds. |
||||
This is controled through the definition of special macros located in the |
||||
file "ftoptions.h". The macros are: |
||||
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: |
||||
|
||||
|
||||
FT_DEBUG_LEVEL_ERROR :: |
||||
FT_DEBUG_LEVEL_ERROR |
||||
|
||||
#define this macro if you want to compile the FT_ERROR macro calls |
||||
used to print error messages during program execution. This will not |
||||
stop the program, but is very useful to spot invalid fonts during |
||||
development and code wordarounds for them. |
||||
#define this macro if you want to compile the FT_ERROR macro calls |
||||
used to print error messages during program execution. This will |
||||
not stop the program, but is very useful to spot invalid fonts |
||||
during development and code wordarounds for them. |
||||
|
||||
FT_DEBUG_LEVEL_TRACE |
||||
|
||||
FT_DEBUG_LEVEL_TRACE :: |
||||
#define this macro if you want to compile both the FT_ERROR macro |
||||
and the FT_TRACE one. This also includes the variants FT_TRACE0, |
||||
FT_TRACE1, FT_TRACE2, ..., FT_TRACE6. |
||||
|
||||
#define this macro if you want to compile both the FT_ERROR macro and |
||||
the FT_TRACE one. This also includes the variants FT_TRACE0, FT_TRACE1, |
||||
FT_TRACE2, ..., FT_TRACE6. |
||||
The trace macros are used to send debugging messages when an |
||||
appropriate "debug level" is configured at runtime through the |
||||
FT2_DEBUG environment variable (more on this later). |
||||
|
||||
The trace macros are used to send debugging messages when an appropriate |
||||
"debug level" is configured at runtime through the FT2_DEBUG environment |
||||
variable (more on this later) |
||||
FT_DEBUG_MEMORY |
||||
|
||||
If this macro is #defined, the FreeType engines is linked with a |
||||
small but effective debugging memory manager that tracks all |
||||
allocations and frees that are performed within the font engine. |
||||
|
||||
FT_DEBUG_MEMORY :: |
||||
|
||||
when this macro is #defined, the FreeType engines is linked with a small |
||||
but effective debugging memory manager that tracks all allocations and |
||||
frees that are performed within the font engine. |
||||
|
||||
When the FT2_DEBUG_MEMORY environment variable is defined at runtime, a |
||||
call to FT_Done_FreeType will dump memory statistics, including the list of |
||||
leaked memory blocks with the source locations where these were allocated. |
||||
It's always a very good idea to define this in development builds. This |
||||
works with _any_ program linked to FreeType, but requires a big deal of |
||||
memory (the debugging memory manager never frees the blocks to the |
||||
heap in order to detect double frees). |
||||
When the FT2_DEBUG_MEMORY environment variable is defined at |
||||
runtime, a call to FT_Done_FreeType will dump memory statistics, |
||||
including the list of leaked memory blocks with the source locations |
||||
where these were allocated. It's always a very good idea to define |
||||
this in development builds. This works with _any_ program linked to |
||||
FreeType, but requires a big deal of memory (the debugging memory |
||||
manager never frees the blocks to the heap in order to detect double |
||||
frees). |
||||
|
||||
When FT2_DEBUG_MEMORY isn't defined at runtime, the debugging memory |
||||
manager is ignored, and performance is un-affected. |
||||
|
||||
|
||||
II. Debugging macros: |
||||
===================== |
||||
II. Debugging macros |
||||
-------------------- |
||||
|
||||
Several macros can be used within the FreeType sources to help debugging |
||||
its code: |
||||
Several macros can be used within the FreeType sources to help debugging |
||||
its code: |
||||
|
||||
1. FT_ERROR(( .. )) |
||||
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" |
||||
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". |
||||
|
||||
Note that you must use with a printf-like signature, but with double |
||||
parentheses, like in: |
||||
Note that you must use with a printf-like signature, but with double |
||||
parentheses, like in: |
||||
|
||||
FT_ERROR(( "your %s is not %s\n", "foo", "bar" )); |
||||
FT_ERROR(( "your %s is not %s\n", "foo", "bar" )); |
||||
|
||||
|
||||
2. FT_ASSERT( condition ) |
||||
2. FT_ASSERT( condition ) |
||||
|
||||
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: |
||||
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_ASSERT( ptr != NULL ); |
||||
FT_ASSERT( ptr != NULL ); |
||||
|
||||
|
||||
3. FT_TRACE( level, (message...) ) |
||||
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 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: |
||||
The developer should always define FT_COMPONENT as appropriate, for |
||||
example as in: |
||||
|
||||
#undef FT_COMPONENT |
||||
#define FT_COMPONENT trace_io |
||||
#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> |
||||
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>. |
||||
|
||||
Each such component is assigned a "debug level", ranging from 0 to 6 |
||||
when a program linked with FreeType starts, through the use of the FT2_DEBUG |
||||
environment variable, described later. |
||||
Each such component is assigned a "debug level", ranging from 0 to 6 |
||||
when a program linked with FreeType starts, through the use of the |
||||
FT2_DEBUG environment variable, described later. |
||||
|
||||
When FT_TRACE is called, its level is compared to the one of the |
||||
corresponding component. Messages with trace levels *higher* than the |
||||
corresponding component level are filtered and never printed. |
||||
When FT_TRACE is called, its level is compared to the one of the |
||||
corresponding component. Messages with trace levels *higher* than |
||||
the corresponding component level are filtered and never printed. |
||||
|
||||
this means that trace messages with level 0 are always printed, those |
||||
with level 2 are only printed when the component level is *at least* 2 |
||||
This means that trace messages with level 0 are always printed, |
||||
those with level 2 are only printed when the component level is *at |
||||
least* 2. |
||||
|
||||
The second parameter to FT_TRACE must contain parentheses and correspond |
||||
to a print-like call, as in: |
||||
The second parameter to FT_TRACE must contain parentheses and |
||||
correspond to a print-like call, as in: |
||||
|
||||
FT_TRACE( 2, ( "your %s is not %s\n", "foo", "bar" ) ) |
||||
FT_TRACE( 2, ( "your %s is not %s\n", "foo", "bar" ) ) |
||||
|
||||
The shortcut macros FT_TRACE0, FT_TRACE1, FT_TRACE2_, ... FT_TRACE6 can |
||||
be used with constant level indices, and are much cleaner to use, as in |
||||
The shortcut macros FT_TRACE0, FT_TRACE1, FT_TRACE2_, ... FT_TRACE6 |
||||
can be used with constant level indices, and are much cleaner to |
||||
use, as in |
||||
|
||||
FT_TRACE2(( "your %s is not %s\n", "foo", "bar" )); |
||||
|
||||
|
||||
III. Environment variables: |
||||
=========================== |
||||
III. Environment variables |
||||
-------------------------- |
||||
|
||||
The following environment variables control debugging output and behaviour |
||||
of FreeType at runtime: |
||||
The following environment variables control debugging output and |
||||
behaviour of FreeType at runtime: |
||||
|
||||
|
||||
FT2_DEBUG |
||||
this variable is only used when FreeType is built with FT_DEBUG_LEVEL_TRACE |
||||
defined. It contains a list of component level definitions, following this |
||||
format: |
||||
|
||||
component1:level1 component2:level2 component3:level3 ... |
||||
This variable is only used when FreeType is built with |
||||
FT_DEBUG_LEVEL_TRACE defined. It contains a list of component level |
||||
definitions, following this format: |
||||
|
||||
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, and "levelX" is the |
||||
"fttrace.h", but without the "trace_" prefix, and "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) |
||||
|
||||
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. |
||||
|
||||
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. |
||||
|
||||
FT2_DEBUG_MEMORY |
||||
this environment variable, when defined, tells FreeType to use a debugging |
||||
memory manager that will track leaked memory blocks as well as other common |
||||
errors like double frees. It is also capable of reporting _where_ the |
||||
leaked blocks were allocated, which 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 ignored in other builds. |
||||
|
||||
|
||||
Voila, |
||||
|
||||
- David Turner |
||||
This environment variable, when defined, tells FreeType to use a |
||||
debugging memory manager that will track leaked memory blocks as |
||||
well as other common errors like double frees. It is also capable |
||||
of reporting _where_ the leaked blocks were allocated, which |
||||
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 |
||||
ignored in other builds. |
||||
|
||||
|
||||
used like printf( format, ... ), but with double quotes. This will |
||||
send a message to the standard error descriptor (stderr on most systems) |
||||
in certain builds of the library |
||||
End of file |
||||
|
||||
Loading…
Reference in new issue