Logging

Usage

Use CastleLog unit and call InitializeLog to have logging enabled. Call WritelnLog or WritelnWarning to log stuff.

Some engine functions also automatically write to this log. For example, initializing the OpenGL context logs the OpenGL and GPU features detected.

An example:
Deprecated: Function create_function() is deprecated in /var/www/cge-www-preview/geshi/geshi.php on line 4751

{$ifdef MSWINDOWS} {$apptype GUI} {$endif}
 
uses CastleLog, CastleWindow, CastleColors, CastleControls;
var
  Window: TCastleWindowBase;
  Lab: TCastleLabel;
begin
  InitializeLog;
 
  WritelnLog('My Log Message');
  WritelnLog('My Category', 'My Log Message');
  WritelnWarning('My Warning');
 
  // display the LogOutput value in a window
  Window := TCastleWindowBase.Create(Application);
 
  Lab := TCastleLabel.Create(Application);
  Lab.Caption := 'Logging to ' + LogOutput;
  Lab.Color := White;
  Window.Controls.InsertFront(Lab);
 
  Window.Open;
  Application.Run;
end.

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

Where is the log stored?

  • When running from CGE editor, the log is displayed in the bottom editor panel.

  • On Unix (Linux, macOS...), and on Windows console applications, logging by default goes to the standard output. This is the standard behaviour for Unix and console apps.

    Users can redirect it by running the application from the command-line like my_game > log_file.log. The nice thing about it is that it avoids users asking questions "where is the log file".

  • On Windows GUI applications we log to the file in the user config directory. The file name looks like C:\Users\<user-name>\AppData\Local\<application-name>\<application-name>.log.

    The exact logic to determine the user config directory follows FPC GetAppConfigDir, which in turn asks the Windows API function, so it may be a little different from system to system.

    You can display the LogOutput value to show user on screen where is the log file.

  • On Android the log goes to the standard device log. It that can be viewed using various Android tools, like adb logcat.

  • On iOS, Nintendo Switch it goes to the standard log facility for these devices.

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

    You can also set LogFileName variable before calling the InitializeLog. This way you force using specific filename for logging, overriding the OS-specific auto-detection mechanism described above.

    User can also call the application with --log-file=c:/tmp/my_log_name.txt command-line option to set the location (and filename) explicitly. In fact, this way user sets the LogFileName variable. It will work if you call in your main program file Application.ParseStandardParameters;.