LazLogger: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		## Overview
2	2
3	3		The unit LazLogger is supplied with Lazarus and provides logging to file or console.
4	4
5	5		## Usage
6	6
7	7		### Adding logging support to your source code
8	8
9	9		By just including the unit lazlogger you can use the following:
10	10
11	11		- [[DebugLn]]: which works about the same as WriteLn.
12	12		- DebugLnEnter/DebugLnExit: same as debugln, but DebugLnEnter increases (and DebugLnExit decreases) the indentation of the written line.
13	13		- DbgOut: which works about the same as Write.
14	14
15	15		All of the above can be called with either:
16	16
17	17		- A single string, or list of (up to 15) strings: DebugLn('Foo'); DbgOut('a','b');
18	18		- An array of const: DebugLn(\['Foo=', 1, ' Bar=', anInteger\]);
19	19		- Same arguments as Format(). String + array of const: DbgOut('a %d',\[1\]);
20	20
21	21		Also there are many dbgs functions. Each converts a common type to a string for display. For example dbgs(aRect) converts a variable of type TRect to a string. You can write your own dbgs() functions for type conversions Lazarus does not provide, such as your custom records, which you can then use in DebugLn etc.
22	22
23	23		#### Activate/Deactivate LazLogger by using the correct unit
24	24
25	25		LazLogger provides 3 units for your "uses" clause
26	26
27	27		LazLogger
28	28		Use this unit in your main program only. Using this unit activates the functionality of LazLogger.
29	29
30	30		LazLoggerBase
31	31		Use this unit whenever you want to use DebugLn. What LazLoggerBase does depends on whether the unit LazLogger is used in any other unit of your application. If the LazLogger unit is not used, LazLoggerBase installs a "black hole" logger which discards all log messages. If LazLogger is used anywhere, then all units using LazLoggerBase will write the log messages as described under "Logging Output"
32	32
33	33		LazLoggerDummy
34	34		This unit provides you with dummy DebugLn calls (and all other LazLogger functions). They are just calls to empty methods. This allows you to disable all logging in a unit, without the need to remove any debugln statement.
35	35
36	36		### Logging output
37	37
38	38		#### Stdout/Console
39	39
40		-	By default the output created by `DebugLn` is written to the `stdout` device. The output is silently discarded if `stdout` is not open. On Windows this is the default behavior, if project type "Application" is used to create a Windows GUI application. To get a console alongside your Windows GUI application, you need to <b>uncheck</b> the option "Win32 gui application (-WG)" under Project options / Compiler options / Config and Target / Target specific options. Alternatively you can add {\$APPTYPE CONSOLE} at the top of your project .lpr file, or configure multiple "Build Modes" to control the -WG switch.
	40	+	By default the output created by `DebugLn` is written to the `stdout` device. The output is silently discarded if `stdout` is not open. On Windows this is the default behavior, if project type "Application" is used to create a Windows GUI application. To get a console alongside your Windows GUI application, you need to uncheck the option "Win32 gui application (-WG)" under Project options / Compiler options / Config and Target / Target specific options. Alternatively you can add {\$APPTYPE CONSOLE} at the top of your project .lpr file, or configure multiple "Build Modes" to control the -WG switch.
