Reference for unit 'LazLoggerBase'

Defines base logging classes used in the Lazarus IDE.

Overview

lazloggerbase.pas contains classes, types, and routines used to implement the base logging mechanisms used in the Lazarus IDE. Its primary usage, when used along with the LazLogger unit, is to provide output to the debugger in the Lazarus IDE.

Logger classes (and routines) are found in units like:

LazLoggerBase.pas

Provides the base TLazLogger class used as the common ancestor for other logger classes. Use this unit when you want to use the debugln routine. What LazLoggerBase does depends on whether the unit LazLogger is used in any other unit of your application. If LazLogger is not used, LazLoggerBase will install a "blackhole logger" that discards all log messages. If LazLogger is used anywhere, then all units using LazLoggerBase will write the log messages as described under "Logging Output"

LazLogger.pas

Provides a logger class which writes output to a file or file handle. Use this unit to activate the functionality of LazLogger.

LazLoggerProfiling.pas

Provides a logger class which captures memory usage and execution times.

LazLoggerDummy.pas

Re-implements the logger class methods with empty implementations. They are just calls to empty methods. This allows you to disable logging in a unit without the need to remove debugln statements.

The LazLoggerIntf.inc include file contains interface declarations for routines and operators which should be implemented in each of the units for the various loggers.

Usage

Add one of the logger classes to your application to enable output of logging messages to the destination supported in the logger class. By using the LazLogger unit, the following are enabled:

• A single string, or list of (up to 15) strings: DebugLn('Foo'); DbgOut('a','b');
• An array of const: DebugLn(['Foo=', 1, ' Bar=', anInteger]);
• Same arguments as Format(). String + array of const: DbgOut('a %d',[1]);

Also there are tons of dbgs functions that converts common types to a string. For example dbgs(aRect) converts a variable of type TRect to a string.

Logger output

Stdout/Console

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.

File

Debug output can also be written to file. The initialization code of the logging unit 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>.

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).

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.

Multithreading

DebugLn is thread safe, since Lazarus 2.0. Earlier versions of this text stated "since 1.0", but a further race condition was found and fixed for 2.0.

Calls to DbgOut, DebugLnEnter, DebugLnExit can be made from threads, but may not always format/indent the output correctly.

The creation/setup/destruction/configuration of the logger is not thread-safe, and should be done before threads are started. Creation is usually done automatically during unit initialization. But any properties (eg ParamForLogFileName) should be set before accessing the logger from threads.

Callback to events like OnDebugLn are made in each thread. The code in the callback must be thread save by itself. Changing the routine assigned to the property is NOT thread-safe.

lazloggerbase.pas is part of the LazUtils package.