A potential issue I just thought of is that the 'search for cfg()' solution doesn't account for build scripts, you'd have to first run the build script, and only then search for cfgs. Is there a way to build only the build.rs without building any dependencies? If not, that sort of defeats the point ... maybe we could fallback to always building all targets if a build.rs exists?
An alternative to just not handling buildscripts would be to check for the rustc-cfg string in the build script to see just if it's setting any nonstandard cfg and back out to the more conservative behavior again.
The point here only needs to be to do the correct thing for simple cases, as crates doing more complicated things can always set the docs-rs metadata manually to get the specific behavior.
An alternative to just not handling buildscripts would be to check for the
rustc-cfgstring in the build script to see just if it's setting any nonstandard cfg and back out to the more conservative behavior again.
build.rs can also generate whole .rs files out of cloth; see for example https://github.com/bytecodealliance/target-lexicon/blob/main/build.rs#L85, which does have target-specific behavior. So it's not enough to see if they set a cfg, we also need to know what files they're writing to $OUT_DIR.
The point here only needs to be to do the correct thing for simple cases, as crates doing more complicated things can always set the docs-rs metadata manually to get the specific behavior.
Sure, I'm all in favor of only covering the simple cases. My worry is that we'll have inconsistent behavior where people can't predict what targets will be built - it's better to overshoot and build too many than too few.
Ah, right, actual codegen.
I'd personally start with looking for include! macro usage to see if the crate uses codegen and then just reset to the conservative behavior then. The other possible behavior would be just to do the scrape after the default target build and scrape $OUT_DIR as well.
It's definitely also worth mentioning that macros can "obfuscate" a #[cfg] so it wouldn't be found by the scrape. Thankfully, the big cfg macro, cfg_if!, is caught by the scrape, but other macros easily might not contain the literal #[cfg syntax that the scrape is looking for.
I'm sort of brainstorming from the direction of docs really wants to build only one platform by default, and any smarts beyond that are attempts to make the behavior more likely to generate docs for the meaningful targets.
The docs infra would prefer to underestimate the required targets, the empathy towards users would prefer to overestimate the required targets.
The only "safe" behavior is to continue cross-documenting all tier-1 targets; any other solution is going to miss some edge cases (fairly trivially true due to halting problem for the build script). So it feels to me like the only "good" solution is to drop the default number of builds and have some small number of fairly simple rules as to when tier-1 doc builds for other targets are implicitly enabled.
Platform detection doesn't have to be 100% accurate, just better than doing nothing. I think it's fine to have a heuristic. Even a simple grep over all .rs files could be useful.
You could also look at dependencies to detect supported platforms, e.g. if a crate depends on winapi directly, try building for Windows.
This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.