* 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
diff --git a/docs/DEBUG.TXT b/docs/DEBUG.TXT
new file mode 100644
index 0000000..86ffbcf
--- /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