| 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 `ftoptions.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 will 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 will dump memory statistics, |
| including the list of leaked memory blocks 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. |
| |
| |
| 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), but will not stop 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 will abort 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. For 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 used to name 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 trace_io |
| |
| The value of the FT_COMPONENT macro is an enumeration named |
| `trace_XXXX' where `XXXX' is one of the component names defined in |
| the internal file `internal/fttrace.h'. If you modify FreeType |
| source and insert new `trace_XXXX' macro, you must register it in |
| `fttrace.h'. If you insert or remove many trace macros, you can |
| check the undefined or the unused trace macro by |
| `src/tools/chktrcmp.py'. |
| |
| Each such component is assigned a `debug level', ranging from 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 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. |
| |
| The second parameter to FT_TRACE must contain parentheses and |
| correspond 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', but without the `trace_' prefix. `levelX' is the |
| corresponding level to use at runtime. |
| |
| `any' is a special component name that will be 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 will be set to trace levels 5 |
| and 4, respectively. |
| |
| |
| FT2_DEBUG_MEMORY |
| |
| This environment variable, when defined, tells FreeType to use a |
| debugging memory manager that will track 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 will be |
| 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, then |
| 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, then |
| no allocation bounds are checked at runtime. |
| |
| ------------------------------------------------------------------------ |
| |
| Copyright 2002-2015 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 --- |
