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:

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.