diff options
author | David Turner <david@freetype.org> | 2002-07-08 23:02:32 +0000 |
---|---|---|
committer | David Turner <david@freetype.org> | 2002-07-08 23:02:32 +0000 |
commit | 02c3aede1bc6f26f9d54fbdeeb0c939c00799614 (patch) | |
tree | 0f9b192124e030b2ffac2cbd6a5d46ef79521a4e /docs | |
parent | 27c322e9835b8fec7e5f65a012f56e1c64fc9879 (diff) | |
download | freetype2-02c3aede1bc6f26f9d54fbdeeb0c939c00799614.tar.gz |
* 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
Diffstat (limited to 'docs')
-rw-r--r-- | docs/DEBUG.TXT | 164 |
1 files changed, 164 insertions, 0 deletions
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 + <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
\ No newline at end of file |