modules/freetype2/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'.
  96
  97     Each  such component  is assigned  a `debug  level', ranging  from 0
  98     to  7,  through  the  use  of  the  FT2_DEBUG  environment  variable
  99     (described below) when a program linked with FreeType starts.
 100
 101     When FT_TRACE  is called, its  level is compared  to the one  of the
 102     corresponding component.   Messages with trace  levels *higher* than
 103     the corresponding component level are filtered and never printed.
 104
 105     This  means that  trace messages  with level  0 are  always printed,
 106     those with level 2 are only  printed when the component level is *at
 107     least* 2.
 108
 109     The  second  parameter  to  FT_TRACE must  contain  parentheses  and
 110     correspond to a printf-like call, as in
 111
 112       FT_TRACE( 2, ( "your %s is not %s\n", "foo", "bar" ) )
 113
 114     The shortcut macros  FT_TRACE0, FT_TRACE1, FT_TRACE2, ..., FT_TRACE7
 115     can be  used with  constant level indices,  and are much  cleaner to
 116     use, as in
 117
 118      FT_TRACE2(( "your %s is not %s\n", "foo", "bar" ));
 119
 120
 121 III. Environment variables
 122 --------------------------
 123
 124 The  following  environment   variables  control  debugging  output  and
 125 behaviour of FreeType at runtime.
 126
 127
 128   FT2_DEBUG
 129
 130     This   variable  is   only  used   when  FreeType   is   built  with
 131     FT_DEBUG_LEVEL_TRACE defined.  It contains a list of component level
 132     definitions, following this format:
 133
 134        component1:level1 component2:level2 component3:level3 ...
 135
 136     where `componentX' is the name of a tracing component, as defined in
 137     `fttrace.h',  but  without the  `trace_'  prefix.   `levelX' is  the
 138     corresponding level to use at runtime.
 139
 140     `any'  is a  special  component  name that  will  be interpreted  as
 141     `any/all components'.  For example, the following definitions
 142
 143        set FT2_DEBUG=any:2 memory:5 io:4        (on Windows)
 144        export FT2_DEBUG="any:2 memory:5 io:4"   (on Linux with bash)
 145
 146     both stipulate that  all components should have level  2, except for
 147     the memory and io components which will be set to trace levels 5 and
 148     4, respectively.
 149
 150
 151   FT2_DEBUG_MEMORY
 152
 153     This  environment variable, when  defined, tells  FreeType to  use a
 154     debugging memory  manager that will  track leaking memory  blocks as
 155     well as other  common errors like double frees.   It is also capable
 156     of  reporting  _where_  the  leaking blocks  were  allocated,  which
 157     considerably saves time when debugging new additions to the library.
 158
 159     This  code  is  only  compiled  when  FreeType  is  built  with  the
 160     FT_DEBUG_MEMORY macro  #defined in  `ftoption.h' though, it  will be
 161     ignored in other builds.
 162
 163
 164   FT2_ALLOC_TOTAL_MAX
 165
 166     This  variable is ignored  if FT2_DEBUG_MEMORY  is not  defined.  It
 167     allows you to specify a maximum heap size for all memory allocations
 168     performed by FreeType.   This is very useful to  test the robustness
 169     of  the  font  engine and  programs  that  use  it in  tight  memory
 170     conditions.
 171
 172     If it is  undefined, or if its value is  not strictly positive, then
 173     no allocation bounds are checked at runtime.
 174
 175
 176   FT2_ALLOC_COUNT_MAX
 177
 178     This  variable is ignored  if FT2_DEBUG_MEMORY  is not  defined.  It
 179     allows  you  to  specify  a  maximum number  of  memory  allocations
 180     performed    by     FreeType    before    returning     the    error
 181     FT_Err_Out_Of_Memory.  This is useful  for debugging and testing the
 182     engine's robustness.
 183
 184     If it is  undefined, or if its value is  not strictly positive, then
 185     no allocation bounds are checked at runtime.
 186
 187 ------------------------------------------------------------------------
 188
 189 Copyright 2002, 2003, 2004, 2005 by
 190 David Turner, Robert Wilhelm, and Werner Lemberg.
 191
 192 This  file is  part  of the  FreeType  project, and  may  only be  used,
 193 modified,  and  distributed under  the  terms  of  the FreeType  project
 194 license, LICENSE.TXT.  By continuing  to use, modify, or distribute this
 195 file  you indicate that  you have  read the  license and  understand and
 196 accept it fully.
 197
 198
 199 --- end of DEBUG ---