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:
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,2or3maintainers(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 namenotes: a string containing a short description of the target for the tablestd:true,false,unknown, whether the target hasstdhost:true,false,unknown, whether the target has host toolsfootnotes(optional): a list of footnotes, where every footnote has anameandcontent. These are used in the table.