diff options
author | Priyesh Kumar <priyeshkkumar@gmail.com> | 2020-08-28 11:28:17 +0530 |
---|---|---|
committer | Werner Lemberg <wl@gnu.org> | 2020-12-04 16:19:42 +0100 |
commit | ab0ea068ee5acf6a6e1a77d5c315fb8934ce4190 (patch) | |
tree | 352335a1591142a4464632e0e75d52e1bb3537ae /docs | |
parent | 6d9e6b21e5ca88b0b6dfa28ebcc86c99971bc60f (diff) | |
download | freetype2-ab0ea068ee5acf6a6e1a77d5c315fb8934ce4190.tar.gz |
Update logging related documentation.
* docs/DEBUG: Updates related to `FT_LOGGING`.
* README.git: Updates related to logging.
Diffstat (limited to 'docs')
-rw-r--r-- | docs/DEBUG | 94 |
1 files changed, 94 insertions, 0 deletions
diff --git a/docs/DEBUG b/docs/DEBUG index a96b5e27b..48bea346a 100644 --- a/docs/DEBUG +++ b/docs/DEBUG @@ -44,6 +44,21 @@ located in the file `ftoption.h'. The macros are: When `FT2_DEBUG_MEMORY' isn't defined at runtime, the debugging memory manager is ignored, and performance is unaffected. + FT_LOGGING + + #define this macro for enhanced logging support; it automatically + sets `FT_DEBUG_LEVEL_TRACE' and `FT_DEBUG_LEVEL_ERROR'. + + If defined, `FT_TRACE' and `FT_ERROR' can send tracing and + debugging messages to a file. The location of the log file has to + be set with the `FT_LOGGING_FILE' environment variable (more on + this later). + + The main enhancements are the possibility of logging the time and + the name of the `FT_COMPONENT' macro together with the affected + `FT_TRACE' or `FT_ERROR' calls. See below how to activate this in + the `FT2_DEBUG' environment variable. + II. Debugging macros -------------------- @@ -150,6 +165,43 @@ behaviour of FreeType at runtime. the memory and io components, which are set to the trace levels 5 and 4, respectively. + If `FT_LOGGING' is defined, two more options are available. + + * -v: Print also the name of FreeType's component from which the + current log is produced. + + * -t: Print also the time. + + Here are some examples how the output might look like. + + FT2_DEBUG="any:7 memory:5 -vt" + + => [20:32:02:44969 ttload] table directory loaded + + FT2_DEBUG="any:7 memory:5 -t" + + => [20:32:02:44969] table directory loaded + + FT2_DEBUG="any:7 memory:5 -v" + + => [ttload] table directory loaded + + + FT_LOGGING_FILE + + This variable is only used if FreeType is built with the + `FT_LOGGING' macro defined. It contains the path to the file + where the user wants to put his log file. If it is not set, + FreeType uses stderr. + + Examples: + + On UNIX-like systems with bash: + export FT_LOGGING_FILE="/tmp/freetype2.log" + + On Windows: + set FT_LOGGING_FILE=C:\Users\AppData\Local\Temp\freetype2.log + FT2_DEBUG_MEMORY @@ -201,6 +253,48 @@ behaviour of FreeType at runtime. If it is undefined, or if its value is not strictly positive, freed blocks are released at runtime. + +IV. Additional Capabilities with `FT_LOGGING' +--------------------------------------------- + +If `FT_LOGGING' is defined, four APIs are available to provide +additional debugging support. Use + + #include<freetype/ftlogging.h> + +to access them. + + FT_Trace_Set_Level( const char* level ) + + By default, FreeType uses the tracing levels set in the + `FT2_DEBUG' environment variable. Use this function to override + the value with `level'. Use value `NULL' to disable tracing. + + FT_Trace_Set_Default_Level(): + + Reset the tracing levels to the default value, i.e., the value of + the `FT2_DEBUG' environment variable or no tracing if not set. + + FT_Set_Log_Handler( ft_custom_log_handler handler ): + + Use `handler' as a custom handler for formatting tracing and error + messages. The `ft_custom_log_handler' typedef has the following + prototype. + + void + (*ft_custom_log_handler)( const char* ft_component, + const char* fmt, + va_list args ); + + `ft_component' is the current component like `ttload', `fmt' is the + first argument of `FT_TRACE' or `FT_ERROR', and `args' holds the + remaining arguments. + + FT_Set_Default_Log_Handler(): + + Reset the log handler to the default version. + + ------------------------------------------------------------------------ Copyright (C) 2002-2020 by |