Commit ab0ea068ee5acf6a6e1a77d5c315fb8934ce4190
2020-08-28T11:28:17
Update logging related documentation. * docs/DEBUG: Updates related to `FT_LOGGING`. * README.git: Updates related to logging.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156
diff --git a/ChangeLog b/ChangeLog
index 5d6ac07..fb6da40 100644
--- 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>
diff --git a/README.git b/README.git
index c4f0033..1da3fa8 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 a96b5e2..48bea34 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