superbuild/modules/freetype/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 `ftoption.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 does
    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'  dumps memory  statistics,
    including the list of leaked memory blocks and optionally 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.

  FT_DEBUG_LOGGING

    #define this macro for enhanced logging support; it automatically
    sets `FT_DEBUG_LEVEL_TRACE' and `FT_DEBUG_LEVEL_ERROR'.

    If  defined,  `FT_TRACE'  and  `FT_ERROR'  can  send  tracing  and
    debugging messages to a file.  The location of the log file has to
    be set  with the  `FT_LOGGING_FILE' environment variable  (more on
    this later).

    The main enhancements are the  possibility of logging the time and
    the name  of the `FT_COMPONENT'  macro together with  the affected
    `FT_TRACE' or `FT_ERROR' calls.  See below how to activate this in
    the `FT2_DEBUG' environment variable.


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)  without stopping  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 aborts  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.  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',  which names  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  io

    The  value of  the `FT_COMPONENT'  macro is  one of  the component
    names defined  in the internal file  `internal/fttrace.h'.  If you
    modify the  FreeType source code  and insert a  new `FT_COMPONENT'
    macro,  you must  register it  in `fttrace.h'.   If you  insert or
    remove many  trace macros,  you can test  for undefined  or unused
    trace macros with the script `src/tools/chktrcmp.py'.

    Each  such component  is assigned  a `debug  level', ranging  from
    value  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  out 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, etc.

    The second  parameter to  `FT_TRACE' must contain  parentheses and
    corresponds 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'.  `levelX' is  the corresponding level  to  use  at
    runtime.

    `any' is a special component  name that is 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  are set to the trace levels 5
    and 4, respectively.

    If `FT_DEBUG_LOGGING' is defined, two more options are available.

    * -v: Print also  the name of FreeType's component  from which the
          current log is produced, together with the tracing level.

    * -t: Print also the time.

    Here are some examples how the output might look like.

      FT2_DEBUG="any:7 memory:5 -vt"

        => [20:32:02:44969 ttload:2]    table directory loaded

      FT2_DEBUG="any:7 memory:5 -t"

        => [20:32:02:44969]    table directory loaded

      FT2_DEBUG="any:7 memory:5 -v"

        => [ttload:2]    table directory loaded


  FT_LOGGING_FILE

    This  variable  is  only  used  if  FreeType  is  built  with  the
    `FT_DEBUG_LOGGING'  macro defined.   It contains  the path  to the
    file where the user wants to put  his log file.  If it is not set,
    FreeType uses stderr.

    Examples:

      On UNIX-like systems with bash:
      export FT_LOGGING_FILE="/tmp/freetype2.log"

      On Windows:
      set FT_LOGGING_FILE=C:\Users\AppData\Local\Temp\freetype2.log


  FT2_DEBUG_MEMORY

    This environment variable,  when defined, tells FreeType  to use a
    debugging memory manager that tracks 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  is
    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, 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, no
    allocation bounds are checked at runtime.


  FT2_KEEP_ALIVE

    This  variable is  ignored if  `FT2_DEBUG_MEMORY' is  not defined.
    `Keep alive' means that freed  blocks aren't released to the heap.
    This is  useful to detect  double-frees or weird  heap corruption,
    reporting the source code location  of the original allocation and
    deallocation  in case  of a  problem.   It uses  large amounts  of
    memory, however.

    If it  is undefined,  or if  its value  is not  strictly positive,
    freed blocks are released at runtime.


IV. Additional Capabilities with `FT_DEBUG_LOGGING'
---------------------------------------------------

If `FT_DEBUG_LOGGING' is  defined, four APIs are  available to provide
additional debugging support.  Use

  #include <freetype/ftlogging.h>

to access them.

  FT_Trace_Set_Level( const char*  level )

    By  default,  FreeType   uses  the  tracing  levels   set  in  the
    `FT2_DEBUG' environment  variable.  Use this function  to override
    the value with `level'.  Use value `NULL' to disable tracing.

  FT_Trace_Set_Default_Level():

    Reset the tracing levels to the default value, i.e., the value of
    the `FT2_DEBUG' environment variable or no tracing if not set.

  FT_Set_Log_Handler( ft_custom_log_handler  handler ):

    Use `handler' as a custom handler for formatting tracing and error
    messages.  The  `ft_custom_log_handler' typedef has  the following
    prototype.

      void
      (*ft_custom_log_handler)( const char*  ft_component,
                                const char*  fmt,
                                va_list      args );

   `ft_component' is the current component like `ttload', `fmt' is the
   first argument  of `FT_TRACE' or  `FT_ERROR', and `args'  holds the
   remaining arguments.

  FT_Set_Default_Log_Handler():

    Reset the log handler to the default version.


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

Copyright (C) 2002-2022 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 ---