[cargo doc] build.rs does not cover the use cases very well

[nagisa]

With docs.rs out, we’ve noticed a problem with cargo running build.rs scripts when documenting each crate, while it shouldn’t be necessary in majority of the cases.

Namely, most of the crates use build.rs scripts for one of these three large categories:

• Native library discovery (pkgconfig/etc);
• Building of dependencies written in other languages (gcc-rs/etc);
• Generating rust code (syntex/lalrpop/etc).

First and second use case will not influence the resulting documentation in meaningful ways, while the third use-case almost always will. First and second use-cases are target-dependent and may require cross-compilation toolchains, whereas the third use-case as well as documentation generation are obviously target-agnostic and can be done without any extra tooling or knowledge about the target platform.

It is counter-productive to not make any distinction between these cases. A project like docs.rs ideally shouldn’t need to install any native dependencies (see https://github.com/onur/docs.rs/issues/23) in order to generate documentation (because they are irrelevant for documentation generation purposes!)

There’s multiple ways one could proceed here:

• Introduce generate.rs, do not run build.rs scripts on cargo doc;
• Introduce extra keys to Cargo.toml (e.g. run_build_script_for_docs = false) defaulting to not running build.rs before generating documentation and making people using third use case specify that variable to true;
• The least breaking change would be to add a way in cargo API to not run build.rs scripts when building docs, so docs.rs could implement some sort of scheme itself (e.g. via [metadata] Cargo.toml section instructing docs.rs to run build.rs);
• etc.

cc @onur

[cuviper]

Build scripts can also output rustc-cfg features, which may affect the documentation.

[nagisa]

@cuviper I do not disagree, but as I already said, the influence is not meaningful. Those cfgs reflect the build environment of whatever is building your documentation and not the environment your user (the person reading documentation) has. This leads to essentially the same problem as showing linux documentation for a user on windows (resulting in empty/missing os modules etc).

In order to specify cfgs for docs.rs, I think one would end up using similar scheme as the one you’d use to specify features (https://github.com/onur/docs.rs/issues/29).

[alexcrichton]

Yeah it's true that build scripts are basically just large black boxes today, so I think it's correct for now to default to trying to run them to generate docs. I'd be up for exploring the space of more targeted build scripts for situations like this, but that's certainly RFC territory to be implemented.

[nagisa]

@alexcrichton what about

The least breaking change would be to add a way in cargo API to not run build.rs scripts when building docs, so docs.rs could implement some sort of scheme itself (e.g. via [metadata] Cargo.toml section instructing docs.rs to run build.rs);

[alexcrichton]

We could perhaps add a flag to cargo doc that doesn't run build scripts like that, yeah, but I don't think we could switch the default behavior to not running build scripts when building documentation.

[durka]

Can't the build script check $PROFILE and skip things that aren't relevant to docs?

[BusyJay]

Any progress on this issue?

[carols10cents]

This sounds like it might fall under eRFC 2136, Cargo build system integration.

[epage]

As far as I can tell, #8811 is a dupe of this but since it has more recent notes on direction, I'm closing this in favor of it.

If there is a reason we need this separate issue, let us know and we can revisit!