diff options
author | Werner Lemberg <wl@gnu.org> | 2003-04-21 13:30:27 +0000 |
---|---|---|
committer | Werner Lemberg <wl@gnu.org> | 2003-04-21 13:30:27 +0000 |
commit | a16c4a7129d79c18ed74cdf825b67fe17d4707cb (patch) | |
tree | 81718adb89ad86c22896bbe30b4f4a8d683be932 /docs/DEBUG | |
parent | 692bbe59daf7046bb5d6951df9f95a1a7ec61c8b (diff) | |
download | freetype2-a16c4a7129d79c18ed74cdf825b67fe17d4707cb.tar.gz |
* doc/INSTALL.UNX: Cleaned up.
Other minor fixes/beautifying/formatting.
Diffstat (limited to 'docs/DEBUG')
-rw-r--r-- | docs/DEBUG | 76 |
1 files changed, 38 insertions, 38 deletions
diff --git a/docs/DEBUG b/docs/DEBUG index 03ed70311..c85ef3cb1 100644 --- a/docs/DEBUG +++ b/docs/DEBUG @@ -1,5 +1,5 @@ -Debugging within the FreeType sources: -====================================== +Debugging within the FreeType sources +===================================== I. Configuration macros ----------------------- @@ -12,15 +12,15 @@ 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 - used to print error messages during program execution. This will - not stop the program, but is very useful to spot invalid fonts - during development and code workarounds for them. + 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 the FT_ERROR macro - and the FT_TRACE one. This also includes the variants FT_TRACE0, - FT_TRACE1, FT_TRACE2, ..., FT_TRACE6. + #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_TRACE6. The trace macros are used to send debugging messages when an appropriate "debug level" is configured at runtime through the @@ -28,21 +28,21 @@ located in the file "ftoptions.h". The macros are: FT_DEBUG_MEMORY - If this macro is #defined, the FreeType engines is linked with a + 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's always a very good idea to define + 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 un-affected. + manager is ignored, and performance is unaffected. II. Debugging macros @@ -59,7 +59,7 @@ its code: either FT_DEBUG_LEVEL_ERROR or FT_DEBUG_LEVEL_TRACE are defined in "ftoption.h". - Note that you must use with a printf-like signature, but with double + 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" )); @@ -93,9 +93,9 @@ its code: trace_XXXX where XXXX is one of the component names defined in the internal file <freetype/internal/fttrace.h>. - Each such component is assigned a "debug level", ranging from 0 to 6 - when a program linked with FreeType starts, through the use of the - FT2_DEBUG environment variable, described later. + Each such component is assigned a "debug level", ranging from 0 + to 6, 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 @@ -106,7 +106,7 @@ its code: least* 2. The second parameter to FT_TRACE must contain parentheses and - correspond to a print-like call, as in: + correspond to a printf-like call, as in: FT_TRACE( 2, ( "your %s is not %s\n", "foo", "bar" ) ) @@ -123,7 +123,6 @@ 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 @@ -133,51 +132,52 @@ behaviour of FreeType at runtime: 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, and "levelX" is the + "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) + 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. + 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 leaked memory blocks as + 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 leaked blocks were allocated, which + 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. + 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. - + 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 sepcify 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. + 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 bounsd are checked at runtime. + If it is undefined, or if its value is not strictly positive, then + no allocation bounsd are checked at runtime. + -End of file +--- end of DEBUG --- |