Skip to content

Commit 1219d99

Browse files
NoratriebNoratrieb
committed
Introduce infrastructure for generating target docs
1 parent c3b05c6 commit 1219d99

26 files changed

+1181
-24
lines changed

‎Cargo.lock

+36
Original file line numberDiff line numberDiff line change
@@ -1585,6 +1585,12 @@ version = "0.3.1"
15851585
source = "registry+https://github.com/rust-lang/crates.io-index"
15861586
checksum = "d2fabcfbdc87f4758337ca535fb41a6d701b65693ce38287d856d1674551ec9b"
15871587

1588+
[[package]]
1589+
name = "glob-match"
1590+
version = "0.2.1"
1591+
source = "registry+https://github.com/rust-lang/crates.io-index"
1592+
checksum = "9985c9503b412198aa4197559e9a318524ebc4519c229bfa05a535828c950b9d"
1593+
15881594
[[package]]
15891595
name = "globset"
15901596
version = "0.4.13"
@@ -5057,6 +5063,19 @@ dependencies = [
50575063
"serde",
50585064
]
50595065

5066+
[[package]]
5067+
name = "serde_yaml"
5068+
version = "0.9.31"
5069+
source = "registry+https://github.com/rust-lang/crates.io-index"
5070+
checksum = "adf8a49373e98a4c5f0ceb5d05aa7c648d75f63774981ed95b7c7443bbd50c6e"
5071+
dependencies = [
5072+
"indexmap",
5073+
"itoa",
5074+
"ryu",
5075+
"serde",
5076+
"unsafe-libyaml",
5077+
]
5078+
50605079
[[package]]
50615080
name = "sha1"
50625081
version = "0.10.6"
@@ -5419,6 +5438,17 @@ dependencies = [
54195438
"xattr",
54205439
]
54215440

5441+
[[package]]
5442+
name = "target-docs"
5443+
version = "0.1.0"
5444+
dependencies = [
5445+
"eyre",
5446+
"glob-match",
5447+
"serde",
5448+
"serde_json",
5449+
"serde_yaml",
5450+
]
5451+
54225452
[[package]]
54235453
name = "tempfile"
54245454
version = "3.10.1"
@@ -6065,6 +6095,12 @@ dependencies = [
60656095
"diff",
60666096
]
60676097

6098+
[[package]]
6099+
name = "unsafe-libyaml"
6100+
version = "0.2.10"
6101+
source = "registry+https://github.com/rust-lang/crates.io-index"
6102+
checksum = "ab4c90930b95a82d00dc9e9ac071b4991924390d46cbd0dfe566148667605e4b"
6103+
60686104
[[package]]
60696105
name = "unstable-book-gen"
60706106
version = "0.1.0"

‎Cargo.toml

+1
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ members = [
4646
"src/tools/rustdoc-gui-test",
4747
"src/tools/opt-dist",
4848
"src/tools/coverage-dump",
49+
"src/tools/target-docs",
4950
]
5051