41	41
42	42		#### File
43	43
44	44		Debug output can also be written to file. The initialization code of the logging unit
45	45
46	46		- checks your program's command line parameters for --debug-log=\<file\> (In Lazarus: Run / Run Parameters / Command line parameters). On finding this parameter, any subsequent debug output is sent to \<file\>.
47	47
48	48
49	49		The param name can be changed with DebugLogger.ParamForLogFileName:='--debug-log'; This property exists only if the unit LazLogger is used. (LazLoggerBase does not define this property)
50	50
51	51		- If no '--debug-log' command line parameter has been given, it next checks if an operating system environment variable xxx_debuglog exists, where xxx is the program file name without extension. E.g. for Lazarus this would be lazarus_debuglog. If such an environment variable exists, it uses the file specified in that environment variable as file to receive debug output.
52	52
53	53		Example: if you do:
54	54
55	55		```dos
56	56		set lazarus_debuglog=c:\lazarus\debug.txt
57	57		```
58	58
59	59		and run Lazarus, debug output will be written to c:\lazarus\debug.txt.
60	60
61	61		#### Debug server
62	62
63	63		Not available in LazLogger; see [[DebugServer]].
64	64
65	65		### Log Groups
66	66
67	67		You can add log groups.
68	68
69	69		``` pascal
70	70		var MY_LOG_GROUP: PLazLoggerLogGroup;
71	71
72	72		initialization
73	73		MY_LOG_GROUP := DebugLogger.FindOrRegisterLogGroup('fancy_name_for_mylog' {$IFDEF MY_LOG_GROUP_ON_BY_DEFAULT} , True {$ENDIF} );
74	74		```
75	75
76	76		In your code use
77	77
78	78		``` pascal
79	79		debugln(MY_LOG_GROUP, 'log this text');
80	80		debugln(MY_LOG_GROUP, ['a=',a,' b=',b]); // a,b must be basic types: integer, byte, ansistring. See types available for "array of const"
81	81		```
82	82
83	83		and to enable it call your app with
84	84
85	85		```dos
86	86		--debug-enable=fancy_name_for_mylog
87	87		```
88	88
89	89		--debug-enable= takes a comma separated list
90	90
91	91		An already enabled group ( DebugLogger.FindOrRegisterLogGroup('grpname', True) ) can be disabled by specifying the group name with a minus.
92	92
93	93		```dos
94	94		--debug-enable=-fancy_name_for_mylog
95	95		```
96	96
97	97		The parameter name can be set via DebugLogger.ParamForEnabledLogGroups='--debug-enable';
98	98
99	99		## Documentation
100	100
101	101		For more features, see the unit itself and the LCL documentation.
102	102
103	103		Using LazLogger/LazLoggerBase your code can access the DebugLogger instance. This offers some properties to fine tune logging.
104	104
105	105		You can also write your own logger class and use it with LazLogger/Base.
106	106
107	107		## Multithreading
108	108
109	109		- DebugLn is thread safe, since Lazarus 2.0.
110	110
111	111
112	112		That is once the logger is created, see below
113	113
114	114		Earlier versions of this text stated "since 1.0", but a further race condition was found and fixed for 2.0.
115	115
116	116		- Calls to DbgOut, DebugLnEnter, DebugLnExit can be made from threads, but may not always format/indent the output correctly.
117	117
118	118		- The creation/setup/destruction/configuration of the logger is not thread-safe, and must be done before threads are started.
119	119
120	120
121	121		Creation is usually done with the first "debugln" call, maybe just debugln('') passing an empty string before any multi threaded code. Any other LazLogger access will also trigger creation and, once done, its done for the whole application.
122	122
123	123		But any properties (eg ParamForLogFileName) should be set before accessing the logger from threads.
124	124
125	125		- Callback to events like OnDebugLn are made in each thread. The code in the callback must be thread-safe by itself.
126	126
127	127
128	128		Changing the property is NOT thread-safe
129	129
130	130		## See also
131	131
132	132		- [[doc:fcl/eventlog/teventlog.html\|TEventLog documentation]] Built in support for logging in FPC/Lazarus
133	133		- [[DebugServer]] Allows sending log entries to a viewer via IPC
134	134		- [[MultiLog]]
135	135		- [[log4delphi]]
136	136		- The package IdeLazLogger, which adds a dialog to the IDE allowing to enable/disable log groups used in the IDE itself.
137	137
138	138		---
139	139		From the Free Pascal wiki, page "LazLogger", as it stood on 2024-05-26 after a change by Dbannon, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
140	140		Category: Debugging
141	141		Category: LCL
142	142		Category: Lazarus
143	143		Category: Logging

Back to history