Improve documentation when adding a new target #135992

madsmtm · 2025-01-24T13:47:52Z

#133631 (comment) shows that it can be a bit difficult process-wise to add a new target.

I've added a bit of text to the docs, suggesting that users add the target defintion/spec first, and later work on std support.

I also found that we have two places where we document how to add a new target. I've linked these for now, but they should probably be merged somehow in the future.

@rustbot label A-docs
r? compiler
CC @workingjubilee who's worked a lot on target specs IIRC.

Both the target tier policy and the rustc-dev-guide has documentation on this, let's make sure people see both.

rustbot · 2025-01-24T13:48:01Z

The rustc-dev-guide subtree was changed. If this PR only touches the dev guide consider submitting a PR directly to rust-lang/rustc-dev-guide otherwise thank you for updating the dev guide with your changes.

cc @BoxyUwU, @jieyouxu, @Kobzol

jieyouxu · 2025-01-24T14:24:41Z

src/doc/rustc/src/target-tier-policy.md

+Note that crates like `libc` and `cc` may not accept your patches before the
+`rustc` target specification itself exists, so it is recommended that you
+start out with a minimal pull request adding just that (i.e. only
+`#![no_core]` support), and then slowly expand the support in later pull
+requests.


Hang on, doesn't sometimes r-l/r side PR need PRs to libc and cc to unblock the r-l/r side too? Won't this be a cyclic requirement then deadlock?

Ohh I see, this is explicitly to break that cycle right?

Exactly. Not happy with how it's written, open to suggestions for better wording.

I'll open a T-compiler thread about this to clarify how to handle this cycle when trying to add targets

https://rust-lang.zulipchat.com/#narrow/channel/131828-t-compiler/topic/Improving.20docs.20for.20adding.20new.20targets, please feel free to add additional details as you see fit

I'll compiler-nominate this for awareness.

cc @NobodyXu in case you would like to add anything about adding new targets on the cc-rs side

Exactly. Not happy with how it's written, open to suggestions for better wording.

Maybe something like

Note that adding a new target that wants to support std would transitively require cc and libc support. However, cc and libc would need to know about the target from rustc as well. To break this cycle, you are strongly encouraged to add a minimal #![no_core] target spec first to teach rustc about the target's existence, which cc and libc could then learn from, and add std support as a follow-up.

Let me know what you think.

I've rewritten it to something of that effect.

@rustbot ready

jieyouxu · 2025-01-24T15:15:21Z

Nominating this for awareness (please feel free to discuss async over at https://rust-lang.zulipchat.com/#narrow/channel/131828-t-compiler/topic/Improving.20docs.20for.20adding.20new.20targets):

Currently adding new Tier 3 targets is proving to be a lot of friction, because there's a cycle:

If you want to add a new target that wants to support std, you'll find std depends on cc-rs and libc
But cc-rs and libc needs to know about the new target from rustc, and sometimes can't accept new targets before said target spec exists in rustc

So now we have a cycle. Anything we can do to make this less of a pain? E.g.:

This PR modifies the Target Tier policy to recommend adding a bare metal target spec first in order for the target spec to exist in rustc, which makes it easier for cc-rs and libc to accept a patch to add the new target
Do we want to unconditionally require adding Tier 3 targets to need a MCP so that if the MCP is accepted, libc/cc-rs can be more comfortable in accepting a PR to add a new target even if it doesn't necessarily already exist in rustc...? See below

@rustbot label: +I-compiler-nominated

NobodyXu · 2025-01-25T01:19:00Z

libc/cc-rs can be more comfortable in accepting a PR to add a new target even if it doesn't necessarily already exist in rustc...?

I am willing to accept PR to cc-rs for new target, except for modifications on auto-generated target scrapped from rustc nightly

jieyouxu · 2025-01-30T15:24:18Z

@rustbot review

apiraino · 2025-01-30T16:07:55Z

We had a look at the wording during the t-compiler triage meeting on Zulip and it looks fine.

@rustbot label -I-compiler-nominated

jieyouxu

Thanks, some fiddling on the wording but LGTM as well otherwise.

jieyouxu · 2025-01-31T08:33:28Z

src/doc/rustc/src/target-tier-policy.md

+Note that crates like `libc` and `cc` may not accept your patches before the
+`rustc` target specification itself exists, so it is recommended that you
+start out with a minimal pull request adding just that (i.e. only
+`#![no_core]` support), and then slowly expand the support in later pull
+requests.


Exactly. Not happy with how it's written, open to suggestions for better wording.

Maybe something like

Note that adding a new target that wants to support std would transitively require cc and libc support. However, cc and libc would need to know about the target from rustc as well. To break this cycle, you are strongly encouraged to add a minimal #![no_core] target spec first to teach rustc about the target's existence, which cc and libc could then learn from, and add std support as a follow-up.

Let me know what you think.

jieyouxu · 2025-01-31T08:34:18Z

@rustbot author

Co-Authored-By: Jieyou Xu <jieyouxu@outlook.com>

jieyouxu

Thanks, that looks good.

jieyouxu · 2025-01-31T08:50:32Z

@bors r+ rollup

bors · 2025-01-31T08:50:35Z

📌 Commit 7df38d9 has been approved by jieyouxu

It is now in the queue for this repository.

…iaskrgr Rollup of 9 pull requests Successful merges: - rust-lang#134531 ([rustdoc] Add `--extract-doctests` command-line flag) - rust-lang#135860 (Compiler: Finalize dyn compatibility renaming) - rust-lang#135992 (Improve documentation when adding a new target) - rust-lang#136194 (Support clobber_abi in BPF inline assembly) - rust-lang#136325 (Delay a bug when indexing unsized slices) - rust-lang#136326 (Replace our `LLVMRustDIBuilderRef` with LLVM-C's `LLVMDIBuilderRef`) - rust-lang#136330 (Remove unnecessary hooks) - rust-lang#136336 (Overhaul `rustc_middle::util`) - rust-lang#136341 (Remove myself from vacation) r? `@ghost` `@rustbot` modify labels: rollup

Rollup merge of rust-lang#135992 - madsmtm:new-target-docs, r=jieyouxu Improve documentation when adding a new target rust-lang#133631 (comment) shows that it can be a bit difficult process-wise to add a new target. I've added a bit of text to the docs, suggesting that users add the target defintion/spec first, and later work on `std` support. I also found that we have two places where we document how to add a new target. I've linked these for now, but they should probably be merged somehow in the future. `@rustbot` label A-docs r? compiler CC `@workingjubilee` who's worked a lot on target specs IIRC.

Cross-link documentation for adding a new target

11de4b7

Both the target tier policy and the rustc-dev-guide has documentation on this, let's make sure people see both.

rustbot assigned BoxyUwU Jan 24, 2025

rustbot added A-rustc-dev-guide Area: rustc-dev-guide S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jan 24, 2025

rustbot added the A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools label Jan 24, 2025

madsmtm mentioned this pull request Jan 24, 2025

Support QNX 7.1 with io-sock+libstd and QNX 8.0 (no_std only) #133631

Merged

jieyouxu reviewed Jan 24, 2025

View reviewed changes

jieyouxu added the T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. label Jan 24, 2025

jieyouxu self-assigned this Jan 24, 2025

jieyouxu added S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jan 24, 2025

rustbot added the I-compiler-nominated Nominated for discussion during a compiler team meeting. label Jan 24, 2025

workingjubilee mentioned this pull request Jan 26, 2025

Add armv7a-vex-v5 tier three target #131530

Closed

BoxyUwU removed their assignment Jan 30, 2025

rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jan 30, 2025

rustbot removed the I-compiler-nominated Nominated for discussion during a compiler team meeting. label Jan 30, 2025

jieyouxu removed the S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). label Jan 31, 2025

