📝 SimpleLog-FP

Note

SimpleLog-FP is currently in active development. This is a pre-1.0 release (v0.9.0). The API may change and feedback is welcome!

A simple, lightweight, and easy-to-use logging library for Free Pascal applications.

Why SimpleLog-FP? 🤔 Built from the need for a logging library that is actually simple to use and maintain. No feature bloat, no complexity - just clean, reliable logging for console, file, or both.

🎯 Design Philosophy

• ✅ Simple - Easy for new developers to understand and use
• ✅ Lightweight - ~460 lines of code, no bloat
• ✅ Maintainable - Clean code and easily maintainable
• ✅ Focused - Does three things well: console, file, and console+file logging
• ✅ No dependencies - Uses only standard Free Pascal units
• ✅ Cross-platform - Works on Windows and Unix systems
• ✅ File rotation - Automatic log file rotation when size limits are reached

🚀 Quick Start

📦 Installation

From GitHub:

git clone https://github.com/ikelaiah/simplelog-fp.git
cd simplelog-fp

Manual Installation:

1. Download src/SimpleLog.pas from this repository
2. Copy it to your project directory
3. Add SimpleLog to your uses clause
4. Start logging!

Basic Usage

uses SimpleLog;

var
  Log: TSimpleLog;
begin
  // Console only
  Log := TSimpleLog.Console;
  Log.Info('Hello World!');
  
  // File only  
  Log := TSimpleLog.FileLog('app.log');
  Log.Info('Logged to file');
  
  // Both console and file
  Log := TSimpleLog.Both('app.log');
  Log.Info('Appears in both console and file');
end;

That's it! No complex setup, no memory management, no configuration files required.

For a short walkthrough, see Getting Started.

✨ Features

📝 Core Logging

• 5 log levels: Debug, Info, Warning, Error, Fatal
• Timestamped messages: Each log entry includes precise timestamp with milliseconds
• Optional colored console output with appropriate colors per level
• File logging with automatic directory creation
• Dual output to both console and file simultaneously
• Format string support for all log methods
• Thread safety - logging operations are serialized for multi-threaded applications
• Silent mode to temporarily disable all logging output

Log Output Format

All log messages follow a consistent, readable format:

[2025-07-01 14:30:22.123] [INFO] Application started
[2025-07-01 14:30:22.456] [WARNING] Low disk space: 15.5% remaining
[2025-07-01 14:30:22.789] [ERROR] Database connection failed
[2025-07-01 14:30:23.012] [DEBUG] User authentication successful
[2025-07-01 14:30:23.345] [FATAL] Critical system error

Timestamp format: yyyy-mm-dd hh:nn:ss.zzz

• ISO 8601 compatible date format (sortable)
• 24-hour time format
• Millisecond precision for performance analysis
• Consistent across console and file output

⚙️ Configuration

• Method chaining for fluent configuration
• Log level filtering - set minimum level to reduce noise
• File rotation - automatic rotation when files exceed size limit
• Custom file paths with automatic directory creation
• Color control - disable console colors for plain terminal output

🌍 Cross-Platform

• Windows: Console colors via Windows API
• Unix/Linux: Console colors via ANSI escape codes
• Consistent behavior across platforms

📚 API Reference

🏭 Factory Methods

TSimpleLog.Console              // Console output only
TSimpleLog.FileLog('file.log')  // File output only  
TSimpleLog.Both('file.log')     // Both console and file

🔊 Logging Methods

Log.Debug('Debug message');
Log.Info('Information');
Log.Warning('Warning message');
Log.Error('Error occurred');
Log.Fatal('Critical error');

// Format string variants
Log.Info('User %s has %d items', [username, count]);
Log.Error('Connection failed: %s:%d', [host, port]);

⛓️ Configuration (Method Chaining)

Log := TSimpleLog.Console
  .SetMinLevel(llWarning)           // Only warnings and above
  .SetOutputs([odConsole, odFile])  // Enable both outputs
  .SetFile('app.log')               // Set log file
  .SetMaxFileSize(5 * 1024 * 1024)  // 5MB rotation limit
  .SetSilent(False)                 // Enable/disable all logging
  .SetUseColors(True);              // Enable/disable console colors

🔧 Read-Only Properties

WriteLn(Log.LogFile);                // Current log file path
WriteLn(Ord(Log.MinLevel));          // Current minimum log level
WriteLn(Log.MaxFileSize);            // Current rotation size
WriteLn(Log.Silent);                 // Current silent mode
WriteLn(Log.UseColors);              // Current console color mode

Use the Set... methods for configuration. This keeps validation in one place and avoids direct property writes bypassing rules such as the minimum rotation size.

📋 Examples

🌟 Real-World Usage Example

