Stream: rustdoc

Topic: rustdoc uses `debug` deps


view this post on Zulip Gus Wynn (Sep 01 2021 at 22:36):

I was trying to build a series of crates where there were disjoint features (I know, but it was for async runtimes), and i was trying to use --cgf=docsrs instead of features to ALWAYS show a special method used only by one of the runtimes, but when the downstream crate was building docs, it kept saying that couldnt find that method

with some -vv digging, it looks like the rustdoc invocations linked against the debug builds of the deps, not the doc builds, is this expected?

view this post on Zulip Joshua Nelson (Sep 01 2021 at 22:47):

What do you mean by debug builds? Rustdoc reuses the same cache as cargo check

view this post on Zulip Joshua Nelson (Sep 01 2021 at 22:47):

Are you expecting cfg(doc) to be set for dependencies? It's not

view this post on Zulip Joshua Nelson (Sep 01 2021 at 22:48):

--cfg=docsrs needs to be set for both RUSTFLAGS and RUSTDOCFLAGS if you want it to be set for dependencies

view this post on Zulip Joshua Nelson (Sep 01 2021 at 22:49):

(maybe a simpler way to say those three things is "rustdoc can't generate metadata")

view this post on Zulip Gus Wynn (Sep 01 2021 at 22:51):

I was building all the crates inside a single workplace, so I was expecting things to be the same, but i see now that it doesnt generate metadata

another interesting "consequence" of this was that #[cfg_attr(docrs, doc(...))] attributes were not being forward

I think the RUSTFLAGS would fix that, but in this case it would require I alter the [package.metadata.docs.rs]to also include `rustc-args = ["--cfg=docsrs"]

view this post on Zulip Gus Wynn (Sep 01 2021 at 22:51):

interesting, ill mention to the sqlx people that I can clean up the feature soup I needed with RUSTFLAGS instead, if thats what they want

view this post on Zulip Gus Wynn (Sep 01 2021 at 22:52):

Thanks for explaining!

view this post on Zulip Gus Wynn (Sep 01 2021 at 22:52):

I may link to this zulip stream on the PR

view this post on Zulip Joshua Nelson (Sep 01 2021 at 22:52):

Sure, feel free

view this post on Zulip Gus Wynn (Sep 01 2021 at 22:55):

so in a workplace, if you cargo doc that root, each dep is built twice?

view this post on Zulip Joshua Nelson (Sep 01 2021 at 22:55):

Only if a later crate depends on it

view this post on Zulip Joshua Nelson (Sep 01 2021 at 22:55):

cargo doc -p my_crate doesn't require that you first run cargo check -p my_crate

view this post on Zulip Joshua Nelson (Sep 01 2021 at 22:57):

Joshua Nelson said:

(maybe a simpler way to say those three things is "rustdoc can't generate metadata")

so more accurately: rustdoc doesn't serialize metadata

view this post on Zulip Noah Lev (Sep 01 2021 at 22:59):

Joshua Nelson said:

cargo doc -p my_crate doesn't require that you first run cargo check -p my_crate

That's because rustdoc basically runs cargo check, right?

view this post on Zulip Joshua Nelson (Sep 01 2021 at 23:00):

Essentially, yes. It doesn't type check function bodies.

view this post on Zulip Noah Lev (Sep 01 2021 at 23:00):

Well, it sometimes does. nvm, was thinking of something else

view this post on Zulip Joshua Nelson (Sep 01 2021 at 23:00):

And there are a bunch of other checks it omits too

view this post on Zulip Gus Wynn (Sep 01 2021 at 23:02):

Joshua Nelson said:

Only if a later crate depends on it

ah so in the sqlx case, there is a tree of crates depending on each other, so the non-root crates will all be built in debug mode and doc mode

view this post on Zulip Gus Wynn (Sep 01 2021 at 23:03):

ah thats why the cargo output has "Checking" AND "Documenting"


Last updated: Oct 11 2021 at 22:34 UTC