[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.
This commit is contained in:
Priyeshkkumar
parent
968d484cc0
commit
526d973e31
|
|
@ -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
|
||||
|
|
|
|||
132
docs/DEBUG
132
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<freetype/ftlogging.h>
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
Copyright (C) 2002-2020 by
|
||||
|
|
|
|||
|
|
@ -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++ )
|
||||
|
|
|
|||
Loading…
Reference in New Issue