LazLogger

From Free Pascal wiki
Jump to: navigation, search

Overview

The unit LazLogger is supplied with Lazarus and provides logging to file.

It is not thread safe. For logging with multithreaded applications see below.

Usage

Adding logging support to your source code

(For historical reasons some parts are also accessible through LclProc; this access might be removed in future)

By just including the unit lazlogger you can use the following:

  • DebugLn: which works about the same as WriteLn.
  • DebugLnEnter/DebugLnExit: same as debugln, but increase/decrease indent.
  • DbgOut: which works about the same as Write.

All of them can be called with either:

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

Tip: use LazLoggerDummy in your uses clause if you want to disable all logging but don't want to have to change all your code.

Logging output

Stdout

In normal circumstances, the output is written to stdout. No output is written if stdout is closed - for example when the application is {$AppType Gui}, or compiled with -WG on Windows (see Compiler options / Linking / Target OS specific options).

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

Example: if you do:

set lazarus_debuglog=c:\lazarus\debug.txt

and run Lazarus, debug output will be written to c:\lazarus\debug.txt.

Debug server

Not available in LazLogger; see DebugServer.

Documentation

For more features, see the unit itself and the LCL documentation.

Multithreading

debugln is not thread safe. Solutions:

  • A thread can use Synchronize to use debugln via the main thread.
  • Use DbgOutThreadLog to write the message to file 'Log'+IntToStr(GetThreadID).

See also