Skip to content

Commit 1df05c2

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

26 files changed

+1207
-24
lines changed

Diff for: ‎Cargo.lock

+30
Original file line numberDiff line numberDiff line change
@@ -5057,6 +5057,19 @@ dependencies = [
50575057
"serde",
50585058
]
50595059

5060+
[[package]]
5061+
name = "serde_yaml"
5062+
version = "0.9.31"
5063+
source = "registry+https://github.com./rust-lang/crates.io-index"
5064+
checksum = "adf8a49373e98a4c5f0ceb5d05aa7c648d75f63774981ed95b7c7443bbd50c6e"
5065+
dependencies = [
5066+
"indexmap",
5067+
"itoa",
5068+
"ryu",
5069+
"serde",
5070+
"unsafe-libyaml",
5071+
]
5072+
50605073
[[package]]
50615074
name = "sha1"
50625075
version = "0.10.6"
@@ -5419,6 +5432,17 @@ dependencies = [
54195432
"xattr",
54205433
]
54215434

5435+
[[package]]
5436+
name = "target-docs"
5437+
version = "0.1.0"
5438+
dependencies = [
5439+
"eyre",
5440+
"glob",
5441+
"serde",
5442+
"serde_json",
5443+
"serde_yaml",
5444+
]
5445+
54225446
[[package]]
54235447
name = "tempfile"
54245448
version = "3.10.1"
@@ -6065,6 +6089,12 @@ dependencies = [
60656089
"diff",
60666090
]
60676091

6092+
[[package]]
6093+
name = "unsafe-libyaml"
6094+
version = "0.2.10"
6095+
source = "registry+https://github.com./rust-lang/crates.io-index"
6096+
checksum = "ab4c90930b95a82d00dc9e9ac071b4991924390d46cbd0dfe566148667605e4b"
6097+
60686098
[[package]]
60696099
name = "unstable-book-gen"
60706100
version = "0.1.0"

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

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

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

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

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

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

+34-4
Original file line numberDiff line numberDiff line change
@@ -1147,14 +1147,24 @@ 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<'_>) {
1154+
// The rustc book invokes rustc in its build process and relies on it being the in-tree rustc.
1155+
// (by requiring that the targets match and also that nightly flags can be used)
1156+
// Using the bootstrap compiler for this doesn't work.
1157+
if builder.top_stage < 1 {
1158+
crate::fail("building the rustc book with stage 0 is not supported, use --stage 1");
1159+
}
1160+
11541161
let out_base = builder.md_doc_out(self.target).join("rustc");
11551162
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);
1163+
let out_lints_listing = out_base.join("src/lints");
1164+
let out_src_listing = out_base.join("src");
1165+
1166+
// target-docs will be modifying the files in-place, so we need an actual copy.
1167+
builder.cp_r(&builder.src.join("src/doc/rustc"), &out_base);
11581168
builder.info(&format!("Generating lint docs ({})", self.target));
11591169

11601170
let rustc = builder.rustc(self.compiler);
@@ -1165,7 +1175,7 @@ impl Step for RustcBook {
11651175
cmd.arg("--src");
11661176
cmd.arg(builder.src.join("compiler"));
11671177
cmd.arg("--out");
1168-
cmd.arg(&out_listing);
1178+
cmd.arg(&out_lints_listing);
11691179
cmd.arg("--rustc");
11701180
cmd.arg(&rustc);
11711181
cmd.arg("--rustc-target").arg(self.target.rustc_target_arg());
@@ -1194,6 +1204,26 @@ impl Step for RustcBook {
11941204
builder.run(&mut cmd);
11951205
drop(doc_generator_guard);
11961206

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

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

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

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

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

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

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

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

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

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