1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/modules/freetype2/docs/DEBUG Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,204 @@
1.4 +Debugging within the FreeType sources
1.5 +=====================================
1.6 +
1.7 +I. Configuration macros
1.8 +-----------------------
1.9 +
1.10 +There are several ways to enable debugging features in a FreeType 2
1.11 +builds. This is controlled through the definition of special macros
1.12 +located in the file `ftoptions.h'. The macros are:
1.13 +
1.14 +
1.15 + FT_DEBUG_LEVEL_ERROR
1.16 +
1.17 + #define this macro if you want to compile the FT_ERROR macro calls
1.18 + to print error messages during program execution. This will not
1.19 + stop the program. Very useful to spot invalid fonts during
1.20 + development and to code workarounds for them.
1.21 +
1.22 + FT_DEBUG_LEVEL_TRACE
1.23 +
1.24 + #define this macro if you want to compile both macros FT_ERROR and
1.25 + FT_TRACE. This also includes the variants FT_TRACE0, FT_TRACE1,
1.26 + FT_TRACE2, ..., FT_TRACE7.
1.27 +
1.28 + The trace macros are used to send debugging messages when an
1.29 + appropriate `debug level' is configured at runtime through the
1.30 + FT2_DEBUG environment variable (more on this later).
1.31 +
1.32 + FT_DEBUG_MEMORY
1.33 +
1.34 + If this macro is #defined, the FreeType engine is linked with a
1.35 + small but effective debugging memory manager that tracks all
1.36 + allocations and frees that are performed within the font engine.
1.37 +
1.38 + When the FT2_DEBUG_MEMORY environment variable is defined at
1.39 + runtime, a call to FT_Done_FreeType will dump memory statistics,
1.40 + including the list of leaked memory blocks with the source
1.41 + locations where these were allocated. It is always a very good
1.42 + idea to define this in development builds. This works with _any_
1.43 + program linked to FreeType, but requires a big deal of memory (the
1.44 + debugging memory manager never frees the blocks to the heap in
1.45 + order to detect double frees).
1.46 +
1.47 + When FT2_DEBUG_MEMORY isn't defined at runtime, the debugging
1.48 + memory manager is ignored, and performance is unaffected.
1.49 +
1.50 +
1.51 +II. Debugging macros
1.52 +--------------------
1.53 +
1.54 +Several macros can be used within the FreeType sources to help
1.55 +debugging its code:
1.56 +
1.57 +
1.58 + 1. FT_ERROR(( ... ))
1.59 +
1.60 + This macro is used to send debug messages that indicate relatively
1.61 + serious errors (like broken font files), but will not stop the
1.62 + execution of the running program. Its code is compiled only when
1.63 + either FT_DEBUG_LEVEL_ERROR or FT_DEBUG_LEVEL_TRACE are defined in
1.64 + `ftoption.h'.
1.65 +
1.66 + Note that you have to use a printf-like signature, but with double
1.67 + parentheses, like in
1.68 +
1.69 + FT_ERROR(( "your %s is not %s\n", "foo", "bar" ));
1.70 +
1.71 +
1.72 + 2. FT_ASSERT( condition )
1.73 +
1.74 + This macro is used to check strong assertions at runtime. If its
1.75 + condition isn't TRUE, the program will abort with a panic message.
1.76 + Its code is compiled when either FT_DEBUG_LEVEL_ERROR or
1.77 + FT_DEBUG_LEVEL_TRACE are defined. You don't need double
1.78 + parentheses here. For example
1.79 +
1.80 + FT_ASSERT( ptr != NULL );
1.81 +
1.82 +
1.83 + 3. FT_TRACE( level, (message...) )
1.84 +
1.85 + The FT_TRACE macro is used to send general-purpose debugging
1.86 + messages during program execution. This macro uses an *implicit*
1.87 + macro named FT_COMPONENT used to name the current FreeType
1.88 + component being run.
1.89 +
1.90 + The developer should always define FT_COMPONENT as appropriate,
1.91 + for example as in
1.92 +
1.93 + #undef FT_COMPONENT
1.94 + #define FT_COMPONENT trace_io
1.95 +
1.96 + The value of the FT_COMPONENT macro is an enumeration named
1.97 + `trace_XXXX' where `XXXX' is one of the component names defined in
1.98 + the internal file `internal/fttrace.h'. If you modify FreeType
1.99 + source and insert new `trace_XXXX' macro, you must register it in
1.100 + `fttrace.h'. If you insert or remove many trace macros, you can
1.101 + check the undefined or the unused trace macro by
1.102 + `src/tools/chktrcmp.py'.
1.103 +
1.104 + Each such component is assigned a `debug level', ranging from 0 to
1.105 + 7, through the use of the FT2_DEBUG environment variable
1.106 + (described below) when a program linked with FreeType starts.
1.107 +
1.108 + When FT_TRACE is called, its level is compared to the one of the
1.109 + corresponding component. Messages with trace levels *higher* than
1.110 + the corresponding component level are filtered and never printed.
1.111 +
1.112 + This means that trace messages with level 0 are always printed,
1.113 + those with level 2 are only printed when the component level is
1.114 + *at least* 2.
1.115 +
1.116 + The second parameter to FT_TRACE must contain parentheses and
1.117 + correspond to a printf-like call, as in
1.118 +
1.119 + FT_TRACE( 2, ( "your %s is not %s\n", "foo", "bar" ) )
1.120 +
1.121 + The shortcut macros FT_TRACE0, FT_TRACE1, FT_TRACE2, ...,
1.122 + FT_TRACE7 can be used with constant level indices, and are much
1.123 + cleaner to use, as in
1.124 +
1.125 + FT_TRACE2(( "your %s is not %s\n", "foo", "bar" ));
1.126 +
1.127 +
1.128 +III. Environment variables
1.129 +--------------------------
1.130 +
1.131 +The following environment variables control debugging output and
1.132 +behaviour of FreeType at runtime.
1.133 +
1.134 +
1.135 + FT2_DEBUG
1.136 +
1.137 + This variable is only used when FreeType is built with
1.138 + FT_DEBUG_LEVEL_TRACE defined. It contains a list of component
1.139 + level definitions, following this format:
1.140 +
1.141 + component1:level1 component2:level2 component3:level3 ...
1.142 +
1.143 + where `componentX' is the name of a tracing component, as defined
1.144 + in `fttrace.h', but without the `trace_' prefix. `levelX' is the
1.145 + corresponding level to use at runtime.
1.146 +
1.147 + `any' is a special component name that will be interpreted as
1.148 + `any/all components'. For example, the following definitions
1.149 +
1.150 + set FT2_DEBUG=any:2 memory:5 io:4 (on Windows)
1.151 + export FT2_DEBUG="any:2 memory:5 io:4" (on Linux with bash)
1.152 +
1.153 + both stipulate that all components should have level 2, except for
1.154 + the memory and io components which will be set to trace levels 5
1.155 + and 4, respectively.
1.156 +
1.157 +
1.158 + FT2_DEBUG_MEMORY
1.159 +
1.160 + This environment variable, when defined, tells FreeType to use a
1.161 + debugging memory manager that will track leaking memory blocks as
1.162 + well as other common errors like double frees. It is also capable
1.163 + of reporting _where_ the leaking blocks were allocated, which
1.164 + considerably saves time when debugging new additions to the
1.165 + library.
1.166 +
1.167 + This code is only compiled when FreeType is built with the
1.168 + FT_DEBUG_MEMORY macro #defined in `ftoption.h' though, it will be
1.169 + ignored in other builds.
1.170 +
1.171 +
1.172 + FT2_ALLOC_TOTAL_MAX
1.173 +
1.174 + This variable is ignored if FT2_DEBUG_MEMORY is not defined. It
1.175 + allows you to specify a maximum heap size for all memory
1.176 + allocations performed by FreeType. This is very useful to test
1.177 + the robustness of the font engine and programs that use it in
1.178 + tight memory conditions.
1.179 +
1.180 + If it is undefined, or if its value is not strictly positive, then
1.181 + no allocation bounds are checked at runtime.
1.182 +
1.183 +
1.184 + FT2_ALLOC_COUNT_MAX
1.185 +
1.186 + This variable is ignored if FT2_DEBUG_MEMORY is not defined. It
1.187 + allows you to specify a maximum number of memory allocations
1.188 + performed by FreeType before returning the error
1.189 + FT_Err_Out_Of_Memory. This is useful for debugging and testing
1.190 + the engine's robustness.
1.191 +
1.192 + If it is undefined, or if its value is not strictly positive, then
1.193 + no allocation bounds are checked at runtime.
1.194 +
1.195 +------------------------------------------------------------------------
1.196 +
1.197 +Copyright 2002-2005, 2009, 2013 by
1.198 +David Turner, Robert Wilhelm, and Werner Lemberg.
1.199 +
1.200 +This file is part of the FreeType project, and may only be used,
1.201 +modified, and distributed under the terms of the FreeType project
1.202 +license, LICENSE.TXT. By continuing to use, modify, or distribute this
1.203 +file you indicate that you have read the license and understand and
1.204 +accept it fully.
1.205 +
1.206 +
1.207 +--- end of DEBUG ---
