Question about performance impact on builds

[PhilipDaniels]

Does the macro get expanded when doing a standard cargo build? That would be a lot of processing for something that will be thrown away when producing a binary. Or, better, does it just run when using cargo doc?

[Andlon]

Unfortunately, yes. There is no way to only run macros in doc builds, as we can not reliably detect them. What you can do is hide things behind a feature flag. Note that his is also less than ideal, because when building docs that depend on the crate, the feature flag won't be propagated, so then docs won't work correctly when building something that depends on your crate. For example:

// In Cargo.toml
[features]
doc-images = [ "embed-doc-image" ]

[dependencies]
embed-doc-image = { version="0.1.4", optional = true }

#![cfg_attr(feature = "doc-images",
    cfg_attr(all(),
        doc = ::embed_doc_image::embed_image!("figure", "assets/figure.svg")))],
#![cfg_attr(
    not(feature = "doc-images"),
    doc = "**Doc images not enabled**. Compile with feature `doc-images` and Rust version >= 1.54 \
           to enable."
)]

This is a little complicated, however. If you don't need to support Rust versions before 1.54 you can simplify it a little. To facilitate this kind of stuff, I've been meaning to change embed-doc-image and add an enable feature (perhaps disabled by default) so that you could just do (for Rust >= 1.54)

[features]
doc-images = [ "embed-doc-image/enable" ]

#![cfg_attr(feature = "doc-images", doc = embed_image!("figure", "assets/figure.svg"))],

That does mean that you'll have to run cargo doc with --features doc-images though.

Unfortunately, I'm very busy and this stuff is very low on my list of priorities, so I don't expect to get around to it anytime soon...

[PhilipDaniels]

Thanks for the info. When you say 'we can not reliably detect them' is that recent knowledge or is there a possibility it is dated now? The last commit was 11 months ago, which is quite a long time. I am wondering if it is worthwhile me doing some asking around as research for a future PR, that's all.

[Andlon]

I investigated this again quite recently, and indeed that is the current state. There's some relevant discussion in this issue.