From 1512073b9589c30f415b82b87d1bb3e0e83df981 Mon Sep 17 00:00:00 2001 From: rami3l Date: Mon, 3 Aug 2026 18:34:11 +0200 Subject: [PATCH] docs(dev-guide): mention how to support new compilation targets --- doc/dev-guide/src/SUMMARY.md | 3 ++- doc/dev-guide/src/recipes.md | 47 ++++++++++++++++++++++++++++++++++++ 2 files changed, 49 insertions(+), 1 deletion(-) create mode 100644 doc/dev-guide/src/recipes.md diff --git a/doc/dev-guide/src/SUMMARY.md b/doc/dev-guide/src/SUMMARY.md index 6e92db0665..d95e347b52 100644 --- a/doc/dev-guide/src/SUMMARY.md +++ b/doc/dev-guide/src/SUMMARY.md @@ -1,9 +1,10 @@ # Summary - [Introduction](index.md) - - [Linting](linting.md) + - [Linting](linting.md) - [Coding standards](coding-standards.md) - [Version numbers](version-numbers.md) +- [Recipes](recipes.md) - [Release process](release-process.md) - [Tips and tricks](tips-and-tricks.md) - [Tracing](tracing.md) diff --git a/doc/dev-guide/src/recipes.md b/doc/dev-guide/src/recipes.md new file mode 100644 index 0000000000..aa65f9a39d --- /dev/null +++ b/doc/dev-guide/src/recipes.md @@ -0,0 +1,47 @@ +# Recipes + +This section contains some recipes for common tasks that you may want to +perform when contributing to rustup. + +## Supporting a new compilation target + +Adding support for a new compilation target involves the following steps: + +1. Informing rustup of the new target: + + Since you are here, it is quite likely that you are promoting a target from + tier 3 to tier 2. As such, it is often sufficient to just cross-compile + rustup from Linux to that target. + + You can refer to [rustup#4688] for a practical example for this step. You + can find in that PR nearly all places where you would need to mention your + new target in the rustup codebase. + + Notably, you would need to add a line in + `ci/actions-templates/linux-builds-template.yaml` to include it in rustup's + CI, while disabling the build for this target in all scenarios. At the + moment of writing, this is done by appending the YAML comment + `# skip-pr skip-master skip-stable` + at the end of the line when mentioning your target in that file. + + [rustup#4688]: https://github.com/rust-lang/rustup/pull/4688 + +2. Stabilizing the target: + + When your new target reaches stable Rust, you can then enable the target in + certain CI scenarios, depending on the popularity of the target. At the + moment of writing, this is done by removing certain occurrences of `skip-*` + in the aforementioned YAML comment. In most cases, you would only need to + enable the target for the `stable` CI scenario by removing `skip-stable`. + + You can refer to [rustup#4816] for a practical example for this step. + + Do note that when creating the PR for this step, you will need to prove that + the target's CI is indeed working by removing `skip-pr` in a separate commit + to temporarily enable this target in this PR's CI. Once the CI is green, you + can send the link ([example][send-link]) to that CI run in the PR thread for + verification. After that, you can safely drop the temporary commit to get + the PR ready for merging. + + [rustup#4816]: https://github.com/rust-lang/rustup/pull/4816 + [send-link]: https://github.com/rust-lang/rustup/pull/4816#issuecomment-4263419604