From d3fc623f79d38002b3202551281488d7182049f7 Mon Sep 17 00:00:00 2001 From: Nilstrieb <48135649+Nilstrieb@users.noreply.github.com> Date: Tue, 19 Mar 2024 19:03:07 +0100 Subject: [PATCH] Introduce infrastructure for generating target docs --- Cargo.lock | 36 +++ Cargo.toml | 1 + .../src/spec/targets/aarch64_apple_tvos.rs | 6 +- .../src/spec/targets/i686_pc_windows_gnu.rs | 8 +- .../targets/loongarch64_unknown_linux_gnu.rs | 8 +- .../src/spec/targets/powerpc64_ibm_aix.rs | 8 +- src/bootstrap/src/core/build_steps/doc.rs | 31 ++- src/bootstrap/src/core/build_steps/tool.rs | 1 + src/bootstrap/src/lib.rs | 45 ++- .../host-x86_64/x86_64-gnu-llvm-17/Dockerfile | 4 + src/doc/rustc/src/SUMMARY.md | 3 + src/doc/rustc/src/platform-support.md | 13 +- src/doc/rustc/src/platform-support/aix.md | 10 + .../rustc/src/platform-support/apple-tvos.md | 10 + .../src/platform-support/loongarch-linux.md | 11 + src/doc/rustc/src/platform-support/targets.md | 7 + src/doc/rustc/target_infos/*-apple-tvos.md | 78 ++++++ .../rustc/target_infos/i686-pc-windows-gnu.md | 10 + .../loongarch*-unknown-linux-*.md | 93 +++++++ .../rustc/target_infos/powerpc64-ibm-aix.md | 18 ++ src/tools/target-docs/Cargo.toml | 14 + src/tools/target-docs/README.md | 37 +++ src/tools/target-docs/src/main.rs | 234 ++++++++++++++++ src/tools/target-docs/src/parse.rs | 135 +++++++++ src/tools/target-docs/src/parse/tests.rs | 99 +++++++ src/tools/target-docs/src/render.rs | 257 ++++++++++++++++++ 26 files changed, 1153 insertions(+), 24 deletions(-) create mode 100644 src/doc/rustc/src/platform-support/targets.md create mode 100644 src/doc/rustc/target_infos/*-apple-tvos.md create mode 100644 src/doc/rustc/target_infos/i686-pc-windows-gnu.md create mode 100644 src/doc/rustc/target_infos/loongarch*-unknown-linux-*.md create mode 100644 src/doc/rustc/target_infos/powerpc64-ibm-aix.md create mode 100644 src/tools/target-docs/Cargo.toml create mode 100644 src/tools/target-docs/README.md create mode 100644 src/tools/target-docs/src/main.rs create mode 100644 src/tools/target-docs/src/parse.rs create mode 100644 src/tools/target-docs/src/parse/tests.rs create mode 100644 src/tools/target-docs/src/render.rs diff --git a/Cargo.lock b/Cargo.lock index b8fe1ebaf8019..e20a26cda3ae3 100644 --- a/Cargo.lock +++ b/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" diff --git a/Cargo.toml b/Cargo.toml index e12c968e205b7..90f17982f88e8 100644 --- a/Cargo.toml +++ b/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 --git a/compiler/rustc_target/src/spec/targets/aarch64_apple_tvos.rs b/compiler/rustc_target/src/spec/targets/aarch64_apple_tvos.rs index 0deadbdb02810..86e60ebe9fb8f 100644 --- a/compiler/rustc_target/src/spec/targets/aarch64_apple_tvos.rs +++ b/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 --git a/compiler/rustc_target/src/spec/targets/i686_pc_windows_gnu.rs b/compiler/rustc_target/src/spec/targets/i686_pc_windows_gnu.rs index 66e09416dde90..50465d6710987 100644 --- a/compiler/rustc_target/src/spec/targets/i686_pc_windows_gnu.rs +++ b/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 --git a/compiler/rustc_target/src/spec/targets/loongarch64_unknown_linux_gnu.rs b/compiler/rustc_target/src/spec/targets/loongarch64_unknown_linux_gnu.rs index f15a879894004..e4c3dc3492625 100644 --- a/compiler/rustc_target/src/spec/targets/loongarch64_unknown_linux_gnu.rs +++ b/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 --git a/compiler/rustc_target/src/spec/targets/powerpc64_ibm_aix.rs b/compiler/rustc_target/src/spec/targets/powerpc64_ibm_aix.rs index 481df71c1a65a..227799e1f6fac 100644 --- a/compiler/rustc_target/src/spec/targets/powerpc64_ibm_aix.rs +++ b/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 --git a/src/bootstrap/src/core/build_steps/doc.rs b/src/bootstrap/src/core/build_steps/doc.rs index 51b5cdc056577..92bd2d67c7199 100644 --- a/src/bootstrap/src/core/build_steps/doc.rs +++ b/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, diff --git a/src/bootstrap/src/core/build_steps/tool.rs b/src/bootstrap/src/core/build_steps/tool.rs index deab3fce54ca7..5ca0c66438206 100644 --- a/src/bootstrap/src/core/build_steps/tool.rs +++ b/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 --git a/src/bootstrap/src/lib.rs b/src/bootstrap/src/lib.rs index d8397ab51de3c..412d309fb799a 100644 --- a/src/bootstrap/src/lib.rs +++ b/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); } diff --git a/src/ci/docker/host-x86_64/x86_64-gnu-llvm-17/Dockerfile b/src/ci/docker/host-x86_64/x86_64-gnu-llvm-17/Dockerfile index 538962802c96f..9fa1afcf811b8 100644 --- a/src/ci/docker/host-x86_64/x86_64-gnu-llvm-17/Dockerfile +++ b/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 \ diff --git a/src/doc/rustc/src/SUMMARY.md b/src/doc/rustc/src/SUMMARY.md index 83acce80f969d..a1ee671170669 100644 --- a/src/doc/rustc/src/SUMMARY.md +++ b/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) + + + - [Targets](targets/index.md) - [Built-in Targets](targets/built-in.md) - [Custom Targets](targets/custom.md) diff --git a/src/doc/rustc/src/platform-support.md b/src/doc/rustc/src/platform-support.md index 75d38dd20bdeb..b1fb2b196bbf2 100644 --- a/src/doc/rustc/src/platform-support.md +++ b/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+) + + + [^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 - + + + ## 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 + + + [^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) + + + [runs on NVIDIA GPUs]: https://github.com/japaric-archived/nvptx#targets diff --git a/src/doc/rustc/src/platform-support/aix.md b/src/doc/rustc/src/platform-support/aix.md index c3ce71a183568..bbde0daa179fc 100644 --- a/src/doc/rustc/src/platform-support/aix.md +++ b/src/doc/rustc/src/platform-support/aix.md @@ -1,5 +1,15 @@ # `powerpc64-ibm-aix` + + **Tier: 3** Rust for AIX operating system, currently only 64-bit PowerPC is supported. diff --git a/src/doc/rustc/src/platform-support/apple-tvos.md b/src/doc/rustc/src/platform-support/apple-tvos.md index e7ea109df1ba1..4a42779bb3464 100644 --- a/src/doc/rustc/src/platform-support/apple-tvos.md +++ b/src/doc/rustc/src/platform-support/apple-tvos.md @@ -2,6 +2,16 @@ - aarch64-apple-tvos - x86_64-apple-tvos + + **Tier: 3** Apple tvOS targets: diff --git a/src/doc/rustc/src/platform-support/loongarch-linux.md b/src/doc/rustc/src/platform-support/loongarch-linux.md index e8f55b8bfce10..3cda4eaf4b07c 100644 --- a/src/doc/rustc/src/platform-support/loongarch-linux.md +++ b/src/doc/rustc/src/platform-support/loongarch-linux.md @@ -1,5 +1,16 @@ # loongarch\*-unknown-linux-\* + + + **Tier: 2** [LoongArch] is a new RISC ISA developed by Loongson Technology Corporation Limited. diff --git a/src/doc/rustc/src/platform-support/targets.md b/src/doc/rustc/src/platform-support/targets.md new file mode 100644 index 0000000000000..2a34bac74b377 --- /dev/null +++ b/src/doc/rustc/src/platform-support/targets.md @@ -0,0 +1,7 @@ +# List of all targets + +An alphabetical list of all targets. + + + + diff --git a/src/doc/rustc/target_infos/*-apple-tvos.md b/src/doc/rustc/target_infos/*-apple-tvos.md new file mode 100644 index 0000000000000..1701dc42f9855 --- /dev/null +++ b/src/doc/rustc/target_infos/*-apple-tvos.md @@ -0,0 +1,78 @@ +--- +maintainers: ["@thomcc"] +--- + +## Overview + +Apple tvOS targets: +- Apple tvOS on aarch64 +- Apple tvOS Simulator on x86_64 + +## Requirements + +These targets are cross-compiled. You will need appropriate versions of Xcode +and the SDKs for tvOS (`AppleTVOS.sdk`) and/or the tvOS Simulator +(`AppleTVSimulator.sdk`) to build a toolchain and target these platforms. + +The targets support most (see below) of the standard library including the +allocator to the best of my knowledge, however they are very new, not yet +well-tested, and it is possible that there are various bugs. + +In theory we support back to tvOS version 7.0, although the actual minimum +version you can target may be newer than this, for example due to the versions +of Xcode and your SDKs. + +As with the other Apple targets, `rustc` respects the common environment +variables used by Xcode to configure this, in this case +`TVOS_DEPLOYMENT_TARGET`. + +As mentioned, "most" of the standard library is supported, which means that some portions +are known to be unsupported. The following APIs are currently known to have +missing or incomplete support: + +- `std::process::Command`'s API will return an error if it is configured in a + manner which cannot be performed using `posix_spawn` -- this is because the + more flexible `fork`/`exec`-based approach is prohibited on these platforms in + favor of `posix_spawn{,p}` (which still probably will get you rejected from + app stores, so is likely sideloading-only). A concrete set of cases where this + will occur is difficult to enumerate (and would quickly become stale), but in + some cases it may be worked around by tweaking the manner in which `Command` + is invoked. + +## Building the target + +The targets can be built by enabling them for a `rustc` build in `config.toml`, by adding, for example: + +```toml +[build] +build-stage = 1 +target = ["aarch64-apple-tvos", "x86_64-apple-tvos", "aarch64-apple-tvos-sim"] +``` + +It's possible that cargo under `-Zbuild-std` may also be used to target them. + +## Building Rust programs + +*Note: Building for this target requires the corresponding TVOS SDK, as provided by Xcode.* + +Rust programs can be built for these targets + +```text +$ rustc --target aarch64-apple-tvos your-code.rs +... +$ rustc --target x86_64-apple-tvos your-code.rs +... +$ rustc --target aarch64-apple-tvos-sim your-code.rs +``` + +## Testing + +There is no support for running the Rust or standard library testsuite on tvOS or the simulators at the moment. Testing has mostly been done manually with builds of static libraries called from Xcode or a simulator. + +It hopefully will be possible to improve this in the future. + +## Cross compilation + +This target can be cross-compiled from x86_64 or aarch64 macOS hosts. + +Other hosts are not supported for cross-compilation, but might work when also providing the required Xcode SDK. diff --git a/src/doc/rustc/target_infos/i686-pc-windows-gnu.md b/src/doc/rustc/target_infos/i686-pc-windows-gnu.md new file mode 100644 index 0000000000000..02fe6df687e12 --- /dev/null +++ b/src/doc/rustc/target_infos/i686-pc-windows-gnu.md @@ -0,0 +1,10 @@ +--- +footnotes: + i686-pc-windows-gnu: + - "x86_32-floats-return-ABI" + - "windows-support" +--- + +## Overview + +32-bit Windows using MinGW. diff --git a/src/doc/rustc/target_infos/loongarch*-unknown-linux-*.md b/src/doc/rustc/target_infos/loongarch*-unknown-linux-*.md new file mode 100644 index 0000000000000..b2156caa749bc --- /dev/null +++ b/src/doc/rustc/target_infos/loongarch*-unknown-linux-*.md @@ -0,0 +1,93 @@ +--- +maintainers: + - "[WANG Rui](https://github.com/heiher) `wangrui@loongson.cn`" + - "[ZHAI Xiang](https://github.com/xiangzhai) `zhaixiang@loongson.cn`" + - "[ZHAI Xiaojuan](https://github.com/zhaixiaojuan) `zhaixiaojuan@loongson.cn`" + - "[WANG Xuerui](https://github.com/xen0n) `git@xen0n.name`" +--- + +## Overview + +[LoongArch] is a new RISC ISA developed by Loongson Technology Corporation Limited. + +[LoongArch]: https://loongson.github.io/LoongArch-Documentation/README-EN.html + +The target name follow this format: `--`, where `` specifies the CPU family/model, `` specifies the vendor and `` the operating system name. +While the integer base ABI is implied by the machine field, the floating point base ABI type is encoded into the os field of the specifier using the string suffix ``. + +| `` | `Description` | +|------------------------|--------------------------------------------------------------------| +| f64 | The base ABI use 64-bits FPRs for parameter passing. (lp64d)| +| f32 | The base ABI uses 32-bit FPRs for parameter passing. (lp64f)| +| sf | The base ABI uses no FPR for parameter passing. (lp64s) | + +
+ +|`ABI type(Base ABI/ABI extension)`| `C library` | `kernel` | `target tuple` | +|----------------------------------|-------------|----------|----------------------------------| +| lp64d/base | glibc | linux | loongarch64-unknown-linux-gnu | +| lp64f/base | glibc | linux | loongarch64-unknown-linux-gnuf32 | +| lp64s/base | glibc | linux | loongarch64-unknown-linux-gnusf | +| lp64d/base | musl libc | linux | loongarch64-unknown-linux-musl| +| lp64f/base | musl libc | linux | loongarch64-unknown-linux-muslf32| +| lp64s/base | musl libc | linux | loongarch64-unknown-linux-muslsf | + +## Requirements + +This target is cross-compiled. +A GNU toolchain for LoongArch target is required. It can be downloaded from https://github.com/loongson/build-tools/releases, or built from the source code of GCC (12.1.0 or later) and Binutils (2.40 or later). + +## Building the target + +The target can be built by enabling it for a `rustc` build. + +```toml +[build] +target = ["loongarch64-unknown-linux-gnu"] +``` + +Make sure `loongarch64-unknown-linux-gnu-gcc` can be searched from the directories specified in`$PATH`. Alternatively, you can use GNU LoongArch Toolchain by adding the following to `config.toml`: + +```toml +[target.loongarch64-unknown-linux-gnu] +# ADJUST THIS PATH TO POINT AT YOUR TOOLCHAIN +cc = "/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-gcc" +cxx = "/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-g++" +ar = "/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-ar" +ranlib = "/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-ranlib" +linker = "/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-gcc" +``` + +## Cross compilation + +This target can be cross-compiled on a `x86_64-unknown-linux-gnu` host. Cross-compilation on other hosts may work but is not tested. + +## Testing +To test a cross-compiled binary on your build system, install the qemu binary that supports the LoongArch architecture and execute the following commands. +```text +CC_loongarch64_unknown_linux_gnu=/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-gcc \ +CXX_loongarch64_unknown_linux_gnu=/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-g++ \ +AR_loongarch64_unknown_linux_gnu=/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-gcc-ar \ +CARGO_TARGET_LOONGARCH64_UNKNOWN_LINUX_GNUN_LINKER=/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-gcc \ +# SET TARGET SYSTEM LIBRARY PATH +CARGO_TARGET_LOONGARCH64_UNKNOWN_LINUX_GNUN_RUNNER="qemu-loongarch64 -L /TOOLCHAIN_PATH/TARGET_LIBRARY_PATH" \ +cargo run --target loongarch64-unknown-linux-gnu --release +``` +Tested on x86 architecture, other architectures not tested. + +## Building Rust programs + +Rust does not yet ship pre-compiled artifacts for this target. To compile for this target, you will either need to build Rust with the target enabled (see "Building the target" above), or build your own copy of `std` by using `build-std` or similar. + +If `rustc` has support for that target and the library artifacts are available, then Rust static libraries can be built for that target: + +```shell +$ rustc --target loongarch64-unknown-linux-gnu your-code.rs --crate-type staticlib +$ ls libyour_code.a +``` + +On Rust Nightly it's possible to build without the target artifacts available: + +```text +cargo build -Z build-std --target loongarch64-unknown-linux-gnu +``` diff --git a/src/doc/rustc/target_infos/powerpc64-ibm-aix.md b/src/doc/rustc/target_infos/powerpc64-ibm-aix.md new file mode 100644 index 0000000000000..ac070cb92f7f6 --- /dev/null +++ b/src/doc/rustc/target_infos/powerpc64-ibm-aix.md @@ -0,0 +1,18 @@ +--- +maintainers: [ + "QIU Chaofan `qiucofan@cn.ibm.com`, https://github.com/ecnelises", + "Kai LUO, `lkail@cn.ibm.com`, https://github.com/bzEq", +] +--- + +## Requirements + +This target supports host tools, std and alloc. This target cannot be cross-compiled as for now, mainly because of the unavailability of system linker on other platforms. + +Binary built for this target is expected to run on Power7 or newer CPU, and AIX 7.2 or newer version. + +Binary format of this platform is XCOFF. Archive file format is 'AIX big format'. + +## Testing + +This target supports running test suites natively, but it's not available to cross-compile and execute in emulator. diff --git a/src/tools/target-docs/Cargo.toml b/src/tools/target-docs/Cargo.toml new file mode 100644 index 0000000000000..78741710dcbb7 --- /dev/null +++ b/src/tools/target-docs/Cargo.toml @@ -0,0 +1,14 @@ +[package] +name = "target-docs" +version = "0.1.0" +edition = "2021" +license = "MIT OR Apache-2.0" + +# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html + +[dependencies] +eyre = "0.6.12" +glob-match = "0.2.1" +serde = { version = "1.0.185", features = ["derive"] } +serde_json = "1.0.114" +serde_yaml = "0.9.31" diff --git a/src/tools/target-docs/README.md b/src/tools/target-docs/README.md new file mode 100644 index 0000000000000..d7717a2ced8e8 --- /dev/null +++ b/src/tools/target-docs/README.md @@ -0,0 +1,37 @@ +# target-docs + +This tool generates target documentation for all targets in the rustc book. + +To achieve this, it uses a list of input markdown files provided in `src/doc/rustc/target_infos`. These files follow a strict format. +Every file covers a glob pattern of targets according to its file name. + +For every rustc target, we iterate through all the target infos and find matching globs. +When a glob matches, it extracts the h2 markdown sections and saves them for the target. + +In the end, a page is generated for every target using these sections. +Sections that are not provided are stubbed out. Currently, the sections are + +- Overview +- Requirements +- Testing +- Building the target +- Cross compilation +- Building Rust programs + +In addition to the markdown sections, we also have extra data about the targets. +This is achieved through YAML frontmatter. + +The frontmatter follows the following format: + +```yaml +maintainers: ["@someone"] +footnotes: + i686-pc-windows-gnu: + - "x86_32-floats-return-ABI" + - "windows-support" +``` + +The top level keys are: + +- `maintainers` (optional): list of strings +- `footnotes` (optional): for every *specific* target a list of footnotes. The footnotes have to be defined manually below the correct table in platform-support. diff --git a/src/tools/target-docs/src/main.rs b/src/tools/target-docs/src/main.rs new file mode 100644 index 0000000000000..73d8b3f4fbc47 --- /dev/null +++ b/src/tools/target-docs/src/main.rs @@ -0,0 +1,234 @@ +mod parse; +mod render; + +use std::{ + collections::HashMap, + path::{Path, PathBuf}, + process::Command, +}; + +use eyre::{bail, Context, OptionExt, Result}; +use parse::ParsedTargetInfoFile; +use serde::Deserialize; + +/// Information about a target obtained from the markdown and rustc. +struct TargetInfo { + name: String, + maintainers: Vec, + sections: Vec<(String, String)>, + footnotes: Vec, + target_cfgs: Vec<(String, String)>, + metadata: RustcTargetMetadata, +} + +/// All the sections that we want every doc page to have. +/// It may make sense to relax this into two kinds of sections, "required" sections +/// and "optional" sections, where required sections will get stubbed out when not found +/// while optional sections will just not exist when not found. +// IMPORTANT: This is also documented in the README, keep it in sync. +const SECTIONS: &[&str] = &[ + "Overview", + "Requirements", + "Testing", + "Building the target", + "Cross compilation", + "Building Rust programs", +]; + +fn main() -> Result<()> { + let args = std::env::args().collect::>(); + let input_dir = args + .get(1) + .ok_or_eyre("first argument must be path to target_infos directory containing target source md files (src/doc/rustc/target_infos/)")?; + let output_src = args.get(2).ok_or_eyre( + "second argument must be path to `src` output directory (build/$target/md-doc/rustc/src)", + )?; + + println!("Loading target info docs from {input_dir}"); + println!("Writing output to {output_src}"); + + let targets_to_skip = std::env::var("TARGET_DOCS_SKIP_TARGETS"); + let targets_to_skip = + targets_to_skip.as_deref().map(|s| s.split(",").collect::>()).unwrap_or_default(); + + let rustc = + PathBuf::from(std::env::var("RUSTC").expect("must pass RUSTC env var pointing to rustc")); + let check_only = std::env::var("TARGET_CHECK_ONLY") == Ok("1".to_owned()); + + let targets = rustc_stdout(&rustc, &["--print", "target-list"]); + let targets = + targets.lines().filter(|target| !targets_to_skip.contains(target)).collect::>(); + + let mut info_patterns = parse::load_target_infos(Path::new(input_dir)) + .wrap_err("failed loading target_info")? + .into_iter() + .map(|info| { + let footnotes_used = + info.footnotes.keys().map(|target| (target.clone(), false)).collect(); + TargetPatternEntry { info, used: false, footnotes_used } + }) + .collect::>(); + + eprintln!("Collecting rustc information"); + let rustc_infos = + targets.iter().map(|target| rustc_target_info(&rustc, target)).collect::>(); + + let targets = targets + .into_iter() + .map(|target| target_doc_info(&mut info_patterns, target)) + .zip(rustc_infos) + .map(|(md, rustc)| TargetInfo { + name: md.name, + maintainers: md.maintainers, + sections: md.sections, + footnotes: md.footnotes, + target_cfgs: rustc.target_cfgs, + metadata: rustc.metadata, + }) + .collect::>(); + + eprintln!("Rendering targets check_only={check_only}"); + let targets_dir = Path::new(output_src).join("platform-support").join("targets"); + if !check_only { + std::fs::create_dir_all(&targets_dir).wrap_err("creating platform-support/targets dir")?; + } + for info in &targets { + let doc = render::render_target_md(info); + + if !check_only { + std::fs::write(targets_dir.join(format!("{}.md", info.name)), doc) + .wrap_err("writing target file")?; + } + } + + for target_pattern in info_patterns { + if !target_pattern.used { + bail!("target pattern `{}` was never used", target_pattern.info.pattern); + } + + for footnote_target in target_pattern.info.footnotes.keys() { + let used = target_pattern.footnotes_used[footnote_target]; + if !used { + bail!( + "in target pattern `{}`, the footnotes for target `{}` were never used", + target_pattern.info.pattern, + footnote_target, + ); + } + } + } + + render::render_static(check_only, Path::new(output_src), &targets)?; + + eprintln!("Finished generating target docs"); + Ok(()) +} + +struct TargetPatternEntry { + info: ParsedTargetInfoFile, + used: bool, + footnotes_used: HashMap, +} + +/// Information about a target obtained from the target_info markdown file. +struct TargetInfoMd { + name: String, + maintainers: Vec, + sections: Vec<(String, String)>, + footnotes: Vec, +} + +fn target_doc_info(info_patterns: &mut [TargetPatternEntry], target: &str) -> TargetInfoMd { + let mut maintainers = Vec::new(); + let mut sections = Vec::new(); + + let mut footnotes = Vec::new(); + + for target_pattern_entry in info_patterns { + if glob_match::glob_match(&target_pattern_entry.info.pattern, target) { + target_pattern_entry.used = true; + let target_pattern = &target_pattern_entry.info; + + maintainers.extend_from_slice(&target_pattern.maintainers); + + for (section_name, content) in &target_pattern.sections { + if sections.iter().any(|(name, _)| name == section_name) { + panic!( + "target {target} inherits the section {section_name} from multiple patterns, create a more specific pattern and add it there" + ); + } + sections.push((section_name.clone(), content.clone())); + } + + if let Some(target_footnotes) = target_pattern.footnotes.get(target) { + target_pattern_entry.footnotes_used.insert(target.to_owned(), true); + + if !footnotes.is_empty() { + panic!("target {target} is assigned metadata from more than one pattern"); + } + footnotes = target_footnotes.clone(); + } + } + } + + TargetInfoMd { name: target.to_owned(), maintainers, sections, footnotes } +} + +/// Information about a target obtained from rustc. +struct RustcTargetInfo { + target_cfgs: Vec<(String, String)>, + metadata: RustcTargetMetadata, +} + +#[derive(Deserialize)] +struct RustcTargetMetadata { + description: Option, + tier: Option, + host_tools: Option, + std: Option, +} + +/// Get information about a target from rustc. +fn rustc_target_info(rustc: &Path, target: &str) -> RustcTargetInfo { + let cfgs = rustc_stdout(rustc, &["--print", "cfg", "--target", target]); + let target_cfgs = cfgs + .lines() + .filter_map(|line| { + if line.starts_with("target_") { + let Some((key, value)) = line.split_once('=') else { + // For example `unix` + return None; + }; + Some((key.to_owned(), value.to_owned())) + } else { + None + } + }) + .collect(); + + #[derive(Deserialize)] + struct TargetJson { + metadata: RustcTargetMetadata, + } + + let json_spec = rustc_stdout( + rustc, + &["-Zunstable-options", "--print", "target-spec-json", "--target", target], + ); + let spec = serde_json::from_str::(&json_spec) + .expect("parsing --print target-spec-json for metadata"); + + RustcTargetInfo { target_cfgs, metadata: spec.metadata } +} + +fn rustc_stdout(rustc: &Path, args: &[&str]) -> String { + let output = Command::new(rustc).args(args).output().unwrap(); + if !output.status.success() { + panic!( + "rustc failed: {}, {}", + output.status, + String::from_utf8(output.stderr).unwrap_or_default() + ) + } + String::from_utf8(output.stdout).unwrap() +} diff --git a/src/tools/target-docs/src/parse.rs b/src/tools/target-docs/src/parse.rs new file mode 100644 index 0000000000000..b771c8840209b --- /dev/null +++ b/src/tools/target-docs/src/parse.rs @@ -0,0 +1,135 @@ +//! Suboptimal half-markdown parser that's just good-enough for this. + +use eyre::{bail, OptionExt, Result, WrapErr}; +use serde::Deserialize; +use std::{collections::HashMap, fs::DirEntry, path::Path}; + +#[derive(Debug)] +pub struct ParsedTargetInfoFile { + pub pattern: String, + pub maintainers: Vec, + pub sections: Vec<(String, String)>, + pub footnotes: HashMap>, +} + +// IMPORTANT: This is also documented in the README, keep it in sync. +#[derive(Deserialize)] +#[serde(deny_unknown_fields)] +struct Frontmatter { + #[serde(default)] + maintainers: Vec, + #[serde(default)] + footnotes: HashMap>, +} + +// IMPORTANT: This is also documented in the README, keep it in sync. +#[derive(Debug, Clone, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct TargetFootnotes { + pub target: String, + #[serde(default)] + pub footnotes: Vec, +} + +// IMPORTANT: This is also documented in the README, keep it in sync. +#[derive(Debug, PartialEq, Clone, Copy, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum TriStateBool { + True, + False, + Unknown, +} + +pub fn load_target_infos(directory: &Path) -> Result> { + let dir = std::fs::read_dir(directory).unwrap(); + let mut infos = Vec::new(); + + for entry in dir { + let entry = entry?; + infos.push( + load_single_target_info(&entry) + .wrap_err_with(|| format!("loading {}", entry.path().display()))?, + ) + } + + Ok(infos) +} + +fn load_single_target_info(entry: &DirEntry) -> Result { + let pattern = entry.file_name(); + let name = pattern + .to_str() + .ok_or_eyre("file name is invalid utf8")? + .strip_suffix(".md") + .ok_or_eyre("target_info files must end with .md")?; + let content: String = std::fs::read_to_string(entry.path()).wrap_err("reading content")?; + + parse_file(name, &content) +} + +fn parse_file(name: &str, content: &str) -> Result { + let mut frontmatter_splitter = content.split("---\n"); + + let frontmatter = frontmatter_splitter.nth(1).ok_or_eyre("missing frontmatter")?; + + let frontmatter_line_count = frontmatter.lines().count() + 2; // 2 from --- + + let frontmatter = + serde_yaml::from_str::(frontmatter).wrap_err("invalid frontmatter")?; + + let body = frontmatter_splitter.next().ok_or_eyre("no body")?; + + let mut sections = Vec::<(String, String)>::new(); + let mut in_codeblock = false; + + for (idx, line) in body.lines().enumerate() { + let number = frontmatter_line_count + idx + 1; // 1 because "line numbers" are off by 1 + + let push_line = |sections: &mut Vec<(String, String)>, line| { + match sections.last_mut() { + Some((_, content)) => { + content.push_str(line); + content.push('\n'); + } + None if line.trim().is_empty() => {} + None => { + bail!("line {number} with content not allowed before the first heading") + } + } + Ok(()) + }; + + if line.starts_with("```") { + in_codeblock ^= true; // toggle + push_line(&mut sections, line)?; + } else if line.starts_with('#') { + if in_codeblock { + push_line(&mut sections, line)?; + } else if let Some(header) = line.strip_prefix("## ") { + if !crate::SECTIONS.contains(&header) { + bail!( + "on line {number}, `{header}` is not an allowed section name, must be one of {:?}", + super::SECTIONS + ); + } + sections.push((header.to_owned(), String::new())); + } else { + bail!("on line {number}, the only allowed headings are `## `: `{line}`"); + } + } else { + push_line(&mut sections, line)?; + } + } + + sections.iter_mut().for_each(|section| section.1 = section.1.trim().to_owned()); + + Ok(ParsedTargetInfoFile { + pattern: name.to_owned(), + maintainers: frontmatter.maintainers, + sections, + footnotes: frontmatter.footnotes, + }) +} + +#[cfg(test)] +mod tests; diff --git a/src/tools/target-docs/src/parse/tests.rs b/src/tools/target-docs/src/parse/tests.rs new file mode 100644 index 0000000000000..5b0530ba52656 --- /dev/null +++ b/src/tools/target-docs/src/parse/tests.rs @@ -0,0 +1,99 @@ +#[test] +fn no_frontmatter() { + let name = "archlinux-unknown-linux-gnu.md"; // arch linux is an arch, right? + let content = ""; + assert!(super::parse_file(name, content).is_err()); +} + +#[test] +fn invalid_section() { + let name = "6502-nintendo-nes.md"; + let content = " +--- +--- + +## Not A Real Section +"; + + assert!(super::parse_file(name, content).is_err()); +} + +#[test] +fn wrong_header() { + let name = "x86_64-known-linux-gnu.md"; + let content = " +--- +--- + +# x86_64-known-linux-gnu +"; + + assert!(super::parse_file(name, content).is_err()); +} + +#[test] +fn parse_correctly() { + let name = "cat-unknown-linux-gnu.md"; + let content = r#" +--- +maintainers: ["who maintains the cat?"] +--- +## Requirements + +This target mostly just meows and doesn't do much. + +## Testing + +You can pet the cat and it might respond positively. + +## Cross compilation + +If you're on a dog system, there might be conflicts with the cat, be careful. +But it should be possible. + "#; + + let info = super::parse_file(name, content).unwrap(); + + assert_eq!(info.maintainers, vec!["who maintains the cat?"]); + assert_eq!(info.pattern, name); + assert_eq!( + info.sections, + vec![ + ( + "Requirements".to_owned(), + "This target mostly just meows and doesn't do much.".to_owned(), + ), + ( + "Testing".to_owned(), + "You can pet the cat and it might respond positively.".to_owned(), + ), + ( + "Cross compilation".to_owned(), + "If you're on a dog system, there might be conflicts with the cat, be careful.\nBut it should be possible.".to_owned(), + ), + ] + ); +} + +#[test] +fn backticks() { + let name = "microservices-unknown-linux-gnu"; // microservices are my favourite architecture + let content = r#" +--- +--- + +## Testing + +```text +# hello world +``` + "#; + + let info = super::parse_file(name, content).unwrap(); + + assert_eq!(info.pattern, name); + assert_eq!( + info.sections, + vec![("Testing".to_owned(), "```text\n# hello world\n```".to_owned(),),] + ); +} diff --git a/src/tools/target-docs/src/render.rs b/src/tools/target-docs/src/render.rs new file mode 100644 index 0000000000000..ecb18049a2b33 --- /dev/null +++ b/src/tools/target-docs/src/render.rs @@ -0,0 +1,257 @@ +use eyre::{Context, OptionExt, Result}; +use std::{fs, path::Path}; + +use crate::TargetInfo; + +/// Renders a single target markdown file from the information obtained. +pub fn render_target_md(target: &TargetInfo) -> String { + let render_header_option_bool = |bool| match bool { + Some(true) => "Yes", + Some(false) => "No", + None => "?", + }; + + let mut doc = format!( + "# {}\n\n**Tier: {}**\n\n**std: {}**\n\n**host tools: {}**\n\n", + target.name, + match target.metadata.tier { + Some(1) => "1", + Some(2) => "2", + Some(3) => "3", + _ => "UNKNOWN", + }, + render_header_option_bool(target.metadata.std), + render_header_option_bool(target.metadata.host_tools), + ); + + let mut section = |name: &str, content: &str| { + doc.push_str("## "); + doc.push_str(name.trim()); + doc.push('\n'); + doc.push_str(content.trim()); + doc.push_str("\n\n"); + }; + + let maintainers_content = if target.maintainers.is_empty() { + "This target does not have any maintainers!".to_owned() + } else { + format!( + "This target is maintained by:\n{}", + target + .maintainers + .iter() + .map(|maintainer| { + let maintainer = if maintainer.starts_with('@') && !maintainer.contains(' ') { + format!( + "[@{0}](https://github.com/{0})", + maintainer.strip_prefix("@").unwrap() + ) + } else { + maintainer.to_owned() + }; + + format!("- {maintainer}") + }) + .collect::>() + .join("\n") + ) + }; + + section("Maintainers", &maintainers_content); + + for section_name in crate::SECTIONS { + let value = target.sections.iter().find(|(name, _)| name == section_name); + + let section_content = match value { + Some((_, value)) => value.clone(), + None => "Unknown.".to_owned(), + }; + section(section_name, §ion_content); + } + + let cfg_text = target + .target_cfgs + .iter() + .map(|(key, value)| format!("- `{key}` = `{value}`")) + .collect::>() + .join("\n"); + let cfg_content = + format!("This target defines the following target-specific cfg values:\n{cfg_text}\n"); + + section("cfg", &cfg_content); + + doc +} + +/// Replaces inner part of the form +/// `` +/// with replacement`. +fn replace_section(prev_content: &str, section_name: &str, replacement: &str) -> Result { + let magic_summary_start = format!(""); + let magic_summary_end = format!(""); + + let (pre_target, target_and_after) = prev_content + .split_once(&magic_summary_start) + .ok_or_eyre(" not found")?; + + let (_, post_target) = target_and_after + .split_once(&magic_summary_end) + .ok_or_eyre(" not found")?; + + let new = format!("{pre_target}{replacement}{post_target}"); + Ok(new) +} + +/// Renders the non-target files like `SUMMARY.md` that depend on the target. +pub fn render_static(check_only: bool, src_output: &Path, targets: &[TargetInfo]) -> Result<()> { + let targets_file = src_output.join("platform-support").join("targets.md"); + let old_targets = fs::read_to_string(&targets_file).wrap_err("reading summary file")?; + + let target_list = targets + .iter() + .map(|target| format!("- [{0}](platform-support/targets/{0}.md)", target.name)) + .collect::>() + .join("\n"); + + let new_targets = + replace_section(&old_targets, "TARGET", &target_list).wrap_err("replacing targets.md")?; + + if !check_only { + fs::write(targets_file, new_targets).wrap_err("writing targets.md")?; + } + + let platform_support_main = src_output.join("platform-support.md"); + let platform_support_main_old = + fs::read_to_string(&platform_support_main).wrap_err("reading platform-support.md")?; + let platform_support_main_new = + render_platform_support_tables(&platform_support_main_old, targets)?; + + if !check_only { + fs::write(platform_support_main, platform_support_main_new) + .wrap_err("writing platform-support.md")?; + } + + let summary = src_output.join("SUMMARY.md"); + let summary_old = fs::read_to_string(&summary).wrap_err("reading SUMMARY.md")?; + // indent the list + let summary_new = + replace_section(&summary_old, "TARGET_LIST", &target_list.replace("- ", " - ")) + .wrap_err("replacig SUMMARY.md")?; + if !check_only { + fs::write(summary, summary_new).wrap_err("writing SUMAMRY.md")?; + } + + Ok(()) +} + +impl TargetInfo { + fn has_host_tools(&self) -> bool { + self.metadata.host_tools.unwrap_or(false) + } +} + +fn render_platform_support_tables(content: &str, targets: &[TargetInfo]) -> Result { + let replace_table = |content, name, tier_table| -> Result { + let section_string = render_table(targets, tier_table)?; + replace_section(content, name, §ion_string).wrap_err("replacing platform support.md") + }; + + let content = replace_table( + content, + "TIER1HOST", + TierTable { + filter: |target| target.metadata.tier == Some(1), + include_host: false, + include_std: false, + }, + )?; + let content = replace_table( + &content, + "TIER2HOST", + TierTable { + filter: |target| target.metadata.tier == Some(2) && target.has_host_tools(), + include_host: false, + include_std: false, + }, + )?; + let content = replace_table( + &content, + "TIER2", + TierTable { + filter: |target| target.metadata.tier == Some(2) && !target.has_host_tools(), + include_host: false, + include_std: true, + }, + )?; + let content = replace_table( + &content, + "TIER3", + TierTable { + filter: |target| target.metadata.tier == Some(3), + include_host: true, + include_std: true, + }, + )?; + + Ok(content) +} + +fn render_table_option_bool(bool: Option) -> &'static str { + match bool { + Some(true) => "✓", + Some(false) => " ", + None => "?", + } +} + +struct TierTable { + filter: fn(&TargetInfo) -> bool, + include_std: bool, + include_host: bool, +} + +fn render_table(targets: &[TargetInfo], table: TierTable) -> Result { + let mut rows = Vec::new(); + + let targets = targets.iter().filter(|target| (table.filter)(target)); + + for target in targets { + let meta = &target.metadata; + + let mut notes = meta.description.as_deref().unwrap_or("unknown").to_owned(); + + if !target.footnotes.is_empty() { + let footnotes_str = target + .footnotes + .iter() + .map(|footnote| format!("[^{}]", footnote)) + .collect::>() + .join(" "); + + notes = format!("{notes} {footnotes_str}"); + } + + let std = if table.include_std { + let std = render_table_option_bool(meta.std); + format!(" | {std}") + } else { + String::new() + }; + + let host = if table.include_host { + let host = render_table_option_bool(meta.host_tools); + format!(" | {host}") + } else { + String::new() + }; + + rows.push(format!( + "[`{0}`](platform-support/targets/{0}.md){std}{host} | {notes}", + target.name + )); + } + + let result = rows.join("\n"); + + Ok(result) +}