jieyouxu approved these changes Jan 31, 2025

View reviewed changes

rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jan 31, 2025

Recommend adding target spec first, then std support later

7df38d9

Co-Authored-By: Jieyou Xu <jieyouxu@outlook.com>

madsmtm force-pushed the new-target-docs branch from f3e0f12 to 7df38d9 Compare January 31, 2025 08:42

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Jan 31, 2025

jieyouxu approved these changes Jan 31, 2025

View reviewed changes

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jan 31, 2025

matthiaskrgr mentioned this pull request Jan 31, 2025

Rollup of 9 pull requests #136350

Merged

bors merged commit f818842 into rust-lang:master Jan 31, 2025
6 checks passed

rustbot added this to the 1.86.0 milestone Jan 31, 2025

madsmtm deleted the new-target-docs branch February 2, 2025 00:21

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve documentation when adding a new target #135992

Improve documentation when adding a new target #135992

madsmtm commented Jan 24, 2025 •

edited

Loading

rustbot commented Jan 24, 2025

jieyouxu Jan 24, 2025

jieyouxu Jan 24, 2025

madsmtm Jan 24, 2025

jieyouxu Jan 24, 2025

jieyouxu Jan 24, 2025

jieyouxu Jan 24, 2025

jieyouxu Jan 24, 2025

jieyouxu Jan 31, 2025 •

edited

Loading

madsmtm Jan 31, 2025

jieyouxu commented Jan 24, 2025 •

edited

Loading

NobodyXu commented Jan 25, 2025

jieyouxu commented Jan 30, 2025

apiraino commented Jan 30, 2025

jieyouxu left a comment

jieyouxu Jan 31, 2025 •

edited

Loading

jieyouxu commented Jan 31, 2025

jieyouxu left a comment

jieyouxu commented Jan 31, 2025

bors commented Jan 31, 2025

Improve documentation when adding a new target #135992

Improve documentation when adding a new target #135992

Conversation

madsmtm commented Jan 24, 2025 • edited Loading

rustbot commented Jan 24, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jieyouxu Jan 31, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jieyouxu commented Jan 24, 2025 • edited Loading

NobodyXu commented Jan 25, 2025

jieyouxu commented Jan 30, 2025

apiraino commented Jan 30, 2025

jieyouxu left a comment

Choose a reason for hiding this comment

jieyouxu Jan 31, 2025 • edited Loading

Choose a reason for hiding this comment

jieyouxu commented Jan 31, 2025

jieyouxu left a comment

Choose a reason for hiding this comment

jieyouxu commented Jan 31, 2025

bors commented Jan 31, 2025

madsmtm commented Jan 24, 2025 •

edited

Loading

jieyouxu Jan 31, 2025 •

edited

Loading

jieyouxu commented Jan 24, 2025 •

edited

Loading

jieyouxu Jan 31, 2025 •

edited

Loading