Skip to content

Commit 10d8ab5

Browse files
workingjubileeworkingjubilee
authored
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`
2 parents 101525a + d3fc623 commit 10d8ab5

26 files changed

+1153
-24
lines changed

‎Cargo.lock

Lines changed: 36 additions & 0 deletions
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

Lines changed: 1 addition & 0 deletions
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

Lines changed: 3 additions & 3 deletions
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

Lines changed: 4 additions & 4 deletions
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

Lines changed: 4 additions & 4 deletions
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

Lines changed: 4 additions & 4 deletions
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

Lines changed: 27 additions & 4 deletions
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

Lines changed: 1 addition & 0 deletions
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

Lines changed: 41 additions & 4 deletions
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

Lines changed: 4 additions & 0 deletions
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

Lines changed: 3 additions & 0 deletions
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

Lines changed: 12 additions & 1 deletion
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

Lines changed: 10 additions & 0 deletions
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

Lines changed: 10 additions & 0 deletions
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

Lines changed: 11 additions & 0 deletions
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

Lines changed: 7 additions & 0 deletions
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)