From f863e4cc301c7ab7c97b86ad142474989789badc Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Tue, 2 Nov 2021 14:07:52 +0100 Subject: [PATCH] Add a template for target-specific documentation --- src/doc/rustc/src/SUMMARY.md | 1 + .../rustc/src/platform-support/TEMPLATE.md | 52 +++++++++++++++++++ src/doc/rustc/src/target-tier-policy.md | 5 +- 3 files changed, 56 insertions(+), 2 deletions(-) create mode 100644 src/doc/rustc/src/platform-support/TEMPLATE.md diff --git a/src/doc/rustc/src/SUMMARY.md b/src/doc/rustc/src/SUMMARY.md index 8c418351837..0bf5c9b3de3 100644 --- a/src/doc/rustc/src/SUMMARY.md +++ b/src/doc/rustc/src/SUMMARY.md @@ -13,6 +13,7 @@ - [JSON Output](json.md) - [Tests](tests/index.md) - [Platform Support](platform-support.md) + - [Template for target-specific documentation](platform-support/TEMPLATE.md) - [aarch64-apple-ios-sim](platform-support/aarch64-apple-ios-sim.md) - [\*-kmc-solid_\*](platform-support/kmc-solid.md) - [Target Tier Policy](target-tier-policy.md) diff --git a/src/doc/rustc/src/platform-support/TEMPLATE.md b/src/doc/rustc/src/platform-support/TEMPLATE.md new file mode 100644 index 00000000000..e64783fcf19 --- /dev/null +++ b/src/doc/rustc/src/platform-support/TEMPLATE.md @@ -0,0 +1,52 @@ +# `target-name-here` + +**Tier: 3** + +One-sentence description of the target (e.g. CPU, OS) + +## Target maintainers + +- Some Person, `email@example.org`, https://github.com/... + +## Requirements + +Does the target support host tools, or only cross-compilation? Does the target +support std, or alloc (either with a default allocator, or if the user supplies +an allocator)? + +Document the expectations of binaries built for the target. Do they assume +specific minimum features beyond the baseline of the CPU/environment/etc? What +version of the OS or environment do they expect? + +Are there notable `#[target_feature(...)]` or `-C target-feature=` values that +programs may wish to use? + +What calling convention does `extern "C"` use on the target? + +What format do binaries use by default? ELF, PE, something else? + +## Building the target + +If Rust doesn't build the target by default, how can users build it? Can users +just add it to the `target` list in `config.toml`? + +## Building Rust programs + +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 `core` by using +`build-std` or similar. + +## Testing + +Does the target support running binaries, or do binaries have varying +expectations that prevent having a standard way to run them? If users can run +binaries, can they do so in some common emulator, or do they need native +hardware? Does the target support running the Rust testsuite? + +## Cross-compilation toolchains and C code + +Does the target support C code? If so, what toolchain target should users use +to build compatible C code? (This may match the target triple, or it may be a +toolchain for a different target triple, potentially with specific options or +caveats.) diff --git a/src/doc/rustc/src/target-tier-policy.md b/src/doc/rustc/src/target-tier-policy.md index f82a8edd108..53d0470fa81 100644 --- a/src/doc/rustc/src/target-tier-policy.md +++ b/src/doc/rustc/src/target-tier-policy.md @@ -74,8 +74,9 @@ For a list of all supported targets and their corresponding tiers ("tier 3", Several parts of this policy require providing target-specific documentation. Such documentation should typically appear in a subdirectory of the platform-support section of this rustc manual, with a link from the target's -entry in [platform support](platform-support.md). See other documentation in -that directory for examples. +entry in [platform support](platform-support.md). Use +[TEMPLATE.md](platform-support/TEMPLATE.md) as a base, and see other +documentation in that directory for examples. Note that a target must have already received approval for the next lower tier, and spent a reasonable amount of time at that tier, before making a proposal