Introduce infrastructure for generating target docs

Cargo.lock

@@ -5057,6 +5057,19 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "serde_yaml"
+version = "0.9.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "adf8a49373e98a4c5f0ceb5d05aa7c648d75f63774981ed95b7c7443bbd50c6e"
+dependencies = [
+ "indexmap",
+ "itoa",
+ "ryu",
+ "serde",
+ "unsafe-libyaml",
+]
+
 [[package]]
 name = "sha1"
 version = "0.10.6"
@@ -5419,6 +5432,17 @@ dependencies = [
  "xattr",
 ]
 
+[[package]]
+name = "target-docs"
+version = "0.1.0"
+dependencies = [
+ "eyre",
+ "glob",
+ "serde",
+ "serde_json",
+ "serde_yaml",
+]
+
 [[package]]
 name = "tempfile"
 version = "3.10.1"
@@ -6065,6 +6089,12 @@ dependencies = [
  "diff",
 ]
 
+[[package]]
+name = "unsafe-libyaml"
+version = "0.2.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ab4c90930b95a82d00dc9e9ac071b4991924390d46cbd0dfe566148667605e4b"
+
 [[package]]
 name = "unstable-book-gen"
 version = "0.1.0"

Cargo.toml

@@ -46,6 +46,7 @@ members = [
   "src/tools/rustdoc-gui-test",
   "src/tools/opt-dist",
   "src/tools/coverage-dump",
+  "src/tools/target-docs",
 ]
 
 exclude = [

compiler/rustc_target/src/spec/targets/aarch64_apple_tvos.rs

@@ -6,9 +6,9 @@ pub fn target() -> Target {
     Target {
         llvm_target: tvos_llvm_target(arch).into(),
         metadata: crate::spec::TargetMetadata {
-            description: None,
-            tier: None,
-            host_tools: None,
+            description: Some("ARM64 tvOS".into()),
+            tier: Some(2),
+            host_tools: Some(false),
             std: None,
         },
         pointer_width: 64,

compiler/rustc_target/src/spec/targets/i686_pc_windows_gnu.rs

@@ -18,10 +18,10 @@ pub fn target() -> Target {
     Target {
         llvm_target: "i686-pc-windows-gnu".into(),
         metadata: crate::spec::TargetMetadata {
-            description: None,
-            tier: None,
-            host_tools: None,
-            std: None,
+            description: Some("32-bit MinGW (Windows 7+)".into()),
+            tier: Some(1),
+            host_tools: Some(true),
+            std: Some(true),
         },
         pointer_width: 32,
         data_layout: "e-m:x-p:32:32-p270:32:32-p271:32:32-p272:64:64-\

compiler/rustc_target/src/spec/targets/loongarch64_unknown_linux_gnu.rs

@@ -4,10 +4,10 @@ pub fn target() -> Target {
     Target {
         llvm_target: "loongarch64-unknown-linux-gnu".into(),
         metadata: crate::spec::TargetMetadata {
-            description: None,
-            tier: None,
-            host_tools: None,
-            std: None,
+            description: Some("LoongArch64 Linux, LP64D ABI (kernel 5.19, glibc 2.36)".into()),
+            tier: Some(2),
+            host_tools: Some(true),
+            std: Some(true),
         },
         pointer_width: 64,
         data_layout: "e-m:e-p:64:64-i64:64-i128:128-n64-S128".into(),

compiler/rustc_target/src/spec/targets/powerpc64_ibm_aix.rs

@@ -11,10 +11,10 @@ pub fn target() -> Target {
     Target {
         llvm_target: "powerpc64-ibm-aix".into(),
         metadata: crate::spec::TargetMetadata {
-            description: None,
-            tier: None,
-            host_tools: None,
-            std: None,
+            description: Some("64-bit AIX (7.2 and newer)".into()),
+            tier: Some(3),
+            host_tools: Some(true),
+            std: Some(true),
         },
         pointer_width: 64,
         data_layout: "E-m:a-Fi64-i64:64-n32:64-S128-v256:256:256-v512:512:512".into(),

src/bootstrap/src/core/build_steps/doc.rs

@@ -1147,14 +1147,24 @@ impl Step for RustcBook {
 
     /// Builds the rustc book.
     ///
-    /// The lints are auto-generated by a tool, and then merged into the book
+    /// The lints and target docs are auto-generated by a tool, and then merged into the book
     /// in the "md-doc" directory in the build output directory. Then
     /// "rustbook" is used to convert it to HTML.
     fn run(self, builder: &Builder<'_>) {
+        // The rustc book invokes rustc in its build process and relies on it being the in-tree rustc.
+        // (by requiring that the targets match and also that nightly flags can be used)
+        // Using the bootstrap compiler for this doesn't work.
+        if builder.top_stage < 1 {
+            crate::fail("building the rustc book with stage 0 is not supported, use --stage 1");
+        }
+
         let out_base = builder.md_doc_out(self.target).join("rustc");
         t!(fs::create_dir_all(&out_base));
-        let out_listing = out_base.join("src/lints");
-        builder.cp_link_r(&builder.src.join("src/doc/rustc"), &out_base);
+        let out_lints_listing = out_base.join("src/lints");
+        let out_src_listing = out_base.join("src");
+
+        // target-docs will be modifying the files in-place, so we need an actual copy.
+        builder.cp_r(&builder.src.join("src/doc/rustc"), &out_base);
         builder.info(&format!("Generating lint docs ({})", self.target));
 
         let rustc = builder.rustc(self.compiler);
@@ -1165,7 +1175,7 @@ impl Step for RustcBook {
         cmd.arg("--src");
         cmd.arg(builder.src.join("compiler"));
         cmd.arg("--out");
-        cmd.arg(&out_listing);
+        cmd.arg(&out_lints_listing);
         cmd.arg("--rustc");
         cmd.arg(&rustc);
         cmd.arg("--rustc-target").arg(self.target.rustc_target_arg());
@@ -1194,6 +1204,26 @@ impl Step for RustcBook {
         builder.run(&mut cmd);
         drop(doc_generator_guard);
 
+        // Run target-docs generator
+        let mut cmd = builder.tool_cmd(Tool::TargetDocs);
+        cmd.arg(builder.src.join("src/doc/rustc/target_infos"));
+        cmd.arg(&out_src_listing);
+        cmd.env("RUSTC", &rustc);
+        // For now, we just check that the files are correct but do not generate output.
+        // Let the user override it to TARGET_CHECK_ONLY=0 for testing, but use 1 by default.
+        // See https://github.com/rust-lang/rust/issues/120745 for more info.
+        cmd.env("TARGET_CHECK_ONLY", std::env::var("TARGET_CHECK_ONLY").unwrap_or("1".to_owned()));
+
+        let doc_generator_guard = builder.msg(
+            Kind::Run,
+            self.compiler.stage,
+            "target-docs",
+            self.compiler.host,
+            self.target,
+        );
+        builder.run(&mut cmd);
+        drop(doc_generator_guard);
+
         // Run rustbook/mdbook to generate the HTML pages.
         builder.ensure(RustbookSrc {
             target: self.target,

src/bootstrap/src/core/build_steps/tool.rs

@@ -301,6 +301,7 @@ bootstrap_tool!(
     RustdocTheme, "src/tools/rustdoc-themes", "rustdoc-themes";
     ExpandYamlAnchors, "src/tools/expand-yaml-anchors", "expand-yaml-anchors";
     LintDocs, "src/tools/lint-docs", "lint-docs";
+    TargetDocs, "src/tools/target-docs", "target-docs";
     JsonDocCk, "src/tools/jsondocck", "jsondocck";
     JsonDocLint, "src/tools/jsondoclint", "jsondoclint";
     HtmlChecker, "src/tools/html-checker", "html-checker";

src/bootstrap/src/lib.rs

@@ -1668,10 +1668,23 @@ impl Build {
     /// You can neither rely on this being a copy nor it being a link,
     /// so do not write to dst.
     pub fn copy_link(&self, src: &Path, dst: &Path) {
-        self.copy_link_internal(src, dst, false);
+        self.copy_internal(src, dst, false, true);
     }
 
-    fn copy_link_internal(&self, src: &Path, dst: &Path, dereference_symlinks: bool) {
+    /// Links a file from `src` to `dst`.
+    /// Unlike, [`Build::copy_link`], this makes an actual copy, which is usually not required,
+    /// so `copy_link` should be used instead if possible.
+    pub fn copy(&self, src: &Path, dst: &Path) {
+        self.copy_internal(src, dst, false, false);
+    }
+
+    fn copy_internal(
+        &self,
+        src: &Path,
+        dst: &Path,
+        dereference_symlinks: bool,
+        link_if_possible: bool,
+    ) {
         if self.config.dry_run() {
             return;
         }
@@ -1691,7 +1704,7 @@ impl Build {
                 return;
             }
         }
-        if let Ok(()) = fs::hard_link(&src, dst) {
+        if link_if_possible && fs::hard_link(&src, dst).is_ok() {
             // Attempt to "easy copy" by creating a hard link
             // (symlinks don't work on windows), but if that fails
             // just fall back to a slow `copy` operation.
@@ -1726,6 +1739,28 @@ impl Build {
         }
     }
 
+    /// Copies the `src` directory recursively to `dst`. Both are assumed to exist
+    /// when this function is called.
+    /// Unlike, [`Build::cp_link_r`], this makes an actual copy, which is usually not required,
+    /// so `cp_link_r` should be used instead if possible.
+    pub fn cp_r(&self, src: &Path, dst: &Path) {
+        if self.config.dry_run() {
+            return;
+        }
+        for f in self.read_dir(src) {
+            let path = f.path();
+            let name = path.file_name().unwrap();
+            let dst = dst.join(name);
+            if t!(f.file_type()).is_dir() {
+                t!(fs::create_dir_all(&dst));
+                self.cp_r(&path, &dst);
+            } else {
+                let _ = fs::remove_file(&dst);
+                self.copy(&path, &dst);
+            }
+        }
+    }
+
     /// Copies the `src` directory recursively to `dst`. Both are assumed to exist
     /// when this function is called.
     /// Will attempt to use hard links if possible and fall back to copying.
@@ -1779,7 +1814,9 @@ impl Build {
         if !src.exists() {
             panic!("ERROR: File \"{}\" not found!", src.display());
         }
-        self.copy_link_internal(src, &dst, true);
+
+        self.copy_internal(src, &dst, true, true);
+
         chmod(&dst, perms);
     }
 

src/ci/docker/host-x86_64/x86_64-gnu-llvm-17/Dockerfile

@@ -49,6 +49,10 @@ ENV EXTERNAL_LLVM 1
 # be missing.
 ENV IS_NOT_LATEST_LLVM 1
 
+
+# Ubuntu LLVM 17 does not have support for experimental targets like csky.
+ENV TARGET_DOCS_SKIP_TARGETS "csky-unknown-linux-gnuabiv2,csky-unknown-linux-gnuabiv2hf"
+
 # Using llvm-link-shared due to libffi issues -- see #34486
 ENV RUST_CONFIGURE_ARGS \
       --build=x86_64-unknown-linux-gnu \

src/doc/rustc/src/SUMMARY.md

@@ -69,6 +69,9 @@
     - [x86_64-fortanix-unknown-sgx](platform-support/x86_64-fortanix-unknown-sgx.md)
     - [x86_64-unknown-none](platform-support/x86_64-unknown-none.md)
     - [x86_64h-apple-darwin](platform-support/x86_64h-apple-darwin.md)
+<!--    - [List of Targets](platform-support/targets.md) (see #120745) -->
+<!-- TARGET_LIST SECTION START -->
+<!-- TARGET_LIST SECTION END -->
 - [Targets](targets/index.md)
     - [Built-in Targets](targets/built-in.md)
     - [Custom Targets](targets/custom.md)

src/doc/rustc/src/platform-support.md

@@ -40,6 +40,9 @@ target | notes
 `x86_64-pc-windows-gnu` | 64-bit MinGW (Windows 10+)
 `x86_64-pc-windows-msvc` | 64-bit MSVC (Windows 10+)
 `x86_64-unknown-linux-gnu` | 64-bit Linux (kernel 3.2+, glibc 2.17+)
+<!-- TIER1HOST SECTION START -->
+<!-- See `src/tools/target-docs` -->
+<!-- TIER1HOST SECTION END -->
 
 [^x86_32-floats-return-ABI]: Due to limitations of the C ABI, floating-point support on `i686` targets is non-compliant: floating-point return values are passed via an x87 register, so NaN payload bits can be lost. See [issue #114479][x86-32-float-issue].
 
@@ -102,7 +105,9 @@ target | notes
 `x86_64-unknown-illumos` | illumos
 `x86_64-unknown-linux-musl` | 64-bit Linux with musl 1.2.3
 [`x86_64-unknown-netbsd`](platform-support/netbsd.md) | NetBSD/amd64
-
+<!-- TIER2HOST SECTION START -->
+<!-- See `src/tools/target-docs` -->
+<!-- TIER2HOST SECTION END -->
 ## Tier 2 without Host Tools
 
 Tier 2 targets can be thought of as "guaranteed to build". The Rust project
@@ -201,6 +206,9 @@ target | std | notes
 [`x86_64-unknown-none`](platform-support/x86_64-unknown-none.md) | * | Freestanding/bare-metal x86_64, softfloat
 `x86_64-unknown-redox` | ✓ | Redox OS
 [`x86_64-unknown-uefi`](platform-support/unknown-uefi.md) | ? | 64-bit UEFI
+<!-- TIER2 SECTION START -->
+<!-- See `src/tools/target-docs` -->
+<!-- TIER2 SECTION END -->
 
 [^x86_32-floats-x87]: Floating-point support on `i586` targets is non-compliant: the `x87` registers and instructions used for these targets do not provide IEEE-754-compliant behavior, in particular when it comes to rounding and NaN payload bits. See [issue #114479][x86-32-float-issue].
 [wasi-rename]: https://github.com/rust-lang/compiler-team/issues/607
@@ -379,5 +387,8 @@ target | std | host | notes
 [`x86_64-win7-windows-msvc`](platform-support/win7-windows-msvc.md) | ✓ |   | 64-bit Windows 7 support
 `x86_64-wrs-vxworks` | ? |  |
 [`x86_64h-apple-darwin`](platform-support/x86_64h-apple-darwin.md) | ✓ | ✓ | macOS with late-gen Intel (at least Haswell)
+<!-- TIER3 SECTION START -->
+<!-- See `src/tools/target-docs` -->
+<!-- TIER3 SECTION END -->
 
 [runs on NVIDIA GPUs]: https://github.com/japaric-archived/nvptx#targets

src/doc/rustc/src/platform-support/aix.md

@@ -1,5 +1,15 @@
 # `powerpc64-ibm-aix`
 
+<!--
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+***WARNING***
+This target has already been migrated to the new target docs system: #120745
+When editing this file, make sure that you keep the equivalent docs in ../../target_infos in sync!!!
+
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+-->
+
 **Tier: 3**
 
 Rust for AIX operating system, currently only 64-bit PowerPC is supported.

src/doc/rustc/src/platform-support/apple-tvos.md

@@ -2,6 +2,16 @@
 - aarch64-apple-tvos
 - x86_64-apple-tvos
 
+<!--
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+***WARNING***
+This target has already been migrated to the new target docs system: #120745
+When editing this file, make sure that you keep the equivalent docs in ../../target_infos in sync!!!
+
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+-->
+
 **Tier: 3**
 
 Apple tvOS targets:

src/doc/rustc/src/platform-support/loongarch-linux.md

@@ -1,5 +1,16 @@
 # loongarch\*-unknown-linux-\*
 
+<!--
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+***WARNING***
+This target has already been migrated to the new target docs system: #120745
+When editing this file, make sure that you keep the equivalent docs in ../../target_infos in sync!!!
+
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+-->
+
+
 **Tier: 2**
 
 [LoongArch] is a new RISC ISA developed by Loongson Technology Corporation Limited.

src/doc/rustc/src/platform-support/targets.md

@@ -0,0 +1,7 @@
+# List of all targets
+
+An alphabetical list of all targets.
+
+<!-- TARGET SECTION START -->
+<!-- See `src/tools/target-docs` -->
+<!-- TARGET SECTION END -->