summaryrefslogtreecommitdiff
path: root/Build/source/libs/freetype2/freetype-src/docs/DEBUG
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/libs/freetype2/freetype-src/docs/DEBUG')
-rw-r--r--Build/source/libs/freetype2/freetype-src/docs/DEBUG216
1 files changed, 216 insertions, 0 deletions
diff --git a/Build/source/libs/freetype2/freetype-src/docs/DEBUG b/Build/source/libs/freetype2/freetype-src/docs/DEBUG
new file mode 100644
index 00000000000..a96b5e27b8d
--- /dev/null
+++ b/Build/source/libs/freetype2/freetype-src/docs/DEBUG
@@ -0,0 +1,216 @@
+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 `ftoption.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 does
+ 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' dumps memory statistics,
+ including the list of leaked memory blocks and optionally 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) without stopping 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 aborts 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. 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', which names 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 io
+
+ The value of the `FT_COMPONENT' macro is one of the component
+ names defined in the internal file `internal/fttrace.h'. If you
+ modify the FreeType source code and insert a new `FT_COMPONENT'
+ macro, you must register it in `fttrace.h'. If you insert or
+ remove many trace macros, you can test for undefined or unused
+ trace macros with the script `src/tools/chktrcmp.py'.
+
+ Each such component is assigned a `debug level', ranging from
+ value 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 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.
+
+ The second parameter to `FT_TRACE' must contain parentheses and
+ corresponds 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'. `levelX' is the corresponding level to use at
+ runtime.
+
+ `any' is a special component name that is 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 are set to the trace levels 5
+ and 4, respectively.
+
+
+ FT2_DEBUG_MEMORY
+
+ This environment variable, when defined, tells FreeType to use a
+ debugging memory manager that tracks 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 is
+ 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, 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, no
+ 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.
+
+------------------------------------------------------------------------
+
+Copyright (C) 2002-2020 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 ---