| 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 --- |