diff options
Diffstat (limited to 'docs/DEBUG')
| -rw-r--r-- | docs/DEBUG | 59 |
1 files changed, 32 insertions, 27 deletions
diff --git a/docs/DEBUG b/docs/DEBUG index 4e1323391..4b0501aff 100644 --- a/docs/DEBUG +++ b/docs/DEBUG @@ -6,7 +6,7 @@ I. Configuration macros 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: +located in the file `ftoptions.h'. The macros are: FT_DEBUG_LEVEL_ERROR @@ -23,7 +23,7 @@ located in the file "ftoptions.h". The macros are: FT_TRACE2, ..., FT_TRACE7. The trace macros are used to send debugging messages when an - appropriate "debug level" is configured at runtime through the + appropriate `debug level' is configured at runtime through the FT2_DEBUG environment variable (more on this later). FT_DEBUG_MEMORY @@ -51,16 +51,17 @@ 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". + `ftoption.h'. Note that you have to use a printf-like signature, but with double - parentheses, like in: + parentheses, like in FT_ERROR(( "your %s is not %s\n", "foo", "bar" )); @@ -70,31 +71,31 @@ its code: 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_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: + 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>. + internal file `freetype/internal/fttrace.h'. - Each such component is assigned a "debug level", ranging from 0 - to 7, through the use of the FT2_DEBUG environment variable + Each such component is assigned a `debug level', ranging from 0 + to 7, through the use of the FT2_DEBUG environment variable (described below) when a program linked with FreeType starts. When FT_TRACE is called, its level is compared to the one of the @@ -106,11 +107,11 @@ its code: least* 2. The second parameter to FT_TRACE must contain parentheses and - correspond to a printf-like call, as in: + correspond to a printf-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_TRACE7 + The shortcut macros FT_TRACE0, FT_TRACE1, FT_TRACE2, ..., FT_TRACE7 can be used with constant level indices, and are much cleaner to use, as in @@ -121,7 +122,8 @@ III. Environment variables -------------------------- The following environment variables control debugging output and -behaviour of FreeType at runtime: +behaviour of FreeType at runtime. + FT2_DEBUG @@ -131,19 +133,20 @@ behaviour of FreeType at runtime: 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. "levelX" is the + where `componentX' is the name of a tracing component, as defined in + `fttrace.h', but without the `trace_' prefix. `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 with bash) 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. + the memory and io components which will be set to trace levels 5 and + 4, respectively. + FT2_DEBUG_MEMORY @@ -154,9 +157,10 @@ behaviour of FreeType at runtime: 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 + FT_DEBUG_MEMORY macro #defined in `ftoption.h' though, it will be ignored in other builds. + FT2_ALLOC_TOTAL_MAX This variable is ignored if FT2_DEBUG_MEMORY is not defined. It @@ -168,6 +172,7 @@ behaviour of FreeType at runtime: If it is undefined, or if its value is not strictly positive, then no allocation bounds are checked at runtime. + FT2_ALLOC_COUNT_MAX This variable is ignored if FT2_DEBUG_MEMORY is not defined. It @@ -177,17 +182,17 @@ behaviour of FreeType at runtime: engine's robustness. If it is undefined, or if its value is not strictly positive, then - no allocation bounsd are checked at runtime. + no allocation bounds are checked at runtime. ------------------------------------------------------------------------ -Copyright 2002, 2003, 2004 by +Copyright 2002, 2003, 2004, 2005 by David Turner, Robert Wilhelm, and Werner Lemberg. -This file is part of the FreeType project, and may only be used, -modified, and distributed under the terms of the FreeType project -license, LICENSE.TXT. By continuing to use, modify, or distribute this -file you indicate that you have read the license and understand and +This file is part of the FreeType project, and may only be used, +modified, and distributed under the terms of the FreeType project +license, LICENSE.TXT. By continuing to use, modify, or distribute this +file you indicate that you have read the license and understand and accept it fully. |