michael@0: Debugging within the FreeType sources michael@0: ===================================== michael@0: michael@0: I. Configuration macros michael@0: ----------------------- michael@0: michael@0: There are several ways to enable debugging features in a FreeType 2 michael@0: builds. This is controlled through the definition of special macros michael@0: located in the file `ftoptions.h'. The macros are: michael@0: michael@0: michael@0: FT_DEBUG_LEVEL_ERROR michael@0: michael@0: #define this macro if you want to compile the FT_ERROR macro calls michael@0: to print error messages during program execution. This will not michael@0: stop the program. Very useful to spot invalid fonts during michael@0: development and to code workarounds for them. michael@0: michael@0: FT_DEBUG_LEVEL_TRACE michael@0: michael@0: #define this macro if you want to compile both macros FT_ERROR and michael@0: FT_TRACE. This also includes the variants FT_TRACE0, FT_TRACE1, michael@0: FT_TRACE2, ..., FT_TRACE7. michael@0: michael@0: The trace macros are used to send debugging messages when an michael@0: appropriate `debug level' is configured at runtime through the michael@0: FT2_DEBUG environment variable (more on this later). michael@0: michael@0: FT_DEBUG_MEMORY michael@0: michael@0: If this macro is #defined, the FreeType engine is linked with a michael@0: small but effective debugging memory manager that tracks all michael@0: allocations and frees that are performed within the font engine. michael@0: michael@0: When the FT2_DEBUG_MEMORY environment variable is defined at michael@0: runtime, a call to FT_Done_FreeType will dump memory statistics, michael@0: including the list of leaked memory blocks with the source michael@0: locations where these were allocated. It is always a very good michael@0: idea to define this in development builds. This works with _any_ michael@0: program linked to FreeType, but requires a big deal of memory (the michael@0: debugging memory manager never frees the blocks to the heap in michael@0: order to detect double frees). michael@0: michael@0: When FT2_DEBUG_MEMORY isn't defined at runtime, the debugging michael@0: memory manager is ignored, and performance is unaffected. michael@0: michael@0: michael@0: II. Debugging macros michael@0: -------------------- michael@0: michael@0: Several macros can be used within the FreeType sources to help michael@0: debugging its code: michael@0: michael@0: michael@0: 1. FT_ERROR(( ... )) michael@0: michael@0: This macro is used to send debug messages that indicate relatively michael@0: serious errors (like broken font files), but will not stop the michael@0: execution of the running program. Its code is compiled only when michael@0: either FT_DEBUG_LEVEL_ERROR or FT_DEBUG_LEVEL_TRACE are defined in michael@0: `ftoption.h'. michael@0: michael@0: Note that you have to use a printf-like signature, but with double michael@0: parentheses, like in michael@0: michael@0: FT_ERROR(( "your %s is not %s\n", "foo", "bar" )); michael@0: michael@0: michael@0: 2. FT_ASSERT( condition ) michael@0: michael@0: This macro is used to check strong assertions at runtime. If its michael@0: condition isn't TRUE, the program will abort with a panic message. michael@0: Its code is compiled when either FT_DEBUG_LEVEL_ERROR or michael@0: FT_DEBUG_LEVEL_TRACE are defined. You don't need double michael@0: parentheses here. For example michael@0: michael@0: FT_ASSERT( ptr != NULL ); michael@0: michael@0: michael@0: 3. FT_TRACE( level, (message...) ) michael@0: michael@0: The FT_TRACE macro is used to send general-purpose debugging michael@0: messages during program execution. This macro uses an *implicit* michael@0: macro named FT_COMPONENT used to name the current FreeType michael@0: component being run. michael@0: michael@0: The developer should always define FT_COMPONENT as appropriate, michael@0: for example as in michael@0: michael@0: #undef FT_COMPONENT michael@0: #define FT_COMPONENT trace_io michael@0: michael@0: The value of the FT_COMPONENT macro is an enumeration named michael@0: `trace_XXXX' where `XXXX' is one of the component names defined in michael@0: the internal file `internal/fttrace.h'. If you modify FreeType michael@0: source and insert new `trace_XXXX' macro, you must register it in michael@0: `fttrace.h'. If you insert or remove many trace macros, you can michael@0: check the undefined or the unused trace macro by michael@0: `src/tools/chktrcmp.py'. michael@0: michael@0: Each such component is assigned a `debug level', ranging from 0 to michael@0: 7, through the use of the FT2_DEBUG environment variable michael@0: (described below) when a program linked with FreeType starts. michael@0: michael@0: When FT_TRACE is called, its level is compared to the one of the michael@0: corresponding component. Messages with trace levels *higher* than michael@0: the corresponding component level are filtered and never printed. michael@0: michael@0: This means that trace messages with level 0 are always printed, michael@0: those with level 2 are only printed when the component level is michael@0: *at least* 2. michael@0: michael@0: The second parameter to FT_TRACE must contain parentheses and michael@0: correspond to a printf-like call, as in michael@0: michael@0: FT_TRACE( 2, ( "your %s is not %s\n", "foo", "bar" ) ) michael@0: michael@0: The shortcut macros FT_TRACE0, FT_TRACE1, FT_TRACE2, ..., michael@0: FT_TRACE7 can be used with constant level indices, and are much michael@0: cleaner to use, as in michael@0: michael@0: FT_TRACE2(( "your %s is not %s\n", "foo", "bar" )); michael@0: michael@0: michael@0: III. Environment variables michael@0: -------------------------- michael@0: michael@0: The following environment variables control debugging output and michael@0: behaviour of FreeType at runtime. michael@0: michael@0: michael@0: FT2_DEBUG michael@0: michael@0: This variable is only used when FreeType is built with michael@0: FT_DEBUG_LEVEL_TRACE defined. It contains a list of component michael@0: level definitions, following this format: michael@0: michael@0: component1:level1 component2:level2 component3:level3 ... michael@0: michael@0: where `componentX' is the name of a tracing component, as defined michael@0: in `fttrace.h', but without the `trace_' prefix. `levelX' is the michael@0: corresponding level to use at runtime. michael@0: michael@0: `any' is a special component name that will be interpreted as michael@0: `any/all components'. For example, the following definitions michael@0: michael@0: set FT2_DEBUG=any:2 memory:5 io:4 (on Windows) michael@0: export FT2_DEBUG="any:2 memory:5 io:4" (on Linux with bash) michael@0: michael@0: both stipulate that all components should have level 2, except for michael@0: the memory and io components which will be set to trace levels 5 michael@0: and 4, respectively. michael@0: michael@0: michael@0: FT2_DEBUG_MEMORY michael@0: michael@0: This environment variable, when defined, tells FreeType to use a michael@0: debugging memory manager that will track leaking memory blocks as michael@0: well as other common errors like double frees. It is also capable michael@0: of reporting _where_ the leaking blocks were allocated, which michael@0: considerably saves time when debugging new additions to the michael@0: library. michael@0: michael@0: This code is only compiled when FreeType is built with the michael@0: FT_DEBUG_MEMORY macro #defined in `ftoption.h' though, it will be michael@0: ignored in other builds. michael@0: michael@0: michael@0: FT2_ALLOC_TOTAL_MAX michael@0: michael@0: This variable is ignored if FT2_DEBUG_MEMORY is not defined. It michael@0: allows you to specify a maximum heap size for all memory michael@0: allocations performed by FreeType. This is very useful to test michael@0: the robustness of the font engine and programs that use it in michael@0: tight memory conditions. michael@0: michael@0: If it is undefined, or if its value is not strictly positive, then michael@0: no allocation bounds are checked at runtime. michael@0: michael@0: michael@0: FT2_ALLOC_COUNT_MAX michael@0: michael@0: This variable is ignored if FT2_DEBUG_MEMORY is not defined. It michael@0: allows you to specify a maximum number of memory allocations michael@0: performed by FreeType before returning the error michael@0: FT_Err_Out_Of_Memory. This is useful for debugging and testing michael@0: the engine's robustness. michael@0: michael@0: If it is undefined, or if its value is not strictly positive, then michael@0: no allocation bounds are checked at runtime. michael@0: michael@0: ------------------------------------------------------------------------ michael@0: michael@0: Copyright 2002-2005, 2009, 2013 by michael@0: David Turner, Robert Wilhelm, and Werner Lemberg. michael@0: michael@0: This file is part of the FreeType project, and may only be used, michael@0: modified, and distributed under the terms of the FreeType project michael@0: license, LICENSE.TXT. By continuing to use, modify, or distribute this michael@0: file you indicate that you have read the license and understand and michael@0: accept it fully. michael@0: michael@0: michael@0: --- end of DEBUG ---