5152
exclude = [

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

+3-3
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,9 @@ pub fn target() -> Target {
66
Target {
77
llvm_target: tvos_llvm_target(arch).into(),
88
metadata: crate::spec::TargetMetadata {
9-
description: None,
10-
tier: None,
11-
host_tools: None,
9+
description: Some("ARM64 tvOS".into()),
10+
tier: Some(2),
11+
host_tools: Some(false),
1212
std: None,
1313
},
1414
pointer_width: 64,

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

+4-4
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,10 @@ pub fn target() -> Target {
1818
Target {
1919
llvm_target: "i686-pc-windows-gnu".into(),
2020
metadata: crate::spec::TargetMetadata {
21-
description: None,
22-
tier: None,
23-
host_tools: None,
24-
std: None,
21+
description: Some("32-bit MinGW (Windows 7+)".into()),
22+
tier: Some(1),
23+
host_tools: Some(true),
24+
std: Some(true),
2525
},
2626
pointer_width: 32,
2727
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-4
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,10 @@ pub fn target() -> Target {
44
Target {
55
llvm_target: "loongarch64-unknown-linux-gnu".into(),
66
metadata: crate::spec::TargetMetadata {
7-
description: None,
8-
tier: None,
9-
host_tools: None,
10-
std: None,
7+
description: Some("LoongArch64 Linux, LP64D ABI (kernel 5.19, glibc 2.36)".into()),
8+
tier: Some(2),
9+
host_tools: Some(true),
10+
std: Some(true),
1111
},
1212
pointer_width: 64,
1313
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

+4-4
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,10 @@ pub fn target() -> Target {
1111
Target {
1212
llvm_target: "powerpc64-ibm-aix".into(),
1313
metadata: crate::spec::TargetMetadata {
14-
description: None,
15-
tier: None,
16-
host_tools: None,
17-
std: None,
14+
description: Some("64-bit AIX (7.2 and newer)".into()),
15+
tier: Some(3),
16+
host_tools: Some(true),
17+
std: Some(true),
1818
},
1919
pointer_width: 64,
2020
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

+27-4
Original file line numberDiff line numberDiff line change
@@ -1147,14 +1147,17 @@ impl Step for RustcBook {
11471147

11481148
/// Builds the rustc book.
11491149
///
1150-
/// The lints are auto-generated by a tool, and then merged into the book
1150+
/// The lints and target docs are auto-generated by a tool, and then merged into the book
11511151
/// in the "md-doc" directory in the build output directory. Then
11521152
/// "rustbook" is used to convert it to HTML.
11531153
fn run(self, builder: &Builder<'_>) {
11541154
let out_base = builder.md_doc_out(self.target).join("rustc");
11551155
t!(fs::create_dir_all(&out_base));
1156-
let out_listing = out_base.join("src/lints");
1157-
builder.cp_link_r(&builder.src.join("src/doc/rustc"), &out_base);
1156+
let out_lints_listing = out_base.join("src/lints");
1157+
let out_src_listing = out_base.join("src");
1158+
1159+
// target-docs will be modifying the files in-place, so we need an actual copy.
1160+
builder.cp_r(&builder.src.join("src/doc/rustc"), &out_base);
11581161
builder.info(&format!("Generating lint docs ({})", self.target));
11591162

11601163
let rustc = builder.rustc(self.compiler);
@@ -1165,7 +1168,7 @@ impl Step for RustcBook {
11651168
cmd.arg("--src");
11661169
cmd.arg(builder.src.join("compiler"));
11671170
cmd.arg("--out");
1168-
cmd.arg(&out_listing);
1171+
cmd.arg(&out_lints_listing);
11691172
cmd.arg("--rustc");
11701173
cmd.arg(&rustc);
11711174
cmd.arg("--rustc-target").arg(self.target.rustc_target_arg());
@@ -1194,6 +1197,26 @@ impl Step for RustcBook {
11941197
builder.run(&mut cmd);
11951198
drop(doc_generator_guard);
11961199

1200+
// Run target-docs generator
1201+
let mut cmd = builder.tool_cmd(Tool::TargetDocs);
1202+
cmd.arg(builder.src.join("src/doc/rustc/target_infos"));
1203+
cmd.arg(&out_src_listing);
1204+
cmd.env("RUSTC", &rustc);
1205+
// For now, we just check that the files are correct but do not generate output.
1206+
// Let the user override it to TARGET_CHECK_ONLY=0 for testing, but use 1 by default.
1207+
// See https://github.com/rust-lang/rust/issues/120745 for more info.
1208+
cmd.env("TARGET_CHECK_ONLY", std::env::var("TARGET_CHECK_ONLY").unwrap_or("1".to_owned()));
1209+
1210+
let doc_generator_guard = builder.msg(
1211+
Kind::Run,
1212+
self.compiler.stage,
1213+
"target-docs",
1214+
self.compiler.host,
1215+
self.target,
1216+
);
1217+
builder.run(&mut cmd);
1218+
drop(doc_generator_guard);
1219+
11971220
// Run rustbook/mdbook to generate the HTML pages.
11981221
builder.ensure(RustbookSrc {
11991222
target: self.target,

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

+1
Original file line numberDiff line numberDiff line change
@@ -301,6 +301,7 @@ bootstrap_tool!(
301301
RustdocTheme, "src/tools/rustdoc-themes", "rustdoc-themes";
302302
ExpandYamlAnchors, "src/tools/expand-yaml-anchors", "expand-yaml-anchors";
303303
LintDocs, "src/tools/lint-docs", "lint-docs";
304+
TargetDocs, "src/tools/target-docs", "target-docs";
304305
JsonDocCk, "src/tools/jsondocck", "jsondocck";
305306
JsonDocLint, "src/tools/jsondoclint", "jsondoclint";
306307
HtmlChecker, "src/tools/html-checker", "html-checker";

‎src/bootstrap/src/lib.rs

+41-4
Original file line numberDiff line numberDiff line change
@@ -1668,10 +1668,23 @@ impl Build {
16681668
/// You can neither rely on this being a copy nor it being a link,
16691669
/// so do not write to dst.
16701670
pub fn copy_link(&self, src: &Path, dst: &Path) {
1671-
self.copy_link_internal(src, dst, false);
1671+
self.copy_internal(src, dst, false, true);
16721672
}
16731673

1674-
fn copy_link_internal(&self, src: &Path, dst: &Path, dereference_symlinks: bool) {
1674+
/// Links a file from `src` to `dst`.
1675+
/// Unlike, [`Build::copy_link`], this makes an actual copy, which is usually not required,
1676+
/// so `copy_link` should be used instead if possible.
1677+
pub fn copy(&self, src: &Path, dst: &Path) {
1678+
self.copy_internal(src, dst, false, false);
1679+
}
1680+
1681+
fn copy_internal(
1682+
&self,
1683+
src: &Path,
1684+
dst: &Path,
1685+
dereference_symlinks: bool,
1686+
link_if_possible: bool,
1687+
) {
16751688
if self.config.dry_run() {
16761689
return;
16771690
}
@@ -1691,7 +1704,7 @@ impl Build {
16911704
return;
16921705
}
16931706
}
1694-
if let Ok(()) = fs::hard_link(&src, dst) {
1707+
if link_if_possible && fs::hard_link(&src, dst).is_ok() {
16951708
// Attempt to "easy copy" by creating a hard link
16961709
// (symlinks don't work on windows), but if that fails
16971710
// just fall back to a slow `copy` operation.
@@ -1726,6 +1739,28 @@ impl Build {
17261739
}
17271740
}
17281741

1742+
/// Copies the `src` directory recursively to `dst`. Both are assumed to exist
1743+
/// when this function is called.
1744+
/// Unlike, [`Build::cp_link_r`], this makes an actual copy, which is usually not required,
1745+
/// so `cp_link_r` should be used instead if possible.
1746+
pub fn cp_r(&self, src: &Path, dst: &Path) {
1747+
if self.config.dry_run() {
1748+
return;
1749+
}
1750+
for f in self.read_dir(src) {
1751+
let path = f.path();
1752+
let name = path.file_name().unwrap();
1753+
let dst = dst.join(name);
1754+
if t!(f.file_type()).is_dir() {
1755+
t!(fs::create_dir_all(&dst));
1756+
self.cp_r(&path, &dst);
1757+
} else {
1758+
let _ = fs::remove_file(&dst);
1759+
self.copy(&path, &dst);
1760+
}
1761+
}
1762+
}
1763+
17291764
/// Copies the `src` directory recursively to `dst`. Both are assumed to exist
17301765
/// when this function is called.
17311766
/// Will attempt to use hard links if possible and fall back to copying.
@@ -1779,7 +1814,9 @@ impl Build {
17791814
if !src.exists() {
17801815
panic!("ERROR: File \"{}\" not found!", src.display());
17811816
}
1782-
self.copy_link_internal(src, &dst, true);
1817+
1818+
self.copy_internal(src, &dst, true, true);
1819+
17831820
chmod(&dst, perms);
17841821
}
17851822

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

+4
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,10 @@ ENV EXTERNAL_LLVM 1
4949
# be missing.
5050
ENV IS_NOT_LATEST_LLVM 1
5151

52+
53+
# Ubuntu LLVM 17 does not have support for experimental targets like csky.
54+
ENV TARGET_DOCS_SKIP_TARGETS "csky-unknown-linux-gnuabiv2,csky-unknown-linux-gnuabiv2hf"
55+
5256
# Using llvm-link-shared due to libffi issues -- see #34486
5357
ENV RUST_CONFIGURE_ARGS \
5458
--build=x86_64-unknown-linux-gnu \

‎src/doc/rustc/src/SUMMARY.md

+3
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,9 @@
6969
- [x86_64-fortanix-unknown-sgx](platform-support/x86_64-fortanix-unknown-sgx.md)
7070
- [x86_64-unknown-none](platform-support/x86_64-unknown-none.md)
7171
- [x86_64h-apple-darwin](platform-support/x86_64h-apple-darwin.md)
72+
<!-- - [List of Targets](platform-support/targets.md) (see #120745) -->
73+
<!-- TARGET_LIST SECTION START -->
74+
<!-- TARGET_LIST SECTION END -->
7275
- [Targets](targets/index.md)
7376
- [Built-in Targets](targets/built-in.md)
7477
- [Custom Targets](targets/custom.md)

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

+12-1
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,9 @@ target | notes
4040
`x86_64-pc-windows-gnu` | 64-bit MinGW (Windows 10+)
4141
`x86_64-pc-windows-msvc` | 64-bit MSVC (Windows 10+)
4242
`x86_64-unknown-linux-gnu` | 64-bit Linux (kernel 3.2+, glibc 2.17+)
43+
<!-- TIER1HOST SECTION START -->
44+
<!-- See `src/tools/target-docs` -->
45+
<!-- TIER1HOST SECTION END -->
4346

4447
[^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].
4548

@@ -102,7 +105,9 @@ target | notes
102105
`x86_64-unknown-illumos` | illumos
103106
`x86_64-unknown-linux-musl` | 64-bit Linux with musl 1.2.3
104107
[`x86_64-unknown-netbsd`](platform-support/netbsd.md) | NetBSD/amd64
105-
108+
<!-- TIER2HOST SECTION START -->
109+
<!-- See `src/tools/target-docs` -->
110+
<!-- TIER2HOST SECTION END -->
106111
## Tier 2 without Host Tools
107112

108113
Tier 2 targets can be thought of as "guaranteed to build". The Rust project
@@ -201,6 +206,9 @@ target | std | notes
201206
[`x86_64-unknown-none`](platform-support/x86_64-unknown-none.md) | * | Freestanding/bare-metal x86_64, softfloat
202207
`x86_64-unknown-redox` | ✓ | Redox OS
203208
[`x86_64-unknown-uefi`](platform-support/unknown-uefi.md) | ? | 64-bit UEFI
209+
<!-- TIER2 SECTION START -->
210+
<!-- See `src/tools/target-docs` -->
211+
<!-- TIER2 SECTION END -->
204212

205213
[^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].
206214
[wasi-rename]: https://github.com/rust-lang/compiler-team/issues/607
@@ -379,5 +387,8 @@ target | std | host | notes
379387
[`x86_64-win7-windows-msvc`](platform-support/win7-windows-msvc.md) | ✓ | | 64-bit Windows 7 support
380388
`x86_64-wrs-vxworks` | ? | |
381389
[`x86_64h-apple-darwin`](platform-support/x86_64h-apple-darwin.md) | ✓ | ✓ | macOS with late-gen Intel (at least Haswell)
390+
<!-- TIER3 SECTION START -->
391+
<!-- See `src/tools/target-docs` -->
392+
<!-- TIER3 SECTION END -->
382393

383394
[runs on NVIDIA GPUs]: https://github.com/japaric-archived/nvptx#targets

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

+10
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,15 @@
11
# `powerpc64-ibm-aix`
22

3+
<!--
4+
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5+
6+
***WARNING***
7+
This target has already been migrated to the new target docs system: #120745
8+
When editing this file, make sure that you keep the equivalent docs in ../../target_infos in sync!!!
9+
10+
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
11+
-->
12+
313
**Tier: 3**
414

515
Rust for AIX operating system, currently only 64-bit PowerPC is supported.

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

+10
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,16 @@
22
- aarch64-apple-tvos
33
- x86_64-apple-tvos
44

5+
<!--
6+
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7+
8+
***WARNING***
9+
This target has already been migrated to the new target docs system: #120745
10+
When editing this file, make sure that you keep the equivalent docs in ../../target_infos in sync!!!
11+
12+
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
13+
-->
14+
515
**Tier: 3**
616

717
Apple tvOS targets:

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

+11
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,16 @@
11
# loongarch\*-unknown-linux-\*
22

3+
<!--
4+
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5+
6+
***WARNING***
7+
This target has already been migrated to the new target docs system: #120745
8+
When editing this file, make sure that you keep the equivalent docs in ../../target_infos in sync!!!
9+
10+
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
11+
-->
12+
13+
314
**Tier: 2**
415

516
[LoongArch] is a new RISC ISA developed by Loongson Technology Corporation Limited.

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

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# List of all targets
2+
3+
An alphabetical list of all targets.
4+
5+
<!-- TARGET SECTION START -->
6+
<!-- See `src/tools/target-docs` -->
7+
<!-- TARGET SECTION END -->

0 commit comments

Comments
 (0)