"x.py doc --stage 0" fails with compiler-docs enabled

[tshepang]

Just bumped onto this with ./x.py doc, even after ./x.py clean:

error[E0460]: found possibly newer version of crate `std` which `synstructure` depends on                                                    
 --> src/librustc_macros/src/lib.rs:4:5                                                                                                      
  |                                                                                                                                          
4 | use synstructure::decl_derive;                                                                                                           
  |     ^^^^^^^^^^^^                                                                                                                         
  |                                                                                                                                                                                                                                                                                       
  = note: perhaps that crate needs to be recompiled?                                                                                                                                                                                                                                      
  = note: the following crate versions were found:                                                                                                                                                                                                                                        
          crate `std`: /home/tshepang/rust/build/x86_64-unknown-linux-gnu/stage0-sysroot/lib/rustlib/x86_64-unknown-linux-gnu/lib/libstd-95e90a1be2e66993.rlib                                                                                                                            
          crate `std`: /home/tshepang/rust/build/x86_64-unknown-linux-gnu/stage0-sysroot/lib/rustlib/x86_64-unknown-linux-gnu/lib/libstd-95e90a1be2e66993.so                                                                            
          crate `synstructure`: /home/tshepang/rust/build/x86_64-unknown-linux-gnu/stage0-rustc/release/deps/libsynstructure-7a0d29a374b01f60.rmeta

Here is my config.toml

[build]
compiler-docs = true
extended = true
tools = [ "clippy", "rustfmt", "rust-analyzer" ]
target = [ "wasm32-unknown-unknown" ]

[rust]
incremental = true

Originally posted by @tshepang in #59105 (comment)

[jyn514]

If you pass --stage 1 does it work? The default was recently changed to 0 so that might have uncovered a latent bug.

[tshepang]

@jyn514 that worked

[ehuss]

Fixing this properly looks like it will be quite tricky. Some of the complexity stems from the fact that the rustc wrapper does not set the sysroot without a --target flag, which is what happens when running cargo doc (see here). However, the rustdoc wrapper always sets the sysroot here. This means that dependencies that are built with rustc (for .rmeta) use the beta sysroot (stage0), and rustdoc is using the stage0-sysroot folder with the newly built std.

As an aside, if this is fixed to support stage0, this line will probably need to be changed to Std, not Rustc. There's no need to build Rustc to document itself.

[Mark-Simulacrum]

I suspect that rustdoc always setting the sysroot might in fact be a bug, or at least unintentional - it seems like the two should be the same probably?

[tshepang]

x.py doc --stage 1 does not work anymore

...
 Documenting std v0.0.0 (/home/tshepang/rust/library/std)          
error: unresolved link to `crate::os::unix::ffi::OsStrExt`                                                                                   
   --> library/std/src/ffi/mod.rs:134:22
    |                                                                                                                                        
134 | //! [unix.OsStrExt]: crate::os::unix::ffi::OsStrExt                                                                                    
    |                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ unresolved link
    |                                                                                                                                        
    = note: `-D broken-intra-doc-links` implied by `-D warnings`      
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
...

[jyn514]

What platform are you on? There might be some weird cfgs going on that weren't caught by CI for #75501. Feel free to make a PR reverting the links to ext, if you don't get around to it today I'll try to make a PR by the end of the week.

[tshepang]

I am on x86_64-unknown-linux-gnu, Debian unstable.

[jyn514]

Hmm, I can't reproduce locally and I have the same link in library/std. Not sure what's going on, I'm on x86_64-unknown-linux-gnu as well.

[jyn514]

This makes it seem like it should be independent of the platform:

rust/library/std/src/os/mod.rs

Lines 7 to 22 in 5b04bbf

	if #[cfg(doc)] {
	// When documenting libstd we want to show unix/windows/linux modules as
	// these are the "main modules" that are used across platforms. This
	// should help show platform-specific functionality in a hopefully
	// cross-platform way in the documentation
	#[stable(feature = "rust1", since = "1.0.0")]
	pub use crate::sys::unix_ext as unix;
	#[stable(feature = "rust1", since = "1.0.0")]
	pub use crate::sys::windows_ext as windows;
	#[doc(cfg(target_os = "linux"))]
	pub mod linux;
	} else {

rust/library/std/src/sys/mod.rs

Lines 60 to 82 in 5b04bbf

	#[cfg(doc)]
	cfg_if::cfg_if! {
	if #[cfg(unix)] {
	// On unix we'll document what's already available
	#[stable(feature = "rust1", since = "1.0.0")]
	pub use self::ext as unix_ext;
	} else if #[cfg(any(target_os = "cloudabi",
	target_os = "hermit",
	target_arch = "wasm32",
	all(target_vendor = "fortanix", target_env = "sgx")))] {
	// On CloudABI and wasm right now the module below doesn't compile
	// (missing things in `libc` which is empty) so just omit everything
	// with an empty module
	#[unstable(issue = "none", feature = "std_internals")]
	#[allow(missing_docs)]
	pub mod unix_ext {}
	} else {
	// On other platforms like Windows document the bare bones of unix
	use crate::os::linux as platform;
	#[path = "unix/ext/mod.rs"]
	pub mod unix_ext;
	}
	}

[tshepang]

Here is my config.toml, just in case that makes a difference

[build]
compiler-docs = true
extended = true
tools = [ "clippy", "rustfmt", "rust-analyzer" ]
target = [ "wasm32-unknown-unknown" ]

[rust]
incremental = true
lld = true