Introduce infrastructure for generating target docs

Author: Noratrieb

Diff for: Cargo.lock

@@ -1579,6 +1579,12 @@ version = "0.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d2fabcfbdc87f4758337ca535fb41a6d701b65693ce38287d856d1674551ec9b"
 
+[[package]]
+name = "glob-match"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9985c9503b412198aa4197559e9a318524ebc4519c229bfa05a535828c950b9d"
+
 [[package]]
 name = "globset"
 version = "0.4.13"
@@ -5017,6 +5023,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"
@@ -5379,6 +5398,17 @@ dependencies = [
  "xattr",
 ]
 
+[[package]]
+name = "target-docs"
+version = "0.1.0"
+dependencies = [
+ "eyre",
+ "glob-match",
+ "serde",
+ "serde_json",
+ "serde_yaml",
+]
+
 [[package]]
 name = "tempfile"
 version = "3.10.1"
@@ -6026,6 +6056,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"

Diff for: 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 = [

Diff for: 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,

Diff for: 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-\

Diff for: 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(),

Diff for: 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(),

Diff for: src/bootstrap/src/core/build_steps/doc.rs

@@ -1144,14 +1144,16 @@ 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<'_>) {
         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_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");
+
+        builder.cp_r_but_like_really_copy(&builder.src.join("src/doc/rustc"), &out_base);
         builder.info(&format!("Generating lint docs ({})", self.target));
 
         let rustc = builder.rustc(self.compiler);
@@ -1162,7 +1164,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());
@@ -1191,6 +1193,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 #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,

Diff for: 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";

Diff for: src/bootstrap/src/lib.rs

@@ -1646,12 +1646,24 @@ impl Build {
         paths
     }
 
+    /// Copies a file from `src` to `dst`
+    // TODO: Rename to cp_r or something like that after #122590 has been merged.
+    pub fn copy_but_like_really_copy(&self, src: &Path, dst: &Path) {
+        self.copy_internal(src, dst, false, false);
+    }
+
     /// Copies a file from `src` to `dst`
     pub fn copy(&self, src: &Path, dst: &Path) {
-        self.copy_internal(src, dst, false);
+        self.copy_internal(src, dst, false, true);
     }
 
-    fn copy_internal(&self, src: &Path, dst: &Path, dereference_symlinks: bool) {
+    fn copy_internal(
+        &self,
+        src: &Path,
+        dst: &Path,
+        dereference_symlinks: bool,
+        link_if_possible: bool,
+    ) {
         if self.config.dry_run() {
             return;
         }
@@ -1671,7 +1683,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.
@@ -1706,6 +1718,25 @@ impl Build {
         }
     }
 
+    // TODO: Rename to cp_r or something like that after #122590 has been merged.
+    pub fn cp_r_but_like_really_copy(&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_but_like_really_copy(&path, &dst);
+            } else {
+                let _ = fs::remove_file(&dst);
+                self.copy_but_like_really_copy(&path, &dst);
+            }
+        }
+    }
+
     /// Copies the `src` directory recursively to `dst`. Both are assumed to exist
     /// when this function is called. Unwanted files or directories can be skipped
     /// by returning `false` from the filter function.
@@ -1751,7 +1782,7 @@ impl Build {
         if !src.exists() {
             panic!("ERROR: File \"{}\" not found!", src.display());
         }
-        self.copy_internal(src, &dst, true);
+        self.copy_internal(src, &dst, true, true);
         chmod(&dst, perms);
     }
 

Diff for: 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)
+<!-- TARGET_LIST SECTION START -->
+<!-- TARGET_LIST SECTION END -->
 - [Targets](targets/index.md)
     - [Built-in Targets](targets/built-in.md)
     - [Custom Targets](targets/custom.md)
@@ -79,4 +82,4 @@
 - [Exploit Mitigations](exploit-mitigations.md)
 - [Symbol Mangling](symbol-mangling/index.md)
     - [v0 Symbol Format](symbol-mangling/v0.md)
-- [Contributing to `rustc`](contributing.md)
+- [Contributing to `rustc`](contributing.md)

Diff for: src/doc/rustc/src/platform-support.md

@@ -32,6 +32,9 @@ All tier 1 targets with host tools support the full standard library.
 
 target | notes
 -------|-------
+<!-- TIER1HOST SECTION START -->
+<!-- See `src/tools/target-docs` -->
+<!-- TIER1HOST SECTION END -->
 `aarch64-unknown-linux-gnu` | ARM64 Linux (kernel 4.1, glibc 2.17+)
 `i686-pc-windows-gnu` | 32-bit MinGW (Windows 10+) [^windows-support] [^x86_32-floats-return-ABI]
 `i686-pc-windows-msvc` | 32-bit MSVC (Windows 10+) [^windows-support] [^x86_32-floats-return-ABI]
@@ -88,6 +91,8 @@ so Rustup may install the documentation for a similar tier 1 target instead.
 
 target | notes
 -------|-------
+<!-- TIER2HOST SECTION START -->
+<!-- TIER2HOST SECTION END -->
 `aarch64-apple-darwin` | ARM64 macOS (11.0+, Big Sur+)
 `aarch64-pc-windows-msvc` | ARM64 Windows MSVC
 `aarch64-unknown-linux-musl` | ARM64 Linux with musl 1.2.3
@@ -134,6 +139,8 @@ so Rustup may install the documentation for a similar tier 1 target instead.
 
 target | std | notes
 -------|:---:|-------
+<!-- TIER2 SECTION START -->
+<!-- TIER2 SECTION END -->
 `aarch64-apple-ios` | ✓ | ARM64 iOS
 [`aarch64-apple-ios-sim`](platform-support/aarch64-apple-ios-sim.md) | ✓ | Apple iOS Simulator on ARM64
 `aarch64-fuchsia` | ✓ | Alias for `aarch64-unknown-fuchsia`
@@ -235,6 +242,8 @@ host tools.
 
 target | std | host | notes
 -------|:---:|:----:|-------
+<!-- TIER3 SECTION START -->
+<!-- TIER3 SECTION END -->
 [`arm64e-apple-ios`](platform-support/arm64e-apple-ios.md) | ✓ | | ARM64e Apple iOS
 [`arm64e-apple-darwin`](platform-support/arm64e-apple-darwin.md)  | ✓ | ✓ | ARM64e Apple Darwin
 [`arm64ec-pc-windows-msvc`](platform-support/arm64ec-pc-windows-msvc.md) | ? | | Arm64EC Windows MSVC

Diff for: 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 -->