Rollup merge of rust-lang#121051 - Nilstrieb:targetting, r=davidtwco,…

…onur-ozkan

Introduce infrastructure for generating target docs

See rust-lang#120745

It's highly unlikely that the format is optimal, but it's okay at least and can always be improved. Mostly posting this to get something working so we can continue.

Use `TARGET_CHECK_ONLY=0` to actually build the book instead of just checking the new docs.

r? `@davidtwco`

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 \

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 -->