From 526d973e315ea058b02c1662c6c189edd337b22e Mon Sep 17 00:00:00 2001 From: Priyeshkkumar Date: Fri, 28 Aug 2020 11:28:17 +0530 Subject: [PATCH] [docs] Updated logging related documentation * docs/DEBUG: Updates related to `FT_LOGGING'. * README.git: Updates related to logging * src/sfnt/ttload.c (tt_face_load_font_dir): Changed layout of tracing messages. --- README.git | 8 +++ docs/DEBUG | 132 ++++++++++++++++++++++++++++++++++++++++++++++ src/sfnt/ttload.c | 6 +-- 3 files changed, 143 insertions(+), 3 deletions(-) diff --git a/README.git b/README.git index c4f0033c1..caebe9ac5 100644 --- a/README.git +++ b/README.git @@ -35,6 +35,14 @@ Similarly, a build with `cmake' can be done directly from the git repository. +For using the `FT_LOGGING' macro while debugging(see docs/DEBUG for +more information) use the following git commands to checkout `dlg' +library as a git submodule. + + git submodule init + git submodule update + + ---------------------------------------------------------------------- Copyright (C) 2005-2020 by diff --git a/docs/DEBUG b/docs/DEBUG index a96b5e27b..4da1c17cd 100644 --- a/docs/DEBUG +++ b/docs/DEBUG @@ -44,6 +44,32 @@ 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 + + As mentioned above if `FT_DEBUG_LEVEL_ERROR' and + `FT_DEBUG_LEVEL_TRACE' macros are defined, FreeType will send the + debug and trace logs outputted from `FT_ERROR' and `FT_TRACE' + macros to `stderr'. + + `FT_LOGGING' is a new macro which is introduced to enhance the + capabilities of `FT_TRACE' and `FT_ERROR' macros. + `FT_LOGGING' macro depends on `FT_DEBUG_LEVEL_TRACE' and + `FT_DEBUG_LEVEL_ERROR', therefore these macros will automatically + be #defined once `FT_LOGGING' macro is #defined and + the behaviour of `FT_TRACE' and `FT_ERROR' macros will change. + Now, `FT_TRACE' and `FT_ERROR' macros will start sending the + tracing and debugging messages to the file system instead of + `stderr'. + On the file system the log file will be generated on the path + specified using `FT_LOGGING_FILE' environment variable(more on + this later). + + There is an additional support of logging Time and the name of + the `FT_COMPONENT' from which the current log is generated along + with the actual tracing and debugging message, and for this user + will have to define additional tags under the `FT2_DEBUG' + environment variable(More details under section `FT2_DEBUG' under + Environment Variables heading). II. Debugging macros -------------------- @@ -150,6 +176,48 @@ behaviour of FreeType at runtime. the memory and io components, which are set to the trace levels 5 and 4, respectively. + `FT_LOGGING' related tags: + + As mentioned above in the `FT_LOGGING' section below are the + additional tags which can be added in `FT2_DEBUG' environment + variable to log the time and the value of `FT_COMPONENT' in the + actual log message: + * -v: For printing the name of FreeType's component from which + the current log is produced. + * -t: For printing the time(in milliseconds) along with actual + log message. + + Example: + + Case 1: FT2_DEBUG="any:7 memory:5 -vt" + + [20:32:02:44969 ttload] table directory loaded + + Case 2: FT2_DEBUG="any:7 memory:5 -t" + + [20:32:02:44969 ttload] table directory loaded + + Case 3: FT2_DEBUG="any:7 memory:5 -v" + + [ttload] table directory loaded + + + FT_LOGGING_FILE + + This variable is only used when FreeType is built with + `FT_LOGGING' macro defined. It contains the path to the file where + the user wants to put his log file. + + On Linux with bash: + export FT_LOGGING_FILE="/tmp/freetype2.log" + + On Windows: + set FT_LOGGING_FILE=C:\Users\AppData\Local\Temp\freetype2.log + + Use the following `FT_LOGGING_FILE' value to print logs to stderr. + + export FT_LOGGING_FILE=/dev/stderr + FT2_DEBUG_MEMORY @@ -201,6 +269,70 @@ 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' +-------------------------------------------- + +With the support of `FT_LOGGING', four APIs have been introduced for +providing additional debugging support to the applications using +FreeType. + + FT_Trace_Set_Level( const char* ) + + If FreeType is configured with `FT_LOGGING' the levels of tracing + component set using `FT2_DEBUG' environment variable is considered + as a default value. + And this function can be used change/set the value of the levels + of tracing components at run-time. + + NOTE: If the environment variable `FT2_DEBUG is not defined the + default value of the levels of tracing components will be NULL. + + FT_Trace_Set_Default_Level(): + + If previously, `FT_Trace_Set_Level' functions is used to set new + values of the tracing components of FreeType, this function could + be used to reset the level of tracing components to the default + value. + Hence, the functions `FT_Trace_Set_Default_Level' and + `FT_Trace_Set_Level' could be combined and used together to + change the trace levels of FreeType's components for a particular + block of code. + + FT_Set_Log_Handler( ft_custom_log_handler ): + + This API has been provided under the `FT_LOGGING' macro to support + a feature wherein a custom log handler can be provided based on + user’s choice. Doing so, FreeType will start calling the custom + handler for new log messages and will no longer write these + messages in predefined log file of FreeType. It will totally + depend on user how the log messages will be handled. + User just need to call this API with an argument of type + ft_custom_log_handler which should match following function + prototype: + + void (*ft_custom_log_handler)( const char* ft_component, + const char* fmt, + va_list args ); + + + + FT_Set_Default_Log_Handler(): + + If the user has chosen to set a custom log handler using the + `FT_Set_Log_Handler' API above, the current API can be used to + reset back the log handler to the Freetype's inbuilt log handler. + Hence, the functions `FT_Set_Default_Log_Handler' and + `FT_Set_Log_Handler' in combination can be used to separately + handle the trace or error logs generated by a particular block + of code. + + +Applications need to #include the following header file to avail the +above APIs: + + #include + ------------------------------------------------------------------------ Copyright (C) 2002-2020 by diff --git a/src/sfnt/ttload.c b/src/sfnt/ttload.c index 4b46f4135..043a8f93a 100644 --- a/src/sfnt/ttload.c +++ b/src/sfnt/ttload.c @@ -416,9 +416,9 @@ FT_FRAME_ENTER( sfnt.num_tables * 16L ) ) goto Exit; - FT_TRACE2(( "\n" - " tag offset length checksum\n" - " ----------------------------------\n" )); + FT_TRACE2(( " tag offset length checksum\n")); + FT_TRACE2(( " ----------------------------------\n" )); + valid_entries = 0; for ( nn = 0; nn < sfnt.num_tables; nn++ )