From 470b49bac9ca58e48a92a0f69aef2745413fe9b4 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Tue, 2 Nov 2021 13:34:26 +0100 Subject: [PATCH 1/5] Clarify how to quote and respond to the target tier policy requirements Several times, people have seemed unclear on how to respond to some of the policy requirements, particularly those that just state things the target developers must *not* do (e.g. not posting to PRs that break the target). Add a note that such requirements just need acknowledgement, nothing more. Make quoting and responding a "must" rather than an "is encouraged to", since it's easier to review the requirements that way. --- src/doc/rustc/src/target-tier-policy.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/doc/rustc/src/target-tier-policy.md b/src/doc/rustc/src/target-tier-policy.md index cc02b294b44..191021dea97 100644 --- a/src/doc/rustc/src/target-tier-policy.md +++ b/src/doc/rustc/src/target-tier-policy.md @@ -62,8 +62,10 @@ not preclude an existing target's maintainers using issues (on the Rust repository or otherwise) to track requirements that have not yet been met, as appropriate; however, before officially proposing the introduction or promotion of a target, it should meet all of the necessary requirements. A target -proposal is encouraged to quote the corresponding requirements verbatim as part -of explaining how the target meets those requirements. +proposal must quote the corresponding requirements verbatim and respond to them +as part of explaining how the target meets those requirements. (For the +requirements that simply state that the target or the target developers must +not do something, it suffices to acknowledge the requirement.) For a list of all supported targets and their corresponding tiers ("tier 3", "tier 2", "tier 2 with host tools", "tier 1", or "tier 1 with host tools"), see From 9a016badfae61b7527f94168c2829e775d83401b Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Tue, 2 Nov 2021 13:38:51 +0100 Subject: [PATCH 2/5] Clarify dependency requirements in the face of cross-compilation The requirement on dependencies was phrased in terms of "host tools", but it was also intended to apply equally to targets that only support cross-compilation. Only the exception (for libraries commonly needed for binaries on the target) was intended to apply to host tools. Reword the requirement to talk about the dependencies required for "compiling, linking,and emitting functional binaries, libraries, or other code for the target", rather than generically in terms of dependencies for rustc/cargo. This doesn't change the net effect of the requirements, since other requirements already stated that the target can't make the Rust toolchain depend on proprietary libraries. However, this should make the requirements clearer. --- src/doc/rustc/src/target-tier-policy.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/src/doc/rustc/src/target-tier-policy.md b/src/doc/rustc/src/target-tier-policy.md index 191021dea97..025f7e3984e 100644 --- a/src/doc/rustc/src/target-tier-policy.md +++ b/src/doc/rustc/src/target-tier-policy.md @@ -141,17 +141,19 @@ approved by the appropriate team for that shared code before acceptance. or binary. In other words, the introduction of the target must not cause a user installing or running a version of Rust or the Rust tools to be subject to any new license requirements. - - If the target supports building host tools (such as `rustc` or `cargo`), - those host tools must not depend on proprietary (non-FOSS) libraries, other - than ordinary runtime libraries supplied by the platform and commonly used - by other binaries built for the target. For instance, `rustc` built for the - target may depend on a common proprietary C runtime library or console - output library, but must not depend on a proprietary code generation - library or code optimization library. Rust's license permits such - combinations, but the Rust project has no interest in maintaining such - combinations within the scope of Rust itself, even at tier 3. - - Targets should not require proprietary (non-FOSS) components to link a - functional binary or library. + - Compiling, linking, and emitting functional binaries, libraries, or other + code for the target (whether hosted on the target itself or cross-compiling + from another target) must not depend on proprietary (non-FOSS) libraries. + Host tools built for the target itself may depend on the ordinary runtime + libraries supplied by the platform and commonly used by other applications + built for the target, but those libraries must not be required for code + generation for the target; cross-compilation to the target must not require + such libraries at all. For instance, `rustc` built for the target may + depend on a common proprietary C runtime library or console output library, + but must not depend on a proprietary code generation library or code + optimization library. Rust's license permits such combinations, but the + Rust project has no interest in maintaining such combinations within the + scope of Rust itself, even at tier 3. - "onerous" here is an intentionally subjective term. At a minimum, "onerous" legal/licensing terms include but are *not* limited to: non-disclosure requirements, non-compete requirements, contributor license agreements From 1aeb3f9cadd940825e1e0ce167a8852e0681c20d Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Tue, 2 Nov 2021 13:47:08 +0100 Subject: [PATCH 3/5] Clarify documentation about running binaries The requirement for target documentation talks about "running tests", but tier 3 targets often don't support running the full testsuite, and in practice the documentation for how to run an individual binary may be more useful. Change "running tests" to "running binaries, or running tests". --- src/doc/rustc/src/target-tier-policy.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/doc/rustc/src/target-tier-policy.md b/src/doc/rustc/src/target-tier-policy.md index 025f7e3984e..5f22ad2b16f 100644 --- a/src/doc/rustc/src/target-tier-policy.md +++ b/src/doc/rustc/src/target-tier-policy.md @@ -188,9 +188,9 @@ approved by the appropriate team for that shared code before acceptance. target not implementing those portions. - The target must provide documentation for the Rust community explaining how to build for the target, using cross-compilation if possible. If the target - supports running tests (even if they do not pass), the documentation must - explain how to run tests for the target, using emulation if possible or - dedicated hardware if necessary. + supports running binaries, or running tests (even if they do not pass), the + documentation must explain how to run such binaries or tests for the target, + using emulation if possible or dedicated hardware if necessary. - Tier 3 targets must not impose burden on the authors of pull requests, or other developers in the community, to maintain the target. In particular, do not post comments (automated or manual) on a PR that derail or suggest a From 10420ef94514b6319ab87442bfbc7fd465c3394b Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Tue, 2 Nov 2021 13:52:39 +0100 Subject: [PATCH 4/5] Point to platform-support/ for target-specific documentation Explain that target-specific documentation should appear in a subdirectory of platform-support, with a link from the target's entry on the platform-support page. --- src/doc/rustc/src/target-tier-policy.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/doc/rustc/src/target-tier-policy.md b/src/doc/rustc/src/target-tier-policy.md index 5f22ad2b16f..f82a8edd108 100644 --- a/src/doc/rustc/src/target-tier-policy.md +++ b/src/doc/rustc/src/target-tier-policy.md @@ -71,6 +71,12 @@ For a list of all supported targets and their corresponding tiers ("tier 3", "tier 2", "tier 2 with host tools", "tier 1", or "tier 1 with host tools"), see [platform support](platform-support.md). +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. + 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 for promotion to the next higher tier; this is true even if a target meets the From f863e4cc301c7ab7c97b86ad142474989789badc Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Tue, 2 Nov 2021 14:07:52 +0100 Subject: [PATCH 5/5] 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