mirror
/
rustc-dev-guide
mirror of https://github.com/rust-lang/rustc-dev-guide.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update LLVM docs (#2039) 

* Update LLVM docs

* Apply feedback
This commit is contained in:
Nikita Popov 2024-08-12 23:07:49 +02:00 committed by GitHub
parent c156104dbe
commit 9c427609af
1 changed files with 71 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

98
src/backend/updating-llvm.md
View File

@ -2,33 +2,73 @@
<!-- toc --> <!-- toc -->
<!-- date-check: Jul 2023 --> <!-- date-check: Aug 2024 -->
There is no formal policy about when to update LLVM or what it can be updated to, Rust supports building against multiple LLVM versions:
but a few guidelines are applied:
* We try to always support the latest released version * Tip-of-tree for the current LLVM development branch is usually supported
* We try to support the last few versions within a few days. PRs for such fixes are tagged with `llvm-main`.
(and the number changes over time) * The latest released major version is always supported.
* We allow moving to arbitrary commits during development * The one or two preceding major versions are usually supported.
* We strongly prefer to upstream all patches to LLVM before including them in rustc
## Why update LLVM? By default, Rust uses its own fork in the [rust-lang/llvm-project repository].
This fork is based on a `release/$N.x` branch of the upstream project, where
`$N` is either the latest released major version, or the current major version
in release candidate phase. The fork is never based on the `main` development
branch.
There are two reasons we would want to update LLVM: Our LLVM fork only accepts:
* A bug could have been fixed! * Backports of changes that have already landed upstream.
Note that if we are the ones who fixed such a bug, * Workarounds for build issues affecting our CI environment.
we prefer to upstream it, then pull it back for use by rustc.
* LLVM itself may have a new release. With the exception of one grandfathered-in patch for SGX enablement, we do not
accept functional patches that have not been upstreamed first.
Each of these reasons has a different strategy for updating LLVM, and we'll go There are three types of LLVM updates, with different procedures:
over them in detail here.
## Bugfix Updates * Backports while the current major LLVM version is supported.
* Backports while the current major LLVM version is no longer supported (or
the change is not eligible for upstream backport).
* Update to a new major LLVM version.
For updates of LLVM that are to fix a small bug, we cherry-pick the bugfix to ## Backports (upstream supported)
the branch we're already using. The steps for this are:
While the current major LLVM version is supported upstream, fixes should be
backported upstream first, and the release branch then merged back into the
Rust fork.
1. Make sure the bugfix is in upstream LLVM.
2. If this hasn't happened already, request a backport to the upstream release
branch. If you have LLVM commit access, follow the [backport process].
Otherwise, open an issue requesting the backport. Continue once the
backport has been approved and merged.
3. Identify the branch that rustc is currently using. The `src/llvm-project`
submodule is always pinned to a branch of the
[rust-lang/llvm-project repository].
4. Fork the rust-lang/llvm-project repository.
5. Check out the appropriate branch (typically named `rustc/a.b-yyyy-mm-dd`).
6. Add a remote for the upstream repository using
`git remote add upstream https://github.com/llvm/llvm-project.git` and
fetch it using `git fetch upstream`.
7. Merge the `upstream/release/$N.x` branch.
8. Push this branch to your fork.
9. Send a Pull Request to rust-lang/llvm-project to the same branch as before.
Be sure to reference the Rust and/or LLVM issue that you're fixing in the PR
description.
10. Wait for the PR to be merged.
11. Send a PR to rust-lang/rust updating the `src/llvm-project` submodule with
your bugfix. This can be done locally with `git submodule update --remote
src/llvm-project` typically.
12. Wait for PR to be merged.
An example PR:
[#59089](https://github.com/rust-lang/rust/pull/59089)
## Backports (upstream not supported)
Upstream LLVM releases are only supported for two to three months after the
GA release. Once upstream backports are no longer accepted, changes should be
cherry-picked directly to our fork.
1. Make sure the bugfix is in upstream LLVM. 1. Make sure the bugfix is in upstream LLVM.
2. Identify the branch that rustc is currently using. The `src/llvm-project` 2. Identify the branch that rustc is currently using. The `src/llvm-project`
@ -36,16 +76,19 @@ the branch we're already using. The steps for this are:
[rust-lang/llvm-project repository]. [rust-lang/llvm-project repository].
3. Fork the rust-lang/llvm-project repository. 3. Fork the rust-lang/llvm-project repository.
4. Check out the appropriate branch (typically named `rustc/a.b-yyyy-mm-dd`). 4. Check out the appropriate branch (typically named `rustc/a.b-yyyy-mm-dd`).
5. Cherry-pick the upstream commit onto the branch. 5. Add a remote for the upstream repository using
6. Push this branch to your fork. `git remote add upstream https://github.com/llvm/llvm-project.git` and
7. Send a Pull Request to rust-lang/llvm-project to the same branch as before. fetch it using `git fetch upstream`.
6. Cherry-pick the relevant commit(s) using `git cherry-pick -x`.
7. Push this branch to your fork.
8. Send a Pull Request to rust-lang/llvm-project to the same branch as before.
Be sure to reference the Rust and/or LLVM issue that you're fixing in the PR Be sure to reference the Rust and/or LLVM issue that you're fixing in the PR
description. description.
8. Wait for the PR to be merged. 9. Wait for the PR to be merged.
9. Send a PR to rust-lang/rust updating the `src/llvm-project` submodule with 10. Send a PR to rust-lang/rust updating the `src/llvm-project` submodule with
your bugfix. This can be done locally with `git submodule update --remote your bugfix. This can be done locally with `git submodule update --remote
src/llvm-project` typically. src/llvm-project` typically.
10. Wait for PR to be merged. 11. Wait for PR to be merged.
An example PR: An example PR:
[#59089](https://github.com/rust-lang/rust/pull/59089) [#59089](https://github.com/rust-lang/rust/pull/59089)
@ -187,3 +230,4 @@ keep in mind while going through them:
[`llvm-wrapper`]: https://github.com/rust-lang/rust/tree/master/compiler/rustc_llvm/llvm-wrapper [`llvm-wrapper`]: https://github.com/rust-lang/rust/tree/master/compiler/rustc_llvm/llvm-wrapper
[wg-llvm]: https://rust-lang.zulipchat.com/#narrow/stream/187780-t-compiler.2Fwg-llvm [wg-llvm]: https://rust-lang.zulipchat.com/#narrow/stream/187780-t-compiler.2Fwg-llvm
[Dev Desktops]: https://forge.rust-lang.org/infra/docs/dev-desktop.html [Dev Desktops]: https://forge.rust-lang.org/infra/docs/dev-desktop.html
[backport process]: https://llvm.org/docs/GitHub.html#backporting-fixes-to-the-release-branches