🪶 saydbg

A tiny, dependency-light macro crate for conditional debug printing — designed to give you
println!-style logging in debug builds, with optional color, timestamps, and file logging.
In release mode, all debug macros are completely compiled out (zero cost).

✨ Features

✅ Simple println!-style usage
✅ Works only in debug mode (cfg(debug_assertions))
✅ Optional colored output (--features color)
✅ Optional timestamps (--features timestamp)
✅ Optional file logging (--features file)
✅ Zero-cost in release builds
✅ MIT licensed — free for any project

📦 Installation

Add to your project’s Cargo.toml:

[dependencies]
saydbg = "0.2"

Optionally enable features:

[dependencies]
saydbg = { version = "0.2", features = ["color", "timestamp", "file"] }

🧠 Example

use saydbg::{saydbg, saywarn, sayerr, saytrace, saylog};

fn main() {
    saydbg!("Connected to database");
    saywarn!("Missing optional config file");
    saytrace!("Query took {:?} ms", 5);
    sayerr!("User not found: {}", "admin");
    saylog!("Server started successfully");
}

🧱 Default Output (Debug build)

[debug] Connected to database
[warn] Missing optional config file
[trace] Query took 5 ms
[error] User not found: admin
[log] Server started successfully

🌈 With --features color

Colors (blue, yellow, red, gray, green) are added for easy scanning.

🕒 With --features timestamp

[2025-10-08 12:11:47] [debug] Connected to database
[2025-10-08 12:11:47] [warn] Missing optional config file

⚙️ Macros

🚀 Why use saydbg?

Because sometimes you don’t need a full logger — just some conditional, colorful debug messages that disappear in release builds.

saydbg sits between:

• ✏️ println!() — simple but always prints
• 🧱 log or tracing — powerful but heavy for small tools

Perfect for:

• CLI utilities
• Tauri or WASM apps
• Embedded debugging
• Classroom or educational projects
• Quick prototypes or experiments

🔧 Feature Flags

Enable all for maximum clarity:

[dependencies]
saydbg = { version = "0.2", features = ["color", "timestamp", "file"] }

🗂️ File Logging (Optional Feature)

When compiled with the file feature, saydbg automatically mirrors all console output to a persistent log file (saydbg.log by default).

Enabling

Add the feature flag in your Cargo.toml:

[dependencies]
saydbg = { version = "0.2", features = ["file"] }

or on the command line:

cargo run --features "file"

Default Behavior

When enabled, each macro (e.g., saydbg!, saywarn!, sayerr!) appends its message to a file in the working directory:

saydbg.log

Example content:

[2025-10-09 11:32:17] [debug] Connected to database
[2025-10-09 11:32:18] [warn] User 'ryonb' not found in DB — inserting.

Manual Logging

You can also call the helper directly:

use saydbg::write_to_log_file;

write_to_log_file("[info] Manual entry from external system");

Thread Safety

saydbg uses a global, thread-safe file handle (via once_cell + Mutex) to avoid race conditions across threads or async tasks.

This means you can freely log from multiple tasks without worrying about file corruption or interleaving.

🧩 Example Project Integration

use saydbg::{saydbg, saywarn, sayerr};

pub fn connect_db() {
    saydbg!("Connecting to database...");
    // ...
    saywarn!("Connection is slow, retrying...");
    sayerr!("Database unreachable after retries");
}

All of these compile away completely in release:

cargo run --release
# (no debug output at all)

📜 License

Licensed under the MIT License.

💡 Author

Ryon Boswell — @crookedlungs
A developer and educator creating lightweight, modular tools for Rust and education.

🌟 Contributing

Pull requests, feature ideas, and improvements are welcome.
You can clone this repo, modify the macros, or submit suggestions on GitHub.

🦀 "Debug smart, release clean." — saydbg