reactos/dll/3rdparty/freetype/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   1. FT_ERROR(( ... ))
  55
  56     This macro is  used to send debug messages  that indicate relatively
  57     serious  errors (like  broken font  files),  but will  not stop  the
  58     execution of  the running program.   Its code is compiled  only when
  59     either FT_DEBUG_LEVEL_ERROR  or FT_DEBUG_LEVEL_TRACE are  defined in
  60     "ftoption.h".
  61
  62     Note that you  have to use a printf-like  signature, but with double
  63     parentheses, like in:
  64
  65       FT_ERROR(( "your %s is not %s\n", "foo", "bar" ));
  66
  67
  68   2. FT_ASSERT( condition )
  69
  70     This macro  is used to check  strong assertions at  runtime.  If its
  71     condition isn't TRUE,  the program will abort with  a panic message.
  72     Its   code   is  compiled   when   either  FT_DEBUG_LEVEL_ERROR   or
  73     FT_DEBUG_LEVEL_TRACE are defined.  You don't need double-parentheses
  74     here.  For example:
  75
  76       FT_ASSERT( ptr != NULL );
  77
  78
  79   3. FT_TRACE( level, (message...) )
  80
  81     The  FT_TRACE  macro  is  used  to  send  general-purpose  debugging
  82     messages during  program execution.   This macro uses  an *implicit*
  83     macro named FT_COMPONENT used to name the current FreeType component
  84     being run.
  85
  86     The developer should always  define FT_COMPONENT as appropriate, for
  87     example as in:
  88
  89       #undef  FT_COMPONENT
  90       #define FT_COMPONENT  trace_io
  91
  92     The  value  of  the  FT_COMPONENT  macro  is  an  enumeration  named
  93     trace_XXXX where XXXX  is one of the component  names defined in the
  94     internal file <freetype/internal/fttrace.h>.
  95
  96     Each  such component  is assigned  a "debug  level", ranging  from 0
  97     to 7,  through  the  use   of  the  FT2_DEBUG  environment  variable
  98     (described below) when a program linked with FreeType starts.
  99
 100     When FT_TRACE  is called, its  level is compared  to the one  of the
 101     corresponding component.   Messages with trace  levels *higher* than
 102     the corresponding component level are filtered and never printed.
 103
 104     This  means that  trace messages  with level  0 are  always printed,
 105     those with level 2 are only  printed when the component level is *at
 106     least* 2.
 107
 108     The  second  parameter  to  FT_TRACE must  contain  parentheses  and
 109     correspond to a printf-like call, as in:
 110
 111       FT_TRACE( 2, ( "your %s is not %s\n", "foo", "bar" ) )
 112
 113     The shortcut macros  FT_TRACE0, FT_TRACE1, FT_TRACE2_, ... FT_TRACE7
 114     can be  used with  constant level indices,  and are much  cleaner to
 115     use, as in
 116
 117      FT_TRACE2(( "your %s is not %s\n", "foo", "bar" ));
 118
 119
 120 III. Environment variables
 121 --------------------------
 122
 123 The  following  environment   variables  control  debugging  output  and
 124 behaviour of FreeType at runtime:
 125
 126   FT2_DEBUG
 127
 128     This   variable  is   only  used   when  FreeType   is   built  with
 129     FT_DEBUG_LEVEL_TRACE defined.  It contains a list of component level
 130     definitions, following this format:
 131
 132        component1:level1 component2:level2 component3:level3 ...
 133
 134     where "componentX" is the name of a tracing component, as defined in
 135     "fttrace.h",  but  without the  "trace_"  prefix.   "levelX" is  the
 136     corresponding level to use at runtime.
 137
 138     "any"  is a  special  component  name that  will  be interpreted  as
 139     "any/all components".  For example, the following definitions
 140
 141        set FT2_DEBUG=any:2 memory:5 io:4        (on Windows)
 142        export FT2_DEBUG="any:2 memory:5 io:4"   (on Linux with bash)
 143
 144     both stipulate that  all components should have level  2, except for
 145     the memory  and io components  which will be  set to trace  levels 5
 146     and 4, respectively.
 147
 148   FT2_DEBUG_MEMORY
 149
 150     This  environment variable, when  defined, tells  FreeType to  use a
 151     debugging memory  manager that will  track leaking memory  blocks as
 152     well as other  common errors like double frees.   It is also capable
 153     of  reporting  _where_  the  leaking blocks  were  allocated,  which
 154     considerably saves time when debugging new additions to the library.
 155
 156     This  code  is  only  compiled  when  FreeType  is  built  with  the
 157     FT_DEBUG_MEMORY macro  #defined in  "ftoption.h" though, it  will be
 158     ignored in other builds.
 159
 160   FT2_ALLOC_TOTAL_MAX
 161
 162     This  variable is ignored  if FT2_DEBUG_MEMORY  is not  defined.  It
 163     allows you to specify a maximum heap size for all memory allocations
 164     performed by FreeType.   This is very useful to  test the robustness
 165     of  the  font  engine and  programs  that  use  it in  tight  memory
 166     conditions.
 167
 168     If it is  undefined, or if its value is  not strictly positive, then
 169     no allocation bounds are checked at runtime.
 170
 171   FT2_ALLOC_COUNT_MAX
 172
 173     This  variable is ignored  if FT2_DEBUG_MEMORY  is not  defined.  It
 174     allows  you  to  specify  a  maximum number  of  memory  allocations
 175     performed    by     FreeType    before    returning     the    error
 176     FT_Err_Out_Of_Memory.  This is useful  for debugging and testing the
 177     engine's robustness.
 178
 179     If it is  undefined, or if its value is  not strictly positive, then
 180     no allocation bounsd are checked at runtime.
 181
 182 ------------------------------------------------------------------------
 183
 184 Copyright 2002, 2003, 2004 by
 185 David Turner, Robert Wilhelm, and Werner Lemberg.
 186
 187 This  file  is  part  of the  FreeType  project, and may  only be  used,
 188 modified,  and  distributed  under  the  terms of  the FreeType  project
 189 license, LICENSE.TXT.   By continuing to use, modify, or distribute this
 190 file you  indicate that  you have  read the  license and understand  and
 191 accept it fully.
 192
 193
 194 --- end of DEBUG ---