Repository: rust
Issue: rustdoc: follow-up work for `--emit=toolchain-shared-resources`
Labels: T-rustdoc,C-tracking-issue,requires-nightly,T-docs-rs,S-tracking-perma-unstable,A-CLI

<!--
Thank you for creating a tracking issue! 📜 Tracking issues are for tracking a
feature from implementation to stabilisation. Make sure to include the relevant
RFC for the feature if it has one. Otherwise provide a short summary of the
feature and link any relevant PRs or issues, and remove any sections that are
not relevant to the feature.

Remember to add team labels to the tracking issue.
For a language team feature, this would e.g., be `T-lang`.
Such a feature should also be labeled with e.g., `F-my_feature`.
This label is used to associate issues (e.g., bugs and design questions) to the feature.
-->

This is a tracking issue for the unstable feature `--emit=toolchain-shared-resources`, which requires `-Z unstable-options`. This feature is not meant to ever be stabilized; it's used by docs.rs to avoid copying the same files for each crate. Users other than docs.rs are not supported.

### Unresolved Questions

- Can we get rid of `unversioned-shared-resources` completely? It's unclear what the difference between a versioned and unversioned resource is; I don't know if rustdoc can promise its files will *never* change even across toolchains.
- `main.js` is currently marked as a toolchain resource, which is wrong if the user passes `--theme` in RUSTDOCFLAGS.

### Implementation history

- [x] Initial implementation: https://github.com/rust-lang/rust/pull/83478
- [x] Use in docs.rs https://github.com/rust-lang/docs.rs/pull/1340
- [x] Remove `--print=unversioned-files`: https://github.com/rust-lang/rust/pull/85770

<h3 id="why-does-this-feature-exist">Why does this feature exist?</h3>

Docs.rs has been having quite a lot of trouble with essential files. Here are the recent developments:

1. rustdoc added a new crates.js file a few weeks ago, breaking search for all newly built crates https://github.com/rust-lang/docs.rs/issues/1300
2. dtolnay added crates.js and also some other essential files that were missing https://github.com/rust-lang/docs.rs/pull/1301
3. It turned out the other essential files had a typo, breaking all builds https://github.com/rust-lang/docs.rs/issues/1305. the typo was fixed by https://github.com/rust-lang/docs.rs/pull/1308
4. rustdoc wanted to start adding *more* essential files (https://github.com/rust-lang/rust/pull/82732, https://github.com/rust-lang/rust/pull/80705) and I got fed up of dealing with it so I opened https://github.com/rust-lang/docs.rs/pull/1312
5. rust-lang/docs.rs#1312 had a bug (https://github.com/rust-lang/docs.rs/pull/1312#issuecomment-803616354) if we copy more files than necessary. I opened https://github.com/rust-lang/docs.rs/pull/1324 giving precedence to local shared files over global ones which avoids the bug.
6. https://github.com/rust-lang/docs.rs/pull/1324 broke docs that weren't using `--extern-html-root-url` (https://github.com/rust-lang/docs.rs/issues/1327#issuecomment-804447887). The tracking issue for rebuilding those is https://github.com/rust-lang/docs.rs/issues/1181.

In summary, docs.rs can't copy fewer shared files than rustdoc generates, and due to 2 months of broken builds about 3 years ago, it also can't copy *more*. So there has to be a way to know exactly which files should be shared and which shouldn't.