20. Logging

Simply use CastleLog unit and call InitializeLog to have logging enabled.

  • On Unix (Linux, Mac OS X...), and on Windows console applications, logging by default goes to the standard error output. This is called StdErr, also known as ErrOutput in Pascal. This is the standard behaviour for Unix and console apps. The nice thing about it is that it avoids users asking questions "where is the log file" — because they choose the name and location of the log file themselves.

  • On Windows GUI applications we log to the file xxx.log in the current directory (where xxx is your ApplicationName).

  • On Windows GUI libraries (like NPAPI plugins) we log to the file xxx.log in the user's private directory (where xxx is your ApplicationName). User's private directory is determined by standard FPC functions, that in turn use standard Windows functions, it's something like c:/Documents and Settings/USERNAME/Local settings/Application Data/xxx/xxx.log or c:/c:/Users/USERNAME/AppData/Local/xxx/xxx.log depending on your Windows version.

  • You can pass a parameter to InitializeLog to generate log to any stream.

A lot of engine components automatically use this log. To use it yourself, just call WritelnLog (or one of it's friends, see CastleLog unit).

To summarize:

uses ..., CastleLog;
... // place this in your initialization:
InitializeLog('1.0.0'); // parameter describes program version, will be logged
... // then use this wherever you want:
WritelnLog('My Category', 'My Log Message');

'My Category' is useful to easily spot your messages later. There are no hard rules about it, so you're free to just invent your own category names here, whatever works for you.