ref: ab0ea068ee5acf6a6e1a77d5c315fb8934ce4190
parent: 6d9e6b21e5ca88b0b6dfa28ebcc86c99971bc60f
author: Priyesh Kumar <priyeshkkumar@gmail.com>
date: Fri Aug 28 07:28:17 EDT 2020
Update logging related documentation. * docs/DEBUG: Updates related to `FT_LOGGING`. * README.git: Updates related to logging.
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,13 @@
2020-11-30 Priyesh Kumar <priyeshkkumar@gmail.com>
+ Update logging related documentation.
+
+ * docs/DEBUG: Updates related to `FT_LOGGING`.
+
+ * README.git: Updates related to logging.
+
+2020-11-30 Priyesh Kumar <priyeshkkumar@gmail.com>
+
* src/*: Fix `-Wformat` warnings.
2020-11-30 Priyesh Kumar <priyeshkkumar@gmail.com>
--- a/README.git
+++ b/README.git
@@ -35,6 +35,14 @@
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
--- a/docs/DEBUG
+++ b/docs/DEBUG
@@ -44,7 +44,22 @@
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,7 +165,44 @@
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
This environment variable, when defined, tells FreeType to use a
@@ -200,6 +252,48 @@
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.
+
------------------------------------------------------------------------