/[freetype]/freetype2/docs/DEBUG
ViewVC logotype

Diff of /freetype2/docs/DEBUG

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.4 by wl, Sat Jun 4 23:00:25 2005 UTC revision 1.5 by wl, Tue Aug 30 00:22:46 2005 UTC
# Line 6  I. Configuration macros Line 6  I. Configuration macros
6    
7  There  are several ways  to enable  debugging features  in a  FreeType 2  There  are several ways  to enable  debugging features  in a  FreeType 2
8  builds.   This is controlled  through the  definition of  special macros  builds.   This is controlled  through the  definition of  special macros
9  located in the file "ftoptions.h".  The macros are:  located in the file `ftoptions.h'.  The macros are:
10    
11    
12    FT_DEBUG_LEVEL_ERROR    FT_DEBUG_LEVEL_ERROR
# Line 23  located in the file "ftoptions.h".  The Line 23  located in the file "ftoptions.h".  The
23      FT_TRACE2, ..., FT_TRACE7.      FT_TRACE2, ..., FT_TRACE7.
24    
25      The  trace  macros are  used  to  send  debugging messages  when  an      The  trace  macros are  used  to  send  debugging messages  when  an
26      appropriate  "debug  level" is  configured  at  runtime through  the      appropriate  `debug  level' is  configured  at  runtime through  the
27      FT2_DEBUG environment variable (more on this later).      FT2_DEBUG environment variable (more on this later).
28    
29    FT_DEBUG_MEMORY    FT_DEBUG_MEMORY
# Line 51  II. Debugging macros Line 51  II. Debugging macros
51  Several macros can be used within the FreeType sources to help debugging  Several macros can be used within the FreeType sources to help debugging
52  its code:  its code:
53    
54    
55    1. FT_ERROR(( ... ))    1. FT_ERROR(( ... ))
56    
57      This macro is  used to send debug messages  that indicate relatively      This macro is  used to send debug messages  that indicate relatively
58      serious  errors (like  broken font  files),  but will  not stop  the      serious  errors (like  broken font  files),  but will  not stop  the
59      execution of  the running program.   Its code is compiled  only when      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      either FT_DEBUG_LEVEL_ERROR  or FT_DEBUG_LEVEL_TRACE are  defined in
61      "ftoption.h".      `ftoption.h'.
62    
63      Note that you  have to use a printf-like  signature, but with double      Note that you  have to use a printf-like  signature, but with double
64      parentheses, like in:      parentheses, like in
65    
66        FT_ERROR(( "your %s is not %s\n", "foo", "bar" ));        FT_ERROR(( "your %s is not %s\n", "foo", "bar" ));
67    
# Line 70  its code: Line 71  its code:
71      This macro  is used to check  strong assertions at  runtime.  If its      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.      condition isn't TRUE,  the program will abort with  a panic message.
73      Its   code   is  compiled   when   either  FT_DEBUG_LEVEL_ERROR   or      Its   code   is  compiled   when   either  FT_DEBUG_LEVEL_ERROR   or
74      FT_DEBUG_LEVEL_TRACE are defined.  You don't need double-parentheses      FT_DEBUG_LEVEL_TRACE are defined.  You don't need double parentheses
75      here.  For example:      here.  For example
76    
77        FT_ASSERT( ptr != NULL );        FT_ASSERT( ptr != NULL );
78    
79    
80    3. FT_TRACE( level, (message...) )    3. FT_TRACE( level, (message...) )
81    
82      The  FT_TRACE  macro  is  used  to  send  general-purpose  debugging      The  FT_TRACE  macro  is  used  to  send  general-purpose  debugging
83      messages during  program execution.   This macro uses  an *implicit*      messages during  program execution.   This macro uses  an *implicit*
84      macro named FT_COMPONENT used to name the current FreeType component      macro named FT_COMPONENT used to name the current FreeType component
85      being run.      being run.
86    
87      The developer should always  define FT_COMPONENT as appropriate, for      The developer should always  define FT_COMPONENT as appropriate, for
88      example as in:      example as in
89    
90        #undef  FT_COMPONENT        #undef  FT_COMPONENT
91        #define FT_COMPONENT  trace_io        #define FT_COMPONENT  trace_io
92    
93      The  value  of  the  FT_COMPONENT  macro  is  an  enumeration  named      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      trace_XXXX where XXXX  is one of the component  names defined in the
95      internal file <freetype/internal/fttrace.h>.      internal file `freetype/internal/fttrace.h'.
96    
97      Each  such component  is assigned  a "debug  level", ranging  from 0      Each  such component  is assigned  a `debug  level', ranging  from 0
98      to 7,  through  the  use   of  the  FT2_DEBUG  environment  variable      to  7,  through  the  use  of  the  FT2_DEBUG  environment  variable
99      (described below) when a program linked with FreeType starts.      (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      When FT_TRACE  is called, its  level is compared  to the one  of the
# Line 106  its code: Line 107  its code:
107      least* 2.      least* 2.
108    
109      The  second  parameter  to  FT_TRACE must  contain  parentheses  and      The  second  parameter  to  FT_TRACE must  contain  parentheses  and
110      correspond to a printf-like call, as in:      correspond to a printf-like call, as in
111    
112        FT_TRACE( 2, ( "your %s is not %s\n", "foo", "bar" ) )        FT_TRACE( 2, ( "your %s is not %s\n", "foo", "bar" ) )
113    
114      The shortcut macros  FT_TRACE0, FT_TRACE1, FT_TRACE2_, ... FT_TRACE7      The shortcut macros  FT_TRACE0, FT_TRACE1, FT_TRACE2, ..., FT_TRACE7
115      can be  used with  constant level indices,  and are much  cleaner to      can be  used with  constant level indices,  and are much  cleaner to
116      use, as in      use, as in
117    
# Line 121  III. Environment variables Line 122  III. Environment variables
122  --------------------------  --------------------------
123    
124  The  following  environment   variables  control  debugging  output  and  The  following  environment   variables  control  debugging  output  and
125  behaviour of FreeType at runtime:  behaviour of FreeType at runtime.
126    
127    
128    FT2_DEBUG    FT2_DEBUG
129    
# Line 131  behaviour of FreeType at runtime: Line 133  behaviour of FreeType at runtime:
133    
134         component1:level1 component2:level2 component3:level3 ...         component1:level1 component2:level2 component3:level3 ...
135    
136      where "componentX" is the name of a tracing component, as defined in      where `componentX' is the name of a tracing component, as defined in
137      "fttrace.h",  but  without the  "trace_"  prefix.   "levelX" is  the      `fttrace.h',  but  without the  `trace_'  prefix.   `levelX' is  the
138      corresponding level to use at runtime.      corresponding level to use at runtime.
139    
140      "any"  is a  special  component  name that  will  be interpreted  as      `any'  is a  special  component  name that  will  be interpreted  as
141      "any/all components".  For example, the following definitions      `any/all components'.  For example, the following definitions
142    
143         set FT2_DEBUG=any:2 memory:5 io:4        (on Windows)         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)         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      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      the memory and io components which will be set to trace levels 5 and
148      and 4, respectively.      4, respectively.
149    
150    
151    FT2_DEBUG_MEMORY    FT2_DEBUG_MEMORY
152    
# Line 154  behaviour of FreeType at runtime: Line 157  behaviour of FreeType at runtime:
157      considerably saves time when debugging new additions to the library.      considerably saves time when debugging new additions to the library.
158    
159      This  code  is  only  compiled  when  FreeType  is  built  with  the      This  code  is  only  compiled  when  FreeType  is  built  with  the
160      FT_DEBUG_MEMORY macro  #defined in  "ftoption.h" though, it  will be      FT_DEBUG_MEMORY macro  #defined in  `ftoption.h' though, it  will be
161      ignored in other builds.      ignored in other builds.
162    
163    
164    FT2_ALLOC_TOTAL_MAX    FT2_ALLOC_TOTAL_MAX
165    
166      This  variable is ignored  if FT2_DEBUG_MEMORY  is not  defined.  It      This  variable is ignored  if FT2_DEBUG_MEMORY  is not  defined.  It
# Line 168  behaviour of FreeType at runtime: Line 172  behaviour of FreeType at runtime:
172      If it is  undefined, or if its value is  not strictly positive, then      If it is  undefined, or if its value is  not strictly positive, then
173      no allocation bounds are checked at runtime.      no allocation bounds are checked at runtime.
174    
175    
176    FT2_ALLOC_COUNT_MAX    FT2_ALLOC_COUNT_MAX
177        
178      This  variable is ignored  if FT2_DEBUG_MEMORY  is not  defined.  It      This  variable is ignored  if FT2_DEBUG_MEMORY  is not  defined.  It
# Line 177  behaviour of FreeType at runtime: Line 182  behaviour of FreeType at runtime:
182      engine's robustness.      engine's robustness.
183            
184      If it is  undefined, or if its value is  not strictly positive, then      If it is  undefined, or if its value is  not strictly positive, then
185      no allocation bounsd are checked at runtime.      no allocation bounds are checked at runtime.
186    
187  ------------------------------------------------------------------------  ------------------------------------------------------------------------
188    
189  Copyright 2002, 2003, 2004 by  Copyright 2002, 2003, 2004, 2005 by
190  David Turner, Robert Wilhelm, and Werner Lemberg.  David Turner, Robert Wilhelm, and Werner Lemberg.
191    
192  This  file  is  part  of the  FreeType  project, and may  only be  used,  This  file is  part  of the  FreeType  project, and  may  only be  used,
193  modified,  and  distributed  under  the  terms of  the FreeType  project  modified,  and  distributed under  the  terms  of  the FreeType  project
194  license, LICENSE.TXT.   By continuing to use, modify, or distribute this  license, LICENSE.TXT.  By continuing  to use, modify, or distribute this
195  file you  indicate that  you have  read the  license and understand  and  file  you indicate that  you have  read the  license and  understand and
196  accept it fully.  accept it fully.
197    
198    

Legend:
Removed from v.1.4  
changed lines
  Added in v.1.5

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26