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 controlled  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

    If 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.


End of file