docs/DEBUG

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
    to print error  messages during program execution.   This will not
    stop  the  program.  Very  useful  to  spot invalid  fonts  during
    development and to code workarounds for them.

  FT_DEBUG_LEVEL_TRACE

    #define this macro if you want to compile both macros FT_ERROR and
    FT_TRACE.  This  also includes the variants  FT_TRACE0, FT_TRACE1,
    FT_TRACE2, ..., FT_TRACE7.

    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 engine 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 is 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 unaffected.


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 have to use 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 `internal/fttrace.h'.   If you  modify FreeType
    source and insert new `trace_XXXX'  macro, you must register it in
    `fttrace.h'. If  you insert or  remove many trace macros,  you can
    check   the    undefined   or   the   unused    trace   macro   by
    `src/tools/chktrcmp.py'.

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


  FT2_DEBUG_MEMORY

    This environment variable,  when defined, tells FreeType  to use a
    debugging memory manager that will  track leaking memory blocks as
    well as other common errors like double frees.  It is also capable
    of  reporting _where_  the  leaking 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.


  FT2_ALLOC_TOTAL_MAX

    This variable is  ignored if FT2_DEBUG_MEMORY is  not defined.  It
    allows  you  to  specify  a  maximum  heap  size  for  all  memory
    allocations performed  by FreeType.  This  is very useful  to test
    the robustness  of the  font engine  and programs  that use  it in
    tight memory conditions.

    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
    allows  you to  specify  a maximum  number  of memory  allocations
    performed    by    FreeType    before    returning    the    error
    FT_Err_Out_Of_Memory.  This  is useful  for debugging  and testing
    the engine's robustness.

    If it is undefined, or if its value is not strictly positive, then
    no allocation bounds are checked at runtime.

------------------------------------------------------------------------

Copyright 2002-2015 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
accept it fully.


--- end of DEBUG ---