Add logging to facilitate debugging about mdbook

[kbknapp]

A way I've gone about this is to add a cargo feature (I usually name it "debug") and create a macro which prints debugging output, but when compiled without the "debug" feature it does nothing and gets optimized away.

i.e.

# in Cargo.toml
[features]
debug = []

// In lib.rs
#[cfg(feature = "debug")]
macro_rules! debug {
    ($fmt:expr) => (println!(concat!("**DEBUG** ", $fmt)));
    ($fmt:expr, $($arg:tt)*) => (println!(concat!("**DEBUG** ",$fmt), $($arg)*));
}

#[cfg(not(feature = "debug"))]
macro_rules! debug {
    ($fmt:expr) => ();
    ($fmt:expr, $($arg:tt)*) => ();
}

Then throughout your code:

// In some source file...
fn my_function() {
    debug!("Just entered my_function");
    let a = 20;
    debug!("A = {}", a);
}

Now when compiled with cargo build --features "debug" you will see these debug messages printed to stdout, but when compiled normally, nothing.

I like how it works, because it's easy to tell a user, "Recompile with --features "debug" and send me the output"

[azerupi]

Seems like a pretty good idea.
I have never used macros, but they seem pretty powerful. Maybe I should learn how to use them properly.

Also since I want to make mdBook available as a crate for others to use, is there a way for them to enable / disable output without having to pass an argument to the called functions? Something similar to fn function(..., print: bool) in functionality. Maybe there is some rust / cargo magic that can be used for this? 😉

[kbknapp]

Yep! If you use the method described above users of mdbook as a library
simply change their Cargo.toml to enable/disable debugging output.

For example, no debugging info:

[dependencies.mdbook]
version = "*"

Or if they want debugging info:

[dependencies.mdbook]
version = "*"
features = ["debug"]

They could also do the same thing inline with the regular dependencies

[dependencies]
mdbook = { version = "*", features = ["debug"] }

[azerupi]

Nice! I will take a look into that. It looks a lot cleaner than passing an argument :)

[azerupi]

@kbknapp I am trying to implement this but I get an error when compiling with the debug feature.

I have made a macros.rs file containing

#[cfg(feature = "debug")]
#[macro_export]
macro_rules! debug {
    ($fmt:expr) => (println!($fmt));
    ($fmt:expr, $($arg:tt)*) => (println!($fmt, $($arg)*));
}

#[cfg(not(feature = "debug"))]
#[macro_export]
macro_rules! debug {
    ($fmt:expr) => ();
    ($fmt:expr, $($arg:tt)*) => ();
}

But when compiling I get this error:

<std macros>:1:33: 1:58 error: invalid reference to argument `0` (no arguments given)
<std macros>:1 ( $ fmt : expr ) => ( print ! ( concat ! ( $ fmt , "\n" ) ) ) ; (
                                               ^~~~~~~~~~~~~~~~~~~~~~~~~
note: in expansion of format_args!
<std macros>:2:25: 2:56 note: expansion site
<std macros>:1:1: 2:62 note: in expansion of print!
<std macros>:1:23: 1:60 note: expansion site
<std macros>:1:1: 3:58 note: in expansion of println!
src/macros.rs:4:21: 4:35 note: expansion site
src/macros.rs:3:1: 6:2 note: in expansion of debug!
src/parse/summary.rs:73:9: 73:100 note: expansion site
error: aborting due to previous error
Could not compile `mdbook`.

Have you any idea why?

[kbknapp]

Could you commit what you've got to a separate branch and push it? I'd need to see the whole macros.rs and src/parse/summary.rs to see what the issue is.

Also, you don't need the #[macro_export] unless you want consumers of the mdbook library to use debug!() which isn't required even if they compile with features = ["debug"]

[azerupi]

I will push to master since it does not prevent compiling without the feature. Thanks for looking :)

[azerupi]

I'd need to see the whole macros.rs and src/parse/summary.rs to see what the issue is.

Ow I didn't even notice that it was telling me to look at src/parse/summary.rs I found the issue now. I feel a little bit ashamed for not catching that 😊 ..

Thanks for the help! :)

[kbknapp]

No worries :)