Introduce infrastructure for generating target docs

Author: Noratrieb

Cargo.lock

@@ -1585,6 +1585,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"
@@ -5057,6 +5063,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 +5438,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"
@@ -6065,6 +6095,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,17 @@ 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_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 +1168,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 +1197,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 \