From 4f472b5799642f0111c276a961d3133e7a145412 Mon Sep 17 00:00:00 2001 From: Priyeshkkumar Date: Mon, 24 Aug 2020 10:58:17 +0530 Subject: [PATCH] * include/freetype/ftlogging.h (FT_Trace_Set_Level): Use more relevant parameters name in function declaration. (FT_Custom_Log_Handler): Changed function name `ft_custom_log_handler'-> `FT_Custom_Log_Handler'. Updated documentation. * include/freetype/ftchapters.h: Added `debugging_apis' section under `support_api' chapter. * .gitmodules: Updated submodule to track recent changes in dlg library. * src/base/ftdebug.c (ft_log_handler): Updated code according to the recent updates in dlg library. (ft_logging_init): Added environment variable `FT_LOGGING_FILE', the variable `ft_fileptr' stores it's value. Changed function name `ft_custom_log_handler'-> `FT_Custom_Log_Handler'. * include/freetype/internal/ftdebug.h: Changed function name `ft_custom_log_handler'-> `FT_Custom_Log_Handler'. * README.git: Updated documentation. * docs/DEBUG: Updated documentation. --- .gitmodules | 1 - README.git | 7 ++ [priyesh]ChangeLog | 27 ++++++ docs/DEBUG | 116 ++++++++++++++++++++++ include/freetype/ftchapters.h | 1 + include/freetype/ftlogging.h | 143 +++++++++++++++++++++++----- include/freetype/internal/ftdebug.h | 2 +- src/base/ftdebug.c | 38 +++----- submodules/dlg | 2 +- 9 files changed, 284 insertions(+), 53 deletions(-) diff --git a/.gitmodules b/.gitmodules index 3b47f1743..c02c831d0 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,4 +1,3 @@ - [submodule "submodules/dlg"] path = submodules/dlg url = https://github.com/nyorain/dlg.git diff --git a/README.git b/README.git index c4f0033c1..3b8338adf 100644 --- a/README.git +++ b/README.git @@ -35,6 +35,13 @@ 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/[priyesh]ChangeLog b/[priyesh]ChangeLog index f5e1ddfe6..a8b1ae525 100644 --- a/[priyesh]ChangeLog +++ b/[priyesh]ChangeLog @@ -1,3 +1,30 @@ +2020-08-24 Priyesh Kumar + + * include/freetype/ftlogging.h (FT_Trace_Set_Level): Use more relevant + parameters name in function declaration. + (FT_Custom_Log_Handler): Changed function name `ft_custom_log_handler'-> + `FT_Custom_Log_Handler'. + Updated documentation. + + * include/freetype/ftchapters.h: Added `debugging_apis' section under + `support_api' chapter. + + * .gitmodules: Updated submodule to track recent changes in dlg library. + + * src/base/ftdebug.c (ft_log_handler): Updated code according to the + recent updates in dlg library. + (ft_logging_init): Added environment variable `FT_LOGGING_FILE', the + variable `ft_fileptr' stores it's value. + Changed function name `ft_custom_log_handler'-> + `FT_Custom_Log_Handler'. + + * include/freetype/internal/ftdebug.h: Changed function name + `ft_custom_log_handler'-> `FT_Custom_Log_Handler'. + + * README.git: Updated documentation. + + * docs/DEBUG: Updated documentation. + 2020-08-21 Priyesh Kumar * include/freetype/internal/ftdebug.h (FT_LOG ): Use more relevant diff --git a/docs/DEBUG b/docs/DEBUG index a96b5e27b..49365ba65 100644 --- a/docs/DEBUG +++ b/docs/DEBUG @@ -26,6 +26,33 @@ located in the file `ftoption.h'. The macros are: appropriate `debug level' is configured at runtime through the `FT2_DEBUG' environment variable (more on this later). + 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 with name `freetype2.log' will be + generated in the same directory where the executable is placed. + + 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). + + FT_DEBUG_MEMORY If this macro is #defined, the FreeType engine is linked with a @@ -150,6 +177,31 @@ 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 + FT2_DEBUG_MEMORY @@ -201,6 +253,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/include/freetype/ftchapters.h b/include/freetype/ftchapters.h index 2ee26973e..833d75df2 100644 --- a/include/freetype/ftchapters.h +++ b/include/freetype/ftchapters.h @@ -123,6 +123,7 @@ * gzip * lzw * bzip2 + * debugging_apis * */ diff --git a/include/freetype/ftlogging.h b/include/freetype/ftlogging.h index 21ffb4926..e5bc64731 100644 --- a/include/freetype/ftlogging.h +++ b/include/freetype/ftlogging.h @@ -1,47 +1,144 @@ -#include FT_CONFIG_CONFIG_H +/**************************************************************************** + * + * ftlogging.h + * + * Additional debugging APIs. + * + * Copyright (C) 2008-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. + * + */ + #ifndef FTLOGGING_H_ #define FTLOGGING_H_ +#include +#include FT_CONFIG_CONFIG_H FT_BEGIN_HEADER - /*************************************************************************** - * - * If FT_LOGGING is enabled, user can change the trace level at run time - * using the function `FT_Trace_Set_Level()` by passing the desired trace - * level as an argument. - * User can also set the default trace level which is supplied by - * environment variable `FT2_DEBUG` - * See ftdebug.c for definitions - * - */ + /************************************************************************** + * + * @section: + * debugging_apis + * + * @title: + * External Debugginng APIs + * + * @abstract: + * Pubic APIs to use while debugging using `FT_LOGGING' macro + * + * @description: + * This section contains the declaration the public APIs which can be + * used to debug an application using `FT_LOGGING'. + * + */ + + /************************************************************************** + * + * @function: + * FT_Trace_Set_Level + * + * @description: + * To change the levels of tracing components at run time. + * + * @input: + * + * tracing_level :: + * New levels of of tracing components. + * + * @example: + * This function can be used to change the tracing levels of FreeType's + * component as follows: + * + * ``` + * new_levels = "any:7 memory:0"; + * FT_Trace_Set_Level( new_levels ); + * ``` + */ FT_EXPORT( void ) - FT_Trace_Set_Level( const char* level ); + FT_Trace_Set_Level( const char* tracing_level ); + + /************************************************************************** + * + * @function: + * FT_Trace_Set_Default_Level + * + * @description: + * 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. + * + */ FT_EXPORT( void ) FT_Trace_Set_Default_Level( void ); - /* An external callback function to be used to define an output handler */ + /************************************************************************** + * + * @functype: + * FT_Custom_Log_Handler + * + * @description: + * A function used to handle the logging of tracing and debug messages + * on a file system. + * + * @input: + * ft_component :: + * The name of `FT_COMPONENT' from which the current debug or error + * message is produced. + * + * fmt :: + * Actual debug or tracing message. + * + * args:: + * Arguments of debug or tracing messages. + * + */ typedef void - (*ft_custom_log_handler)( const char* ft_component, const char* fmt, + (*FT_Custom_Log_Handler)( const char* ft_component, const char* fmt, va_list args ); /************************************************************************** - * - * If FT_LOGGING is enabled user can provide their own function to handle - * the log messages using the function `FT_Set_Log_Handler()` by passing - * the function name which they want to use. - * User could also revert back to use FreeType's inbuilt function to - * handle logs using function `FT_Set_Default_Log_Handler()` - * Defined in src/base/ftdebug.c * - */ + * @function: + * FT_Set_Log_Handler + * + * @description: + * A function to set a custom log handler + * + * @input: + * + * handler :: + * New logging function + * + */ FT_EXPORT( void ) - FT_Set_Log_Handler( ft_custom_log_handler handler ); + FT_Set_Log_Handler( FT_Custom_Log_Handler handler ); + + + /************************************************************************** + * + * @function: + * FT_Set_Default_Log_Handler + * + * @description: + * If previously, `FT_Set_Log_Handler' functions is used to set new + * custom logging function, this API could be used to reset the back + * the log handler to FreeType's inbuilt log handler. + * + */ FT_EXPORT( void ) FT_Set_Default_Log_Handler( void ); diff --git a/include/freetype/internal/ftdebug.h b/include/freetype/internal/ftdebug.h index 96da630ad..2c9b41a57 100644 --- a/include/freetype/internal/ftdebug.h +++ b/include/freetype/internal/ftdebug.h @@ -388,7 +388,7 @@ ft_remove_tag( const char* tag ); * * These are defined in ftdebug.c */ - extern ft_custom_log_handler custom_output_handler; + extern FT_Custom_Log_Handler custom_output_handler; extern dlg_handler ft_default_log_handler; /************************************************************************** diff --git a/src/base/ftdebug.c b/src/base/ftdebug.c index 3e6b67a7f..68fb0394d 100644 --- a/src/base/ftdebug.c +++ b/src/base/ftdebug.c @@ -79,25 +79,9 @@ static bool ft_timestamp_flag = false; static bool ft_have_newline_char = true; - ft_custom_log_handler custom_output_handler = NULL; + FT_Custom_Log_Handler custom_output_handler = NULL; dlg_handler ft_default_log_handler = NULL; - /* different types of dlg features to be used according to the flags */ - /* passed in FT2_DEBUG environment variable */ - - static unsigned int features_component = dlg_output_threadsafe - | dlg_output_tags; - static unsigned int features_timestamp = dlg_output_threadsafe - | dlg_output_time - | dlg_output_time_msecs; - static unsigned int features_both = dlg_output_threadsafe - | dlg_output_time_msecs - |dlg_output_time - | dlg_output_tags ; - static unsigned int features_none = dlg_output_threadsafe; - - - #endif @@ -428,7 +412,7 @@ else { ft_default_log_handler = ft_log_handler; ft_default_trace_level = ft_getenv( "FT2_DEBUG" ); - ft_fileptr = fopen( "freetype2.log", "w" ); + ft_fileptr = fopen( ft_getenv( "FT_LOGGING_FILE" ), "w" ); ft_debug_init(); /* We need to set the default FreeType specific dlg's output handler */ @@ -452,19 +436,19 @@ else const char* string, void* data ) { ( void ) data; - static unsigned int features ; + const char* features ; if( ft_timestamp_flag && ft_component_flag && ft_have_newline_char ) - features = features_both; + features = "[%h:%m %t] %c"; else if( ft_component_flag && ft_have_newline_char) - features = features_component; + features = "[%t] %c"; else if( ft_timestamp_flag && ft_have_newline_char ) - features = features_timestamp; + features = "[%t] %c"; else - features = features_none; + features = "%c"; + + dlg_generic_outputf_stream( ft_fileptr, features, origin, string, + dlg_default_output_styles, true ); - - dlg_generic_output_stream( ft_fileptr, features, origin, string, - dlg_default_output_styles ); if( strchr( string, '\n' ) ) ft_have_newline_char = true; @@ -509,7 +493,7 @@ else */ FT_EXPORT_DEF( void ) - FT_Set_Log_Handler( ft_custom_log_handler handler ) + FT_Set_Log_Handler( FT_Custom_Log_Handler handler ) { custom_output_handler = handler; } diff --git a/submodules/dlg b/submodules/dlg index 407e385d2..a48976146 160000 --- a/submodules/dlg +++ b/submodules/dlg @@ -1 +1 @@ -Subproject commit 407e385d2e40e11a1f1643cdf698fd09d62561ca +Subproject commit a4897614699fb8e76f23a2d50a63b4d674e39f90