docs/DEBUG.TXT

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