From 02c3aede1bc6f26f9d54fbdeeb0c939c00799614 Mon Sep 17 00:00:00 2001 From: David Turner Date: Mon, 8 Jul 2002 23:02:32 +0000 Subject: [PATCH] * 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 --- ChangeLog | 13 +++ builds/amiga/src/base/ftdebug.c | 24 ++-- builds/win32/ftdebug.c | 12 +- docs/DEBUG.TXT | 164 ++++++++++++++++++++++++++++ include/freetype/internal/ftdebug.h | 9 +- src/base/ftdebug.c | 32 +++--- 6 files changed, 218 insertions(+), 36 deletions(-) create mode 100644 docs/DEBUG.TXT diff --git a/ChangeLog b/ChangeLog index 0be5f229f..514adbea4 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,16 @@ +2002-07-07 David Turner + + * 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 * include/freetype/freetype.h, src/base/ftobjs.h, diff --git a/builds/amiga/src/base/ftdebug.c b/builds/amiga/src/base/ftdebug.c index 7a04c1fe8..a61868746 100644 --- a/builds/amiga/src/base/ftdebug.c +++ b/builds/amiga/src/base/ftdebug.c @@ -100,49 +100,49 @@ extern void __stdargs KVPrintF( const char *formatString, const void *values ); ft_debug_init( void ) { const char* ft2_debug = getenv( "FT2_DEBUG" ); - + if ( ft2_debug ) { const char* p = ft2_debug; const char* q; - + for ( ; *p; p++ ) { /* skip leading whitespace and separators */ - if ( *p == ' ' || *p == '\t' || *p == ':' || *p == ';' || *p == '=' ) + if ( *p == ' ' || *p == '\t' || *p == ',' || *p == ';' || *p == '=' ) continue; - + /* read toggle name, followed by '=' */ q = p; - while ( *p && *p != '=' ) + while ( *p && *p != ':' ) p++; - - if ( *p == '=' && p > q ) + + if ( *p == ':' && p > q ) { int n, i, len = p - q; int level = -1, found = -1; - + for ( n = 0; n < trace_count; n++ ) { const char* toggle = ft_trace_toggles[n]; - + for ( i = 0; i < len; i++ ) { if ( toggle[i] != q[i] ) break; } - + if ( i == len && toggle[i] == 0 ) { found = n; break; } } - + /* read level */ p++; if ( *p ) @@ -151,7 +151,7 @@ extern void __stdargs KVPrintF( const char *formatString, const void *values ); if ( level < 0 || level > 6 ) level = -1; } - + if ( found >= 0 && level >= 0 ) { if ( found == trace_any ) diff --git a/builds/win32/ftdebug.c b/builds/win32/ftdebug.c index 7615172ed..5816a4f9a 100644 --- a/builds/win32/ftdebug.c +++ b/builds/win32/ftdebug.c @@ -107,9 +107,9 @@ /* */ /* Initialize the tracing sub-system. This is done by retrieving the */ /* 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 */ /* for the memory and stream components which are set to 6 and 5, */ @@ -136,15 +136,15 @@ for ( ; *p; p++ ) { /* skip leading whitespace and separators */ - if ( *p == ' ' || *p == '\t' || *p == ':' || *p == ';' || *p == '=' ) + if ( *p == ' ' || *p == '\t' || *p == ',' || *p == ';' || *p == '=' ) continue; - /* read toggle name, followed by '=' */ + /* read toggle name, followed by ':' */ q = p; - while ( *p && *p != '=' ) + while ( *p && *p != ':' ) p++; - if ( *p == '=' && p > q ) + if ( *p == ':' && p > q ) { int n, i, len = p - q; int level = -1, found = -1; diff --git a/docs/DEBUG.TXT b/docs/DEBUG.TXT new file mode 100644 index 000000000..86ffbcfa5 --- /dev/null +++ b/docs/DEBUG.TXT @@ -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 + + + 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 \ No newline at end of file diff --git a/include/freetype/internal/ftdebug.h b/include/freetype/internal/ftdebug.h index 039b17b5d..2820ebe93 100644 --- a/include/freetype/internal/ftdebug.h +++ b/include/freetype/internal/ftdebug.h @@ -13,6 +13,11 @@ /* this file you indicate that you have read the license and */ /* 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. */ +/* */ /***************************************************************************/ @@ -47,10 +52,10 @@ FT_BEGIN_HEADER #define FT_TRACE_DEF( x ) trace_ ## x , - /* defining the enumeration */ + /* defining the enumeration */ typedef enum { -#include FT_INTERNAL_TRACE_H +#include FT_INTERNAL_TRACE_H trace_count } FT_Trace; diff --git a/src/base/ftdebug.c b/src/base/ftdebug.c index 4c6bcc55c..65c823d73 100644 --- a/src/base/ftdebug.c +++ b/src/base/ftdebug.c @@ -86,7 +86,7 @@ #define FT_TRACE_DEF(x) #x , static const char* ft_trace_toggles[trace_count + 1] = - { + { #include FT_INTERNAL_TRACE_H NULL }; @@ -98,9 +98,9 @@ /* */ /* Initialize the tracing sub-system. This is done by retrieving the */ /* 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 */ /* for the memory and stream components which are set to 6 and 5, */ @@ -116,48 +116,48 @@ ft_debug_init( void ) { const char* ft2_debug = getenv( "FT2_DEBUG" ); - + if ( ft2_debug ) { const char* p = ft2_debug; const char* q; - + for ( ; *p; p++ ) { /* skip leading whitespace and separators */ - if ( *p == ' ' || *p == '\t' || *p == ':' || *p == ';' || *p == '=' ) + if ( *p == ' ' || *p == '\t' || *p == ',' || *p == ';' || *p == '=' ) continue; - - /* read toggle name, followed by '=' */ + + /* read toggle name, followed by ':' */ q = p; - while ( *p && *p != '=' ) + while ( *p && *p != ':' ) p++; - - if ( *p == '=' && p > q ) + + if ( *p == ':' && p > q ) { int n, i, len = p - q; int level = -1, found = -1; - + for ( n = 0; n < trace_count; n++ ) { const char* toggle = ft_trace_toggles[n]; - + for ( i = 0; i < len; i++ ) { if ( toggle[i] != q[i] ) break; } - + if ( i == len && toggle[i] == 0 ) { found = n; break; } } - + /* read level */ p++; if ( *p ) @@ -166,7 +166,7 @@ if ( level < 0 || level > 6 ) level = -1; } - + if ( found >= 0 && level >= 0 ) { if ( found == trace_any )