mirror of
https://github.com/Noratrieb/target-tier-docs-experiment.git
synced 2026-01-14 08:30:12 +01:00
57 lines
2.2 KiB
Markdown
57 lines
2.2 KiB
Markdown
# 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
|
|
tier: "1"
|
|
maintainers: ["@someone"]
|
|
metadata:
|
|
- target: "i686-pc-windows-gnu"
|
|
notes: "32-bit MinGW (Windows 7+)"
|
|
std: true
|
|
host: true
|
|
footnotes:
|
|
- name: "x86_32-floats-return-ABI"
|
|
content: |
|
|
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][https://github.com/rust-lang/rust/issues/114479].
|
|
- name: "windows-support"
|
|
content: "Only Windows 10 currently undergoes automated testing. Earlier versions of Windows rely on testing and support from the community."
|
|
```
|
|
|
|
The top level keys are:
|
|
|
|
- `tier` (optional): `1`, `2` or `3`
|
|
- `maintainers` (optional): list of strings
|
|
|
|
There is also `metadata`, which is specific to every single target and not just a target "group" (the glob).
|
|
|
|
`metadata` has the following properties:
|
|
|
|
- `target`: the target name
|
|
- `notes`: a string containing a short description of the target for the table
|
|
- `std`: `true`, `false`, `unknown`, whether the target has `std`
|
|
- `host`: `true`, `false`, `unknown`, whether the target has host tools
|
|
- `footnotes` (optional): a list of footnotes, where every footnote has a `name` and `content`. These are used in the table.
|