rgraves
/
freetype2
forked from minhngoc25a/freetype2
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

docs/DEBUG: Document environment variable `FT2_KEEP_ALIVE'. 

Also do some formatting and minor edits.
This commit is contained in:
Werner Lemberg 2019-10-06 20:07:09 +02:00
parent 1f4e5bcb19
commit d355a73aa3
1 changed files with 73 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

133
docs/DEBUG
View File

@ -11,20 +11,20 @@ located in the file `ftoption.h'. The macros are:
FT_DEBUG_LEVEL_ERROR FT_DEBUG_LEVEL_ERROR
#define this macro if you want to compile the FT_ERROR macro calls #define this macro if you want to compile the `FT_ERROR' macro
to print error messages during program execution. This will not calls to print error messages during program execution. This does
stop the program. Very useful to spot invalid fonts during not stop the program. Very useful to spot invalid fonts during
development and to code workarounds for them. development and to code workarounds for them.
FT_DEBUG_LEVEL_TRACE FT_DEBUG_LEVEL_TRACE
#define this macro if you want to compile both macros FT_ERROR and #define this macro if you want to compile both macros `FT_ERROR'
FT_TRACE. This also includes the variants FT_TRACE0, FT_TRACE1, and `FT_TRACE'. This also includes the variants `FT_TRACE0',
FT_TRACE2, ..., FT_TRACE7. `FT_TRACE1', `FT_TRACE2', ..., `FT_TRACE7'.
The trace macros are used to send debugging messages when an The trace macros are used to send debugging messages when an
appropriate `debug level' is configured at runtime through the appropriate `debug level' is configured at runtime through the
FT2_DEBUG environment variable (more on this later). `FT2_DEBUG' environment variable (more on this later).
FT_DEBUG_MEMORY FT_DEBUG_MEMORY
@ -32,16 +32,16 @@ located in the file `ftoption.h'. The macros are:
small but effective debugging memory manager that tracks all small but effective debugging memory manager that tracks all
allocations and frees that are performed within the font engine. allocations and frees that are performed within the font engine.
When the FT2_DEBUG_MEMORY environment variable is defined at When the `FT2_DEBUG_MEMORY' environment variable is defined at
runtime, a call to FT_Done_FreeType will dump memory statistics, runtime, a call to `FT_Done_FreeType' dumps memory statistics,
including the list of leaked memory blocks with the source including the list of leaked memory blocks and optionally with the
locations where these were allocated. It is always a very good source locations where these were allocated. It is always a very
idea to define this in development builds. This works with _any_ good idea to define this in development builds. This works with
program linked to FreeType, but requires a big deal of memory (the _any_ program linked to FreeType, but requires a big deal of
debugging memory manager never frees the blocks to the heap in memory (the debugging memory manager never frees the blocks to the
order to detect double frees). heap in order to detect double frees).
When FT2_DEBUG_MEMORY isn't defined at runtime, the debugging When `FT2_DEBUG_MEMORY' isn't defined at runtime, the debugging
memory manager is ignored, and performance is unaffected. memory manager is ignored, and performance is unaffected.
@ -55,10 +55,10 @@ debugging its code:
1. FT_ERROR(( ... )) 1. FT_ERROR(( ... ))
This macro is used to send debug messages that indicate relatively This macro is used to send debug messages that indicate relatively
serious errors (like broken font files), but will not stop the serious errors (like broken font files) without stopping the
execution of the running program. Its code is compiled only when execution of the running program. Its code is compiled only when
either FT_DEBUG_LEVEL_ERROR or FT_DEBUG_LEVEL_TRACE are defined in either `FT_DEBUG_LEVEL_ERROR' or `FT_DEBUG_LEVEL_TRACE' are
`ftoption.h'. defined in `ftoption.h'.
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
parentheses, like in parentheses, like in
@ -69,53 +69,53 @@ debugging its code:
2. FT_ASSERT( condition ) 2. FT_ASSERT( condition )
This macro is used to check strong assertions at runtime. If its This macro is used to check strong assertions at runtime. If its
condition isn't TRUE, the program will abort with a panic message. condition isn't TRUE, the program aborts with a panic message.
Its code is compiled when either FT_DEBUG_LEVEL_ERROR or Its code is compiled when either `FT_DEBUG_LEVEL_ERROR' or
FT_DEBUG_LEVEL_TRACE are defined. You don't need double `FT_DEBUG_LEVEL_TRACE' are defined. You don't need double
parentheses here. For example parentheses here. Example:
FT_ASSERT( ptr != NULL ); FT_ASSERT( ptr != NULL );
3. FT_TRACE( level, (message...) ) 3. FT_TRACE( level, (message...) )
The FT_TRACE macro is used to send general-purpose debugging The `FT_TRACE' macro is used to send general-purpose debugging
messages during program execution. This macro uses an *implicit* messages during program execution. This macro uses an *implicit*
macro named FT_COMPONENT used to name the current FreeType macro named `FT_COMPONENT', which names the current FreeType
component being run. component being run.
The developer should always define FT_COMPONENT as appropriate, The developer should always define `FT_COMPONENT' as appropriate,
for example as in for example as in
#undef FT_COMPONENT #undef FT_COMPONENT
#define FT_COMPONENT io #define FT_COMPONENT io
The value of the FT_COMPONENT macro is one of the component The value of the `FT_COMPONENT' macro is one of the component
names defined in the internal file `internal/fttrace.h'. If you names defined in the internal file `internal/fttrace.h'. If you
modify FreeType source and insert new FT_COMPONENT macro, you must modify the FreeType source code and insert a new `FT_COMPONENT'
register it in `fttrace.h'. If you insert or remove many trace macro, you must register it in `fttrace.h'. If you insert or
macros, you can check the undefined or the unused trace macro by remove many trace macros, you can test for undefined or unused
`src/tools/chktrcmp.py'. trace macros with the script `src/tools/chktrcmp.py'.
Each such component is assigned a `debug level', ranging from 0 to Each such component is assigned a `debug level', ranging from
7, through the use of the FT2_DEBUG environment variable value 0 to 7, through the use of the `FT2_DEBUG' environment
(described below) when a program linked with FreeType starts. variable (described below) when a program linked with FreeType
starts.
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
corresponding component. Messages with trace levels *higher* than corresponding component. Messages with trace levels *higher* than
the corresponding component level are filtered and never printed. the corresponding component level are filtered out 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, etc.
This means that trace messages with level 0 are always printed, The second parameter to `FT_TRACE' must contain parentheses and
those with level 2 are only printed when the component level is corresponds to a printf-like call, as in
*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" ) ) FT_TRACE( 2, ( "your %s is not %s\n", "foo", "bar" ) )
The shortcut macros FT_TRACE0, FT_TRACE1, FT_TRACE2, ..., The shortcut macros `FT_TRACE0', `FT_TRACE1', `FT_TRACE2', ...,
FT_TRACE7 can be used with constant level indices, and are much `FT_TRACE7' can be used with constant level indices, and are much
cleaner to use, as in cleaner to use, as in
FT_TRACE2(( "your %s is not %s\n", "foo", "bar" )); FT_TRACE2(( "your %s is not %s\n", "foo", "bar" ));
@ -131,7 +131,7 @@ behaviour of FreeType at runtime.
FT2_DEBUG FT2_DEBUG
This variable is only used when FreeType is built with This variable is only used when FreeType is built with
FT_DEBUG_LEVEL_TRACE defined. It contains a list of component `FT_DEBUG_LEVEL_TRACE' defined. It contains a list of component
level definitions, following this format: level definitions, following this format:
component1:level1 component2:level2 component3:level3 ... component1:level1 component2:level2 component3:level3 ...
@ -140,53 +140,66 @@ behaviour of FreeType at runtime.
in `fttrace.h'. `levelX' is the corresponding level to use at in `fttrace.h'. `levelX' is the corresponding level to use at
runtime. runtime.
`any' is a special component name that will be interpreted as `any' is a special component name that is interpreted as `any/all
`any/all components'. For example, the following definitions components'. For example, the following definitions
set FT2_DEBUG=any:2 memory:5 io:4 (on Windows) set FT2_DEBUG=any:2 memory:5 io:4 (on Windows)
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)
both stipulate that all components should have level 2, except for both stipulate that all components should have level 2, except for
the memory and io components which will be set to trace levels 5 the memory and io components, which are set to the trace levels 5
and 4, respectively. and 4, respectively.
FT2_DEBUG_MEMORY FT2_DEBUG_MEMORY
This environment variable, when defined, tells FreeType to use a This environment variable, when defined, tells FreeType to use a
debugging memory manager that will track leaking memory blocks as debugging memory manager that tracks leaking memory blocks as well
well as other common errors like double frees. It is also capable as other common errors like double frees. It is also capable of
of reporting _where_ the leaking blocks were allocated, which reporting _where_ the leaking blocks were allocated, which
considerably saves time when debugging new additions to the considerably saves time when debugging new additions to the
library. library.
This code is only compiled when FreeType is built with the This code is only compiled when FreeType is built with the
FT_DEBUG_MEMORY macro #defined in `ftoption.h' though, it will be `FT_DEBUG_MEMORY' macro #defined in `ftoption.h' though, it is
ignored in other builds. ignored in other builds.
FT2_ALLOC_TOTAL_MAX FT2_ALLOC_TOTAL_MAX
This variable is ignored if FT2_DEBUG_MEMORY is not defined. It This variable is ignored if `FT2_DEBUG_MEMORY' is not defined. It
allows you to specify a maximum heap size for all memory allows you to specify a maximum heap size for all memory
allocations performed by FreeType. This is very useful to test allocations performed by FreeType. This is very useful to test
the robustness of the font engine and programs that use it in the robustness of the font engine and programs that use it in
tight memory conditions. tight memory conditions.
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, no
no allocation bounds are checked at runtime. allocation bounds are checked at runtime.
FT2_ALLOC_COUNT_MAX FT2_ALLOC_COUNT_MAX
This variable is ignored if FT2_DEBUG_MEMORY is not defined. It This variable is ignored if `FT2_DEBUG_MEMORY' is not defined. It
allows you to specify a maximum number of memory allocations allows you to specify a maximum number of memory allocations
performed by FreeType before returning the error performed by FreeType before returning the error
FT_Err_Out_Of_Memory. This is useful for debugging and testing `FT_Err_Out_Of_Memory'. This is useful for debugging and testing
the engine's robustness. the engine's robustness.
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, no
no allocation bounds are checked at runtime. allocation bounds are checked at runtime.
FT2_KEEP_ALIVE
This variable is ignored if `FT2_DEBUG_MEMORY' is not defined.
`Keep alive' means that freed blocks aren't released to the heap.
This is useful to detect double-frees or weird heap corruption,
reporting the source code location of the original allocation and
deallocation in case of a problem. It uses large amounts of
memory, however.
If it is undefined, or if its value is not strictly positive,
freed blocks are released at runtime.
------------------------------------------------------------------------ ------------------------------------------------------------------------