program MyApplication;
uses SimpleLog;

var
  Log: TSimpleLog;
  UserCount: Integer;
begin
  // Initialize logging to both console and file
  Log := TSimpleLog.Both('application.log')
    .SetMinLevel(llInfo);  // Hide debug messages in production
  
  Log.Info('Application starting up');
  
  try
    // Your application logic
    UserCount := LoadUsers();
    Log.Info('Loaded %d users from database', [UserCount]);
    
    if UserCount = 0 then
      Log.Warning('No users found in database');
      
  except
    on E: Exception do
    begin
      Log.Error('Startup failed: %s', [E.Message]);
      ExitCode := 1;
      Exit;
    end;
  end;
  
  Log.Info('Application ready');
  
  // Your main application loop here...
  
  Log.Info('Application shutting down');
end;

🔍 Level Filtering

// Production: Only show warnings and errors
Log := TSimpleLog.Both('prod.log').SetMinLevel(llWarning);

// Development: Show everything including debug
Log := TSimpleLog.Console.SetMinLevel(llDebug);

🔄 File Rotation

// Rotate when file exceeds 1MB
Log := TSimpleLog.FileLog('big.log').SetMaxFileSize(1024 * 1024);
Log.Info('This will rotate when file gets too big');
// Rotation keeps one bounded backup: big.log.1

🔇 Silent Mode

// Temporarily disable all logging
Log := Log.SetSilent(True);
Log.Error('This error will not appear anywhere');

// Re-enable logging
Log := Log.SetSilent(False);
Log.Info('Logging is back on');

🎨 Plain Console Output

// Useful for redirected output, CI logs, or terminals without color support
Log := TSimpleLog.Console.SetUseColors(False);
Log.Info('No color control codes are written');

🧵 Thread Safety

// Logging operations and individual configuration methods are serialized internally.
// Configure the logger before sharing it between threads for predictable behavior.
var
  Log: TSimpleLog;
begin
  Log := TSimpleLog.Both('threaded.log');
  // Use Log from multiple threads with confidence
  Log.Info('Multi-threaded logging works reliably');
end;

💯 Advanced Record Benefits

SimpleLog uses Free Pascal's advanced records instead of classes:

• ✅ No memory management - no Create/Free needed
• ✅ Stack allocated - automatic cleanup
• ✅ Lightweight - minimal overhead
• ✅ Value semantics - can be copied safely
• ✅ Modern Pascal - leverages language features

📁 File Structure

SimpleLog-FP/
├── src/
│   └── SimpleLog.pas          # Main library (~460 lines)
├── examples/
│   ├── SimpleLogExample/      # Basic usage examples
│   └── ThreadSafeExample/     # Concurrent logging demo
├── tests/
│   └── SimpleLog.Test.pas     # Comprehensive test suite
├── docs/
│   ├── getting-started.md     # Short first-use guide
│   ├── SimpleLogger.md        # User manual
│   ├── cheat-sheet.md         # Quick API reference
│   └── release-checklist.md   # Maintainer release checklist
└── README.md                  # This file

🧪 Tests

A comprehensive test suite is provided in the tests/ directory. To run the tests:

• Build the Lazarus test runner:

  lazbuild tests/TestRunner.lpi

• Run the full suite:

  tests/TestRunner.exe --all --format=plainnotiming

• CI also builds and runs the test suite with Lazarus on Windows and plain FPC on Ubuntu.

📦 Lazarus Package

A ready-to-use Lazarus package is included for easy integration:

• Open packages/lazarus/simplelog.lpk in the Lazarus IDE
• Click "Use" → "Add to Project" to add SimpleLog-FP to your project
• The package will automatically add the correct search paths

This is the recommended way to add SimpleLog-FP to your Lazarus projects for the best experience.

📊 Comparison with Complex Logging Libraries

Feature	SimpleLog-FP	Complex Logger
Lines of code	~460	2000+
Learning curve	Minutes	Hours
Features	3 core outputs	20+ features
Maintenance	Easy	Complex
Memory usage	Minimal	Higher
Dependencies	None	Multiple

🤝 Contributing

Keep it simple! Any contributions should maintain the core philosophy:

• No feature bloat
• Easy to understand
• Focused on core logging needs

⚖️ License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Free Pascal Dev Team for the Pascal compiler
• Lazarus IDE Team for such an amazing IDE
• The kind and helpful individuals on various online platforms such as:
  • Unofficial Free Pascal discord server
  • Free Pascal & Lazarus forum
  • Tweaking4All Delphi, Lazarus, Free Pascal forum
  • Laz Planet - Blogspot / Laz Planet - GitLab
  • Delphi Basics
  • @gcarreno for various suggestions and improvements
• All contributors who have helped improve this project