* docs/DEBUG.TXT: adding debugging support documentation
* src/base/ftdebug.c (ft_debug_init), builds/win32/ftdebug.c (ft_debug_init), builds/amiga/src/ftdebug.c (ft_debug_init): changed the syntax of the FT2_DEBUG environment variable used to control debugging output (i.e. logging and error messages). It must now look like: any:6 memory:4 io:3 or any:6,memory:4,io:3 or any:6;memory:4;io:3
This commit is contained in:
parent
27c322e983
commit
02c3aede1b
13
ChangeLog
13
ChangeLog
|
@ -1,3 +1,16 @@
|
||||||
|
2002-07-07 David Turner <david@freetype.org>
|
||||||
|
|
||||||
|
* docs/DEBUG.TXT: adding debugging support documentation
|
||||||
|
|
||||||
|
* src/base/ftdebug.c (ft_debug_init), builds/win32/ftdebug.c
|
||||||
|
(ft_debug_init), builds/amiga/src/ftdebug.c (ft_debug_init): changed the
|
||||||
|
syntax of the FT2_DEBUG environment variable used to control debugging
|
||||||
|
output (i.e. logging and error messages). It must now look like:
|
||||||
|
|
||||||
|
any:6 memory:4 io:3 or
|
||||||
|
any:6,memory:4,io:3 or
|
||||||
|
any:6;memory:4;io:3
|
||||||
|
|
||||||
2002-07-07 Owen Taylor <owen@redhat.com>
|
2002-07-07 Owen Taylor <owen@redhat.com>
|
||||||
|
|
||||||
* include/freetype/freetype.h, src/base/ftobjs.h,
|
* include/freetype/freetype.h, src/base/ftobjs.h,
|
||||||
|
|
|
@ -111,15 +111,15 @@ extern void __stdargs KVPrintF( const char *formatString, const void *values );
|
||||||
for ( ; *p; p++ )
|
for ( ; *p; p++ )
|
||||||
{
|
{
|
||||||
/* skip leading whitespace and separators */
|
/* skip leading whitespace and separators */
|
||||||
if ( *p == ' ' || *p == '\t' || *p == ':' || *p == ';' || *p == '=' )
|
if ( *p == ' ' || *p == '\t' || *p == ',' || *p == ';' || *p == '=' )
|
||||||
continue;
|
continue;
|
||||||
|
|
||||||
/* read toggle name, followed by '=' */
|
/* read toggle name, followed by '=' */
|
||||||
q = p;
|
q = p;
|
||||||
while ( *p && *p != '=' )
|
while ( *p && *p != ':' )
|
||||||
p++;
|
p++;
|
||||||
|
|
||||||
if ( *p == '=' && p > q )
|
if ( *p == ':' && p > q )
|
||||||
{
|
{
|
||||||
int n, i, len = p - q;
|
int n, i, len = p - q;
|
||||||
int level = -1, found = -1;
|
int level = -1, found = -1;
|
||||||
|
|
|
@ -107,9 +107,9 @@
|
||||||
/* */
|
/* */
|
||||||
/* Initialize the tracing sub-system. This is done by retrieving the */
|
/* Initialize the tracing sub-system. This is done by retrieving the */
|
||||||
/* value of the "FT2_DEBUG" environment variable. It must be a list of */
|
/* value of the "FT2_DEBUG" environment variable. It must be a list of */
|
||||||
/* toggles, separated by spaces, `;' or `:'. Example: */
|
/* toggles, separated by spaces, `;' or `,'. Example: */
|
||||||
/* */
|
/* */
|
||||||
/* "any=3 memory=6 stream=5" */
|
/* "any:3 memory:6 stream:5" */
|
||||||
/* */
|
/* */
|
||||||
/* This will request that all levels be set to 3, except the trace level */
|
/* This will request that all levels be set to 3, except the trace level */
|
||||||
/* for the memory and stream components which are set to 6 and 5, */
|
/* for the memory and stream components which are set to 6 and 5, */
|
||||||
|
@ -136,15 +136,15 @@
|
||||||
for ( ; *p; p++ )
|
for ( ; *p; p++ )
|
||||||
{
|
{
|
||||||
/* skip leading whitespace and separators */
|
/* skip leading whitespace and separators */
|
||||||
if ( *p == ' ' || *p == '\t' || *p == ':' || *p == ';' || *p == '=' )
|
if ( *p == ' ' || *p == '\t' || *p == ',' || *p == ';' || *p == '=' )
|
||||||
continue;
|
continue;
|
||||||
|
|
||||||
/* read toggle name, followed by '=' */
|
/* read toggle name, followed by ':' */
|
||||||
q = p;
|
q = p;
|
||||||
while ( *p && *p != '=' )
|
while ( *p && *p != ':' )
|
||||||
p++;
|
p++;
|
||||||
|
|
||||||
if ( *p == '=' && p > q )
|
if ( *p == ':' && p > q )
|
||||||
{
|
{
|
||||||
int n, i, len = p - q;
|
int n, i, len = p - q;
|
||||||
int level = -1, found = -1;
|
int level = -1, found = -1;
|
||||||
|
|
|
@ -0,0 +1,164 @@
|
||||||
|
Debugging within the FreeType sources:
|
||||||
|
======================================
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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 ::
|
||||||
|
|
||||||
|
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 FT2_DEBUG_MEMORY isn't defined at runtime, the debugging memory
|
||||||
|
manager is ignored, and performance is un-affected.
|
||||||
|
|
||||||
|
|
||||||
|
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"
|
||||||
|
|
||||||
|
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" ));
|
||||||
|
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
#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>
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
FT_TRACE2(( "your %s is not %s\n", "foo", "bar" ));
|
||||||
|
|
||||||
|
|
||||||
|
III. Environment variables:
|
||||||
|
===========================
|
||||||
|
|
||||||
|
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 ...
|
||||||
|
|
||||||
|
where "componentX" is the name of a tracing component, as defined in
|
||||||
|
"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
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
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
|
|
@ -13,6 +13,11 @@
|
||||||
/* this file you indicate that you have read the license and */
|
/* this file you indicate that you have read the license and */
|
||||||
/* understand and accept it fully. */
|
/* understand and accept it fully. */
|
||||||
/* */
|
/* */
|
||||||
|
/* */
|
||||||
|
/* IMPORTANT: A description of FreeType's debugging support can be */
|
||||||
|
/* found in "docs/DEBUG.TXT". Read it if you need to use */
|
||||||
|
/* or understand this code. */
|
||||||
|
/* */
|
||||||
/***************************************************************************/
|
/***************************************************************************/
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -98,9 +98,9 @@
|
||||||
/* */
|
/* */
|
||||||
/* Initialize the tracing sub-system. This is done by retrieving the */
|
/* Initialize the tracing sub-system. This is done by retrieving the */
|
||||||
/* value of the "FT2_DEBUG" environment variable. It must be a list of */
|
/* value of the "FT2_DEBUG" environment variable. It must be a list of */
|
||||||
/* toggles, separated by spaces, `;' or `:'. Example: */
|
/* toggles, separated by spaces, `;' or `,'. Example: */
|
||||||
/* */
|
/* */
|
||||||
/* "any=3 memory=6 stream=5" */
|
/* "any:3 memory:6 stream:5" */
|
||||||
/* */
|
/* */
|
||||||
/* This will request that all levels be set to 3, except the trace level */
|
/* This will request that all levels be set to 3, except the trace level */
|
||||||
/* for the memory and stream components which are set to 6 and 5, */
|
/* for the memory and stream components which are set to 6 and 5, */
|
||||||
|
@ -126,15 +126,15 @@
|
||||||
for ( ; *p; p++ )
|
for ( ; *p; p++ )
|
||||||
{
|
{
|
||||||
/* skip leading whitespace and separators */
|
/* skip leading whitespace and separators */
|
||||||
if ( *p == ' ' || *p == '\t' || *p == ':' || *p == ';' || *p == '=' )
|
if ( *p == ' ' || *p == '\t' || *p == ',' || *p == ';' || *p == '=' )
|
||||||
continue;
|
continue;
|
||||||
|
|
||||||
/* read toggle name, followed by '=' */
|
/* read toggle name, followed by ':' */
|
||||||
q = p;
|
q = p;
|
||||||
while ( *p && *p != '=' )
|
while ( *p && *p != ':' )
|
||||||
p++;
|
p++;
|
||||||
|
|
||||||
if ( *p == '=' && p > q )
|
if ( *p == ':' && p > q )
|
||||||
{
|
{
|
||||||
int n, i, len = p - q;
|
int n, i, len = p - q;
|
||||||
int level = -1, found = -1;
|
int level = -1, found = -1;
|
||||||
|
|
Loading…
Reference in New Issue