docs/DEBUG

   1 Debugging within the FreeType sources
   2 =====================================
   3
   4 I. Configuration macros
   5 -----------------------
   6
   7 There  are several ways  to enable  debugging features  in a  FreeType 2
   8 builds.   This is controlled  through the  definition of  special macros
   9 located in the file `ftoptions.h'.  The macros are:
  10
  11
  12   FT_DEBUG_LEVEL_ERROR
  13
  14     #define this macro  if you want to compile  the FT_ERROR macro calls
  15     to  print error messages  during program  execution.  This  will not
  16     stop  the  program.   Very  useful  to  spot  invalid  fonts  during
  17     development and to code workarounds for them.
  18
  19   FT_DEBUG_LEVEL_TRACE
  20
  21     #define this macro  if you want to compile  both macros FT_ERROR and
  22     FT_TRACE.   This also  includes the  variants  FT_TRACE0, FT_TRACE1,
  23     FT_TRACE2, ..., FT_TRACE7.
  24
  25     The  trace  macros are  used  to  send  debugging messages  when  an
  26     appropriate  `debug  level' is  configured  at  runtime through  the
  27     FT2_DEBUG environment variable (more on this later).
  28
  29   FT_DEBUG_MEMORY
  30
  31     If  this macro is  #defined, the  FreeType engine  is linked  with a
  32     small  but  effective  debugging  memory  manager  that  tracks  all
  33     allocations and frees that are performed within the font engine.
  34
  35     When  the  FT2_DEBUG_MEMORY   environment  variable  is  defined  at
  36     runtime,  a call  to FT_Done_FreeType  will dump  memory statistics,
  37     including the list of leaked memory blocks with the source locations
  38     where these were allocated.  It is always a very good idea to define
  39     this in development builds.  This works with _any_ program linked to
  40     FreeType, but  requires a big  deal of memory (the  debugging memory
  41     manager never frees the blocks to the heap in order to detect double
  42     frees).
  43
  44     When FT2_DEBUG_MEMORY isn't defined at runtime, the debugging memory
  45     manager is ignored, and performance is unaffected.
  46
  47
  48 II. Debugging macros
  49 --------------------
  50
  51 Several macros can be used within the FreeType sources to help debugging
  52 its code:
  53
  54
  55   1. FT_ERROR(( ... ))
  56
  57     This macro is  used to send debug messages  that indicate relatively
  58     serious  errors (like  broken font  files),  but will  not stop  the
  59     execution of  the running program.   Its code is compiled  only when
  60     either FT_DEBUG_LEVEL_ERROR  or FT_DEBUG_LEVEL_TRACE are  defined in
  61     `ftoption.h'.
  62
  63     Note that you  have to use a printf-like  signature, but with double
  64     parentheses, like in
  65
  66       FT_ERROR(( "your %s is not %s\n", "foo", "bar" ));
  67
  68
  69   2. FT_ASSERT( condition )
  70
  71     This macro  is used to check  strong assertions at  runtime.  If its
  72     condition isn't TRUE,  the program will abort with  a panic message.
  73     Its   code   is  compiled   when   either  FT_DEBUG_LEVEL_ERROR   or
  74     FT_DEBUG_LEVEL_TRACE are defined.  You don't need double parentheses
  75     here.  For example
  76
  77       FT_ASSERT( ptr != NULL );
  78
  79
  80   3. FT_TRACE( level, (message...) )
  81
  82     The  FT_TRACE  macro  is  used  to  send  general-purpose  debugging
  83     messages during  program execution.   This macro uses  an *implicit*
  84     macro named FT_COMPONENT used to name the current FreeType component
  85     being run.
  86
  87     The developer should always  define FT_COMPONENT as appropriate, for
  88     example as in
  89
  90       #undef  FT_COMPONENT
  91       #define FT_COMPONENT  trace_io
  92
  93     The  value  of  the  FT_COMPONENT  macro  is  an  enumeration  named
  94     trace_XXXX where XXXX  is one of the component  names defined in the
  95     internal file `freetype/internal/fttrace.h'.  If you modify FreeType
  96     source  and insert  new trace_XXXX macro,  you  must register  it in
  97     fttrace.h. If you insert or remove many trace macros,  you can check
  98     the undefined or the unused trace macro by src/tools/chktrcmp.py.
  99
 100     Each  such component  is assigned  a `debug  level', ranging  from 0
 101     to  7,  through  the  use  of  the  FT2_DEBUG  environment  variable
 102     (described below) when a program linked with FreeType starts.
 103
 104     When FT_TRACE  is called, its  level is compared  to the one  of the
 105     corresponding component.   Messages with trace  levels *higher* than
 106     the corresponding component level are filtered and never printed.
 107
 108     This  means that  trace messages  with level  0 are  always printed,
 109     those with level 2 are only  printed when the component level is *at
 110     least* 2.
 111
 112     The  second  parameter  to  FT_TRACE must  contain  parentheses  and
 113     correspond to a printf-like call, as in
 114
 115       FT_TRACE( 2, ( "your %s is not %s\n", "foo", "bar" ) )
 116
 117     The shortcut macros  FT_TRACE0, FT_TRACE1, FT_TRACE2, ..., FT_TRACE7
 118     can be  used with  constant level indices,  and are much  cleaner to
 119     use, as in
 120
 121      FT_TRACE2(( "your %s is not %s\n", "foo", "bar" ));
 122
 123
 124 III. Environment variables
 125 --------------------------
 126
 127 The  following  environment   variables  control  debugging  output  and
 128 behaviour of FreeType at runtime.
 129
 130
 131   FT2_DEBUG
 132
 133     This   variable  is   only  used   when  FreeType   is   built  with
 134     FT_DEBUG_LEVEL_TRACE defined.  It contains a list of component level
 135     definitions, following this format:
 136
 137        component1:level1 component2:level2 component3:level3 ...
 138
 139     where `componentX' is the name of a tracing component, as defined in
 140     `fttrace.h',  but  without the  `trace_'  prefix.   `levelX' is  the
 141     corresponding level to use at runtime.
 142
 143     `any'  is a  special  component  name that  will  be interpreted  as
 144     `any/all components'.  For example, the following definitions
 145
 146        set FT2_DEBUG=any:2 memory:5 io:4        (on Windows)
 147        export FT2_DEBUG="any:2 memory:5 io:4"   (on Linux with bash)
 148
 149     both stipulate that  all components should have level  2, except for
 150     the memory and io components which will be set to trace levels 5 and
 151     4, respectively.
 152
 153
 154   FT2_DEBUG_MEMORY
 155
 156     This  environment variable, when  defined, tells  FreeType to  use a
 157     debugging memory  manager that will  track leaking memory  blocks as
 158     well as other  common errors like double frees.   It is also capable
 159     of  reporting  _where_  the  leaking blocks  were  allocated,  which
 160     considerably saves time when debugging new additions to the library.
 161
 162     This  code  is  only  compiled  when  FreeType  is  built  with  the
 163     FT_DEBUG_MEMORY macro  #defined in  `ftoption.h' though, it  will be
 164     ignored in other builds.
 165
 166
 167   FT2_ALLOC_TOTAL_MAX
 168
 169     This  variable is ignored  if FT2_DEBUG_MEMORY  is not  defined.  It
 170     allows you to specify a maximum heap size for all memory allocations
 171     performed by FreeType.   This is very useful to  test the robustness
 172     of  the  font  engine and  programs  that  use  it in  tight  memory
 173     conditions.
 174
 175     If it is  undefined, or if its value is  not strictly positive, then
 176     no allocation bounds are checked at runtime.
 177
 178
 179   FT2_ALLOC_COUNT_MAX
 180
 181     This  variable is ignored  if FT2_DEBUG_MEMORY  is not  defined.  It
 182     allows  you  to  specify  a  maximum number  of  memory  allocations
 183     performed    by     FreeType    before    returning     the    error
 184     FT_Err_Out_Of_Memory.  This is useful  for debugging and testing the
 185     engine's robustness.
 186
 187     If it is  undefined, or if its value is  not strictly positive, then
 188     no allocation bounds are checked at runtime.
 189
 190 ------------------------------------------------------------------------
 191
 192 Copyright 2002, 2003, 2004, 2005, 2009 by
 193 David Turner, Robert Wilhelm, and Werner Lemberg.
 194
 195 This  file is  part  of the  FreeType  project, and  may  only be  used,
 196 modified,  and  distributed under  the  terms  of  the FreeType  project
 197 license, LICENSE.TXT.  By continuing  to use, modify, or distribute this
 198 file  you indicate that  you have  read the  license and  understand and
 199 accept it fully.
 200
 201
 202 --- end of DEBUG ---