Skip to content

Commit

Permalink
Rollup merge of #90498 - joshtriplett:target-tier-policy-draft-update…
Browse files Browse the repository at this point in the history
…s, r=Mark-Simulacrum

Clarifications in the target tier policy

We've added several targets since the introduction of the target tier policy. Based on experiences of those adding such targets, and discussions around such additions, clarify the target tier policy to make it easier to follow and work with.

None of these changes substantively change the requirements on targets. (In some cases the changes do direct target submitters to follow specific process requirements for the addition of a target, such as how to respond to requirements, where to put target-specific documentation, or what should appear in that documentation. Those changes are procedural in nature and document the procedures we already direct people to follow.)

- 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.
- Clarify dependency requirements in the face of cross-compilation. I previously phrased this confusingly in terms of "host tools", since that is the case where an exception applies (allowing proprietary target libraries commonly used by binaries for the target). Rephrase it to apply equally to cross-compilation. This doesn't change the net effect of the requirements, since other requirements already cover the dependencies of the Rust toolchain.
- 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".
- Explain where to place target-specific documentation (a subdirectory of platform-support, with a link from the platform-support entry for the target).
- Add a template for target-specific documentation.
  • Loading branch information
matthiaskrgr authored Jan 17, 2022
2 parents ee5d8d3 + f863e4c commit 67bcbde
Show file tree
Hide file tree
Showing 3 changed files with 80 additions and 16 deletions.
1 change: 1 addition & 0 deletions src/doc/rustc/src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
- [x86_64-unknown-none](platform-support/x86_64-unknown-none.md)
Expand Down
52 changes: 52 additions & 0 deletions src/doc/rustc/src/platform-support/TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# `target-name-here`

**Tier: 3**

One-sentence description of the target (e.g. CPU, OS)

## Target maintainers

- Some Person, `[email protected]`, 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.)
43 changes: 27 additions & 16 deletions src/doc/rustc/src/target-tier-policy.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,13 +62,22 @@ 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
[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). 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
for promotion to the next higher tier; this is true even if a target meets the
Expand Down Expand Up @@ -139,17 +148,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
Expand Down Expand Up @@ -184,9 +195,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
Expand Down

0 comments on commit 67bcbde

Please sign in to comment.