Skip to content

Commit 1b9afad

Browse files
NoratriebNoratrieb
committed
Introduce infrastructure for generating target docs
1 parent 502ce82 commit 1b9afad

File tree

17 files changed

+1092
-3
lines changed

17 files changed

+1092
-3
lines changed

‎Cargo.lock

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1636,6 +1636,12 @@ version = "0.3.1"
16361636
source = "registry+https://github.com/rust-lang/crates.io-index"
16371637
checksum = "d2fabcfbdc87f4758337ca535fb41a6d701b65693ce38287d856d1674551ec9b"
16381638

1639+
[[package]]
1640+
name = "glob-match"
1641+
version = "0.2.1"
1642+
source = "registry+https://github.com/rust-lang/crates.io-index"
1643+
checksum = "9985c9503b412198aa4197559e9a318524ebc4519c229bfa05a535828c950b9d"
1644+
16391645
[[package]]
16401646
name = "globset"
16411647
version = "0.4.13"
@@ -5026,6 +5032,19 @@ dependencies = [
50265032
"serde",
50275033
]
50285034

5035+
[[package]]
5036+
name = "serde_yaml"
5037+
version = "0.9.31"
5038+
source = "registry+https://github.com/rust-lang/crates.io-index"
5039+
checksum = "adf8a49373e98a4c5f0ceb5d05aa7c648d75f63774981ed95b7c7443bbd50c6e"
5040+
dependencies = [
5041+
"indexmap",
5042+
"itoa",
5043+
"ryu",
5044+
"serde",
5045+
"unsafe-libyaml",
5046+
]
5047+
50295048
[[package]]
50305049
name = "sha1"
50315050
version = "0.10.6"
@@ -5372,6 +5391,16 @@ dependencies = [
53725391
"xattr",
53735392
]
53745393

5394+
[[package]]
5395+
name = "target-docs"
5396+
version = "0.1.0"
5397+
dependencies = [
5398+
"eyre",
5399+
"glob-match",
5400+
"serde",
5401+
"serde_yaml",
5402+
]
5403+
53755404
[[package]]
53765405
name = "tempfile"
53775406
version = "3.10.0"
@@ -5991,6 +6020,12 @@ dependencies = [
59916020
"diff",
59926021
]
59936022

6023+
[[package]]
6024+
name = "unsafe-libyaml"
6025+
version = "0.2.10"
6026+
source = "registry+https://github.com/rust-lang/crates.io-index"
6027+
checksum = "ab4c90930b95a82d00dc9e9ac071b4991924390d46cbd0dfe566148667605e4b"
6028+
59946029
[[package]]
59956030
name = "unstable-book-gen"
59966031
version = "0.1.0"

‎Cargo.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ members = [
4444
"src/tools/rustdoc-gui-test",
4545
"src/tools/opt-dist",
4646
"src/tools/coverage-dump",
47+
"src/tools/target-docs",
4748
]
4849

4950
exclude = [

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

Lines changed: 23 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1139,13 +1139,14 @@ impl Step for RustcBook {
11391139

11401140
/// Builds the rustc book.
11411141
///
1142-
/// The lints are auto-generated by a tool, and then merged into the book
1142+
/// The lints and target docs are auto-generated by a tool, and then merged into the book
11431143
/// in the "md-doc" directory in the build output directory. Then
11441144
/// "rustbook" is used to convert it to HTML.
11451145
fn run(self, builder: &Builder<'_>) {
11461146
let out_base = builder.md_doc_out(self.target).join("rustc");
11471147
t!(fs::create_dir_all(&out_base));
1148-
let out_listing = out_base.join("src/lints");
1148+
let out_lints_listing = out_base.join("src/lints");
1149+
let out_src_listing = out_base.join("src");
11491150
builder.cp_r(&builder.src.join("src/doc/rustc"), &out_base);
11501151
builder.info(&format!("Generating lint docs ({})", self.target));
11511152

@@ -1157,7 +1158,7 @@ impl Step for RustcBook {
11571158
cmd.arg("--src");
11581159
cmd.arg(builder.src.join("compiler"));
11591160
cmd.arg("--out");
1160-
cmd.arg(&out_listing);
1161+
cmd.arg(&out_lints_listing);
11611162
cmd.arg("--rustc");
11621163
cmd.arg(&rustc);
11631164
cmd.arg("--rustc-target").arg(&self.target.rustc_target_arg());
@@ -1186,6 +1187,25 @@ impl Step for RustcBook {
11861187
builder.run(&mut cmd);
11871188
drop(doc_generator_guard);
11881189

1190+
// Run target-docs generator
1191+
let mut cmd = builder.tool_cmd(Tool::TargetDocs);
1192+
cmd.arg(builder.src.join("src/doc/rustc/target_infos"));
1193+
cmd.arg(&out_src_listing);
1194+
cmd.env("RUSTC", &rustc);
1195+
// For now, we just check that the files are correct but do not generate output.
1196+
// See #120745 for more info.
1197+
cmd.env("TARGET_CHECK_ONLY", "1");
1198+
1199+
let doc_generator_guard = builder.msg(
1200+
Kind::Run,
1201+
self.compiler.stage,
1202+
"target-docs",
1203+
self.compiler.host,
1204+
self.target,
1205+
);
1206+
builder.run(&mut cmd);
1207+
drop(doc_generator_guard);
1208+
11891209
// Run rustbook/mdbook to generate the HTML pages.
11901210
builder.ensure(RustbookSrc {
11911211
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/doc/rustc/src/SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
- [Platform Support](platform-support.md)
1616
- [Target Tier Policy](target-tier-policy.md)
1717
- [Template for Target-specific Documentation](platform-support/TEMPLATE.md)
18+
- [List of Targets](platform-support/targets.md)
1819
- [arm64e-apple-ios.md](platform-support/arm64e-apple-ios.md)
1920
- [arm64e-apple-darwin.md](platform-support/arm64e-apple-darwin.md)
2021
- [aarch64-apple-ios-sim](platform-support/aarch64-apple-ios-sim.md)

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

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,9 @@ All tier 1 targets with host tools support the full standard library.
3232

3333
target | notes
3434
-------|-------
35+
<!-- TIER1HOST SECTION START -->
36+
<!-- See `src/tools/target-docs` -->
37+
<!-- TIER1HOST SECTION END -->
3538
`aarch64-unknown-linux-gnu` | ARM64 Linux (kernel 4.1, glibc 2.17+) [^missing-stack-probes]
3639
`i686-pc-windows-gnu` | 32-bit MinGW (Windows 7+) [^windows-support] [^x86_32-floats-return-ABI]
3740
`i686-pc-windows-msvc` | 32-bit MSVC (Windows 7+) [^windows-support] [^x86_32-floats-return-ABI]
@@ -92,6 +95,8 @@ so Rustup may install the documentation for a similar tier 1 target instead.
9295

9396
target | notes
9497
-------|-------
98+
<!-- TIER2HOST SECTION START -->
99+
<!-- TIER2HOST SECTION END -->
95100
`aarch64-apple-darwin` | ARM64 macOS (11.0+, Big Sur+)
96101
`aarch64-pc-windows-msvc` | ARM64 Windows MSVC
97102
`aarch64-unknown-linux-musl` | ARM64 Linux with MUSL
@@ -138,6 +143,8 @@ so Rustup may install the documentation for a similar tier 1 target instead.
138143

139144
target | std | notes
140145
-------|:---:|-------
146+
<!-- TIER2 SECTION START -->
147+
<!-- TIER2 SECTION END -->
141148
`aarch64-apple-ios` | ✓ | ARM64 iOS
142149
[`aarch64-apple-ios-sim`](platform-support/aarch64-apple-ios-sim.md) | ✓ | Apple iOS Simulator on ARM64
143150
`aarch64-fuchsia` | ✓ | Alias for `aarch64-unknown-fuchsia`
@@ -234,6 +241,8 @@ host tools.
234241

235242
target | std | host | notes
236243
-------|:---:|:----:|-------
244+
<!-- TIER3 SECTION START -->
245+
<!-- TIER3 SECTION END -->
237246
[`arm64e-apple-ios`](platform-support/arm64e-apple-ios.md) | ✓ | | ARM64e Apple iOS
238247
[`arm64e-apple-darwin`](platform-support/arm64e-apple-darwin.md) | ✓ | ✓ | ARM64e Apple Darwin
239248
`aarch64-apple-ios-macabi` | ? | | Apple Catalyst on ARM64

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

‎src/doc/rustc/target_infos/*-apple-tvos.md

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
tier: "2"
3+
maintainers: ["@thomcc"]
4+
metadata:
5+
- target: "aarch64-apple-tvos"
6+
notes: "ARM64 tvOS"
7+
std: "unknown"
8+
host: false
9+
---
10+
11+
## Overview
12+
13+
Apple tvOS targets:
14+
- Apple tvOS on aarch64
15+
- Apple tvOS Simulator on x86_64
16+
17+
## Requirements
18+
19+
These targets are cross-compiled. You will need appropriate versions of Xcode
20+
and the SDKs for tvOS (`AppleTVOS.sdk`) and/or the tvOS Simulator
21+
(`AppleTVSimulator.sdk`) to build a toolchain and target these platforms.
22+
23+
The targets support most (see below) of the standard library including the
24+
allocator to the best of my knowledge, however they are very new, not yet
25+
well-tested, and it is possible that there are various bugs.
26+
27+
In theory we support back to tvOS version 7.0, although the actual minimum
28+
version you can target may be newer than this, for example due to the versions
29+
of Xcode and your SDKs.
30+
31+
As with the other Apple targets, `rustc` respects the common environment
32+
variables used by Xcode to configure this, in this case
33+
`TVOS_DEPLOYMENT_TARGET`.
34+
35+
As mentioned, "most" of the standard library is supported, which means that some portions
36+
are known to be unsupported. The following APIs are currently known to have
37+
missing or incomplete support:
38+
39+
- `std::process::Command`'s API will return an error if it is configured in a
40+
manner which cannot be performed using `posix_spawn` -- this is because the
41+
more flexible `fork`/`exec`-based approach is prohibited on these platforms in
42+
favor of `posix_spawn{,p}` (which still probably will get you rejected from
43+
app stores, so is likely sideloading-only). A concrete set of cases where this
44+
will occur is difficult to enumerate (and would quickly become stale), but in
45+
some cases it may be worked around by tweaking the manner in which `Command`
46+
is invoked.
47+
48+
## Building the target
49+
50+
The targets can be built by enabling them for a `rustc` build in `config.toml`, by adding, for example:
51+
52+
```toml
53+
[build]
54+
build-stage = 1
55+
target = ["aarch64-apple-tvos", "x86_64-apple-tvos", "aarch64-apple-tvos-sim"]
56+
```
57+
58+
It's possible that cargo under `-Zbuild-std` may also be used to target them.
59+
60+
## Building Rust programs
61+
62+
*Note: Building for this target requires the corresponding TVOS SDK, as provided by Xcode.*
63+
64+
Rust programs can be built for these targets
65+
66+
```text
67+
$ rustc --target aarch64-apple-tvos your-code.rs
68+
...
69+
$ rustc --target x86_64-apple-tvos your-code.rs
70+
...
71+
$ rustc --target aarch64-apple-tvos-sim your-code.rs
72+
```
73+
74+
## Testing
75+
76+
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.
77+
78+
It hopefully will be possible to improve this in the future.
79+
80+
## Cross compilation
81+
82+
This target can be cross-compiled from x86_64 or aarch64 macOS hosts.
83+
84+
Other hosts are not supported for cross-compilation, but might work when also providing the required Xcode SDK.

‎src/doc/rustc/target_infos/i686-pc-windows-gnu.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
tier: "1"
3+
metadata:
4+
- target: "i686-pc-windows-gnu"
5+
notes: "32-bit MinGW (Windows 7+)"
6+
std: true
7+
host: true
8+
footnotes:
9+
- name: "x86_32-floats-return-ABI"
10+
content: |
11+
Due to limitations of the C ABI, floating-point support on `i686` targets is non-compliant:
12+
floating-point return values are passed via an x87 register, so NaN payload bits can be lost.
13+
See [issue #114479][https://github.com/rust-lang/rust/issues/114479].
14+
- name: "windows-support"
15+
content: "Only Windows 10 currently undergoes automated testing. Earlier versions of Windows rely on testing and support from the community."
16+
---
17+
18+
## Overview
19+
20+
32-bit Windows using MinGW.

‎src/doc/rustc/target_infos/loongarch*-unknown-linux-*.md

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
---
2+
tier: "2"
3+
maintainers:
4+
- "[WANG Rui](https://github.com/heiher) `wangrui@loongson.cn`"
5+
- "[ZHAI Xiang](https://github.com/xiangzhai) `zhaixiang@loongson.cn`"
6+
- "[ZHAI Xiaojuan](https://github.com/zhaixiaojuan) `zhaixiaojuan@loongson.cn`"
7+
- "[WANG Xuerui](https://github.com/xen0n) `git@xen0n.name`"
8+
metadata:
9+
- target: "loongarch64-unknown-linux-gnu"
10+
notes: "LoongArch64 Linux, LP64D ABI (kernel 5.19, glibc 2.36)"
11+
std: true
12+
host: true
13+
---
14+
15+
## Overview
16+
17+
[LoongArch] is a new RISC ISA developed by Loongson Technology Corporation Limited.
18+
19+
[LoongArch]: https://loongson.github.io/LoongArch-Documentation/README-EN.html
20+
21+
The target name follow this format: `<machine>-<vendor>-<os><fabi_suffix>`, where `<machine>` specifies the CPU family/model, `<vendor>` specifies the vendor and `<os>` the operating system name.
22+
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 `<fabi-suffix>`.
23+
24+
| `<fabi-suffix>` | `Description` |
25+
|------------------------|--------------------------------------------------------------------|
26+
| f64 | The base ABI use 64-bits FPRs for parameter passing. (lp64d)|
27+
| f32 | The base ABI uses 32-bit FPRs for parameter passing. (lp64f)|
28+
| sf | The base ABI uses no FPR for parameter passing. (lp64s) |
29+
30+
<br>
31+
32+
|`ABI type(Base ABI/ABI extension)`| `C library` | `kernel` | `target tuple` |
33+
|----------------------------------|-------------|----------|----------------------------------|
34+
| lp64d/base | glibc | linux | loongarch64-unknown-linux-gnu |
35+
| lp64f/base | glibc | linux | loongarch64-unknown-linux-gnuf32 |
36+
| lp64s/base | glibc | linux | loongarch64-unknown-linux-gnusf |
37+
| lp64d/base | musl libc | linux | loongarch64-unknown-linux-musl|
38+
| lp64f/base | musl libc | linux | loongarch64-unknown-linux-muslf32|
39+
| lp64s/base | musl libc | linux | loongarch64-unknown-linux-muslsf |
40+
41+
## Requirements
42+
43+
This target is cross-compiled.
44+
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).
45+
46+
## Building the target
47+
48+
The target can be built by enabling it for a `rustc` build.
49+
50+
```toml
51+
[build]
52+
target = ["loongarch64-unknown-linux-gnu"]
53+
```
54+
55+
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`:
56+
57+
```toml
58+
[target.loongarch64-unknown-linux-gnu]
59+
# ADJUST THIS PATH TO POINT AT YOUR TOOLCHAIN
60+
cc = "/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-gcc"
61+
cxx = "/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-g++"
62+
ar = "/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-ar"
63+
ranlib = "/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-ranlib"
64+
linker = "/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-gcc"
65+
```
66+
67+
## Cross compilation
68+
69+
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.
70+
71+
## Testing
72+
To test a cross-compiled binary on your build system, install the qemu binary that supports the LoongArch architecture and execute the following commands.
73+
```text
74+
CC_loongarch64_unknown_linux_gnu=/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-gcc \
75+
CXX_loongarch64_unknown_linux_gnu=/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-g++ \
76+
AR_loongarch64_unknown_linux_gnu=/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-gcc-ar \
77+
CARGO_TARGET_LOONGARCH64_UNKNOWN_LINUX_GNUN_LINKER=/TOOLCHAIN_PATH/bin/loongarch64-unknown-linux-gnu-gcc \
78+
# SET TARGET SYSTEM LIBRARY PATH
79+
CARGO_TARGET_LOONGARCH64_UNKNOWN_LINUX_GNUN_RUNNER="qemu-loongarch64 -L /TOOLCHAIN_PATH/TARGET_LIBRARY_PATH" \
80+
cargo run --target loongarch64-unknown-linux-gnu --release
81+
```
82+
Tested on x86 architecture, other architectures not tested.
83+
84+
## Building Rust programs
85+
86+
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.
87+
88+
If `rustc` has support for that target and the library artifacts are available, then Rust static libraries can be built for that target:
89+
90+
```shell
91+
$ rustc --target loongarch64-unknown-linux-gnu your-code.rs --crate-type staticlib
92+
$ ls libyour_code.a
93+
```
94+
95+
On Rust Nightly it's possible to build without the target artifacts available:
96+
97+
```text
98+
cargo build -Z build-std --target loongarch64-unknown-linux-gnu
99+
```

0 commit comments

Comments
 (0)