Update the "Updating LLVM" documentation (#451)
Make sure existing sections are up-to-date and then also add some words about the recent convention we developed for updating LLVM versions with respect to branch naming as well.
This commit is contained in:
Alex Crichton
GitHub
parent
d290423947
commit
fa049ffc79
|
|
@ -17,23 +17,26 @@ policy!), but for now these are rough guidelines!
|
|||
|
||||
## Why update LLVM?
|
||||
|
||||
There are two primary reasons nowadays that we want to update LLVM in one way or
|
||||
There are a few reasons nowadays that we want to update LLVM in one way or
|
||||
another:
|
||||
|
||||
* First, a bug could have been fixed! Often we find bugs in the compiler and fix
|
||||
* A bug could have been fixed! Often we find bugs in the compiler and fix
|
||||
them upstream in LLVM. We'll want to pull fixes back to the compiler itself as
|
||||
they're merged upstream.
|
||||
|
||||
* Second, a new feature may be available in LLVM that we want to use in rustc,
|
||||
* A new feature may be available in LLVM that we want to use in rustc,
|
||||
but we don't want to wait for a full LLVM release to test it out.
|
||||
|
||||
* LLVM itself may have a new release and we'd like to update to this LLVM
|
||||
release.
|
||||
|
||||
Each of these reasons has a different strategy for updating LLVM, and we'll go
|
||||
over both in detail here.
|
||||
over them in detail here.
|
||||
|
||||
## Bugfix Updates
|
||||
|
||||
For updates of LLVM that typically just update a bug, we cherry-pick the bugfix
|
||||
to the branch we're already using. The steps for this are:
|
||||
For updates of LLVM that are to fix a small bug, we cherry-pick the bugfix to
|
||||
the branch we're already using. The steps for this are:
|
||||
|
||||
1. Make sure the bugfix is in upstream LLVM.
|
||||
2. Identify the branch that rustc is currently using. The `src/llvm-project`
|
||||
|
|
@ -43,10 +46,13 @@ to the branch we're already using. The steps for this are:
|
|||
4. Check out the appropriate branch (typically named `rustc/a.b-yyyy-mm-dd`)
|
||||
5. Cherry-pick the upstream commit onto the branch
|
||||
6. Push this branch to your fork
|
||||
7. Send a Pull Request to rust-lang/llvm-project to the same branch as before
|
||||
7. 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.
|
||||
8. Wait for the PR to be merged
|
||||
9. Send a PR to rust-lang/rust updating the `src/llvm-project` submodule with
|
||||
your bugfix
|
||||
your bugfix. This can be done locally with `git submodule update --remote
|
||||
src/llvm-project` typically.
|
||||
10. Wait for PR to be merged
|
||||
|
||||
The tl;dr; is that we can cherry-pick bugfixes at any time and pull them back
|
||||
|
|
@ -70,7 +76,8 @@ through each in detail.
|
|||
1. Create a new branch in the rust-lang/llvm-project repository. This branch
|
||||
should be named `rustc/a.b-yyyy-mm-dd` where `a.b` is the current version
|
||||
number of LLVM in-tree at the time of the branch and the remaining part is
|
||||
today's date.
|
||||
today's date. Move this branch to the commit in LLVM that you'd like, which
|
||||
for this is probably the current LLVM HEAD.
|
||||
|
||||
2. Apply Rust-specific patches to the llvm-project repository. All features and
|
||||
bugfixes are upstream, but there's often some weird build-related patches
|
||||
|
|
@ -78,20 +85,12 @@ through each in detail.
|
|||
patches are around the latest patches in the rust-lang/llvm-project branch
|
||||
that rustc is currently using.
|
||||
|
||||
3. Update the `compiler-rt` submodule in the
|
||||
`rust-lang-nursery/compiler-builtins` repository. Push this update to the
|
||||
same branch name of the `llvm-project` submodule to the
|
||||
of the `rust-lang/compiler-rt` repository. Then push this update to a branch
|
||||
of `compiler-builtins` with the same-named branch. Note that this step is
|
||||
frequently optional since we may not need to update `compiler-rt`.
|
||||
|
||||
4. Prepare a commit to rust-lang/rust
|
||||
|
||||
* Update `src/llvm-project`
|
||||
* Update `compiler-builtins` crate in `Cargo.lock` (if necessary)
|
||||
|
||||
5. Build your commit. Make sure you've committed the previous changes to ensure
|
||||
submodule updates aren't reverted. Some commands you should execute are:
|
||||
3. Build the new LLVM in the `rust` repository. To do this you'll want to update
|
||||
the `src/llvm-project` repository to your branch and the revision you've
|
||||
created. It's also typically a good idea to update `.gitmodules` with the new
|
||||
branch name of the LLVM submodule. Make sure you've committed changes to
|
||||
`src/llvm-project` to ensure submodule updates aren't reverted. Some commands
|
||||
you should execute are:
|
||||
|
||||
* `./x.py build src/llvm` - test that LLVM still builds
|
||||
* `./x.py build src/tools/lld` - same for LLD
|
||||
|
|
@ -101,7 +100,7 @@ through each in detail.
|
|||
LLVM bindings. Note that you should use `#ifdef` and such to ensure that the
|
||||
bindings still compile on older LLVM versions.
|
||||
|
||||
6. Test for regressions across other platforms. LLVM often has at least one bug
|
||||
4. Test for regressions across other platforms. LLVM often has at least one bug
|
||||
for non-tier-1 architectures, so it's good to do some more testing before
|
||||
sending this to bors! If you're low on resources you can send the PR as-is
|
||||
now to bors, though, and it'll get tested anyway.
|
||||
|
|
@ -120,11 +119,20 @@ through each in detail.
|
|||
* `./src/ci/docker/run.sh dist-various-2`
|
||||
* `./src/ci/docker/run.sh armhf-gnu`
|
||||
|
||||
7. Send a PR! Hopefully it's smooth sailing from here :).
|
||||
5. Prepare a PR to `rust-lang/rust`. Work with maintainers of
|
||||
`rust-lang/llvm-project` to get your commit in a branch of that repository,
|
||||
and then you can send a PR to `rust-lang/rust`. You'll change at least
|
||||
`src/llvm-project` and will likely also change `src/rustllvm/*` as well.
|
||||
|
||||
For prior art, previous LLVM updates look like
|
||||
[#55835](https://github.com/rust-lang/rust/pull/55835)
|
||||
[#47828](https://github.com/rust-lang/rust/pull/47828)
|
||||
[#62474](https://github.com/rust-lang/rust/pull/62474)
|
||||
[#62592](https://github.com/rust-lang/rust/pull/62592). Note that sometimes it's
|
||||
easiest to land `src/rustllvm/*` compatibility as a PR before actually updating
|
||||
`src/llvm-project`. This way while you're working through LLVM issues others
|
||||
interested in trying out the new LLVM can benefit from work you've done to
|
||||
update the C++ bindings.
|
||||
|
||||
### Caveats and gotchas
|
||||
|
||||
|
|
@ -134,8 +142,36 @@ keep in mind while going through them:
|
|||
* LLVM bugs are hard to find, don't hesitate to ask for help! Bisection is
|
||||
definitely your friend here (yes LLVM takes forever to build, yet bisection is
|
||||
still your friend)
|
||||
* Updating LLDB has some Rust-specific patches currently that aren't upstream.
|
||||
If you have difficulty @tromey can likely help out.
|
||||
* If you've got general questions, @alexcrichton can help you out.
|
||||
* Creating branches is a privileged operation on GitHub, so you'll need someone
|
||||
with write access to create the branches for you most likely.
|
||||
|
||||
## New LLVM Release Updates
|
||||
|
||||
Updating to a new release of LLVM is very similar to the "feature updates"
|
||||
section above. The release process for LLVM is often months-long though and we
|
||||
like to ensure compatibility ASAP. The main tweaks to the "feature updates"
|
||||
section above is generally around branch naming. The sequence of events
|
||||
typically looks like:
|
||||
|
||||
1. LLVM announces that its latest release version has branched. This will show
|
||||
up as a branch in https://github.com/llvm/llvm-project typically named
|
||||
`release/$N.x` where `$N` is the version of LLVM that's being released.
|
||||
|
||||
2. We then follow the "feature updates" section above to create a new branch of
|
||||
LLVM in our rust-lang/llvm-project repository. This follows the same naming
|
||||
convention of branches as usual, except that `a.b` is the new version. This
|
||||
update is eventually landed in the rust-lang/rust repository.
|
||||
|
||||
3. Over the next few months, LLVM will continually push commits to its
|
||||
`release/a.b` branch. Often those are bug fixes we'd like to have as well.
|
||||
The merge process for that is to use `git merge` itself to merge LLVM's
|
||||
`release/a.b` branch with the branch created in step 2. This is typically
|
||||
done multiple times when necessary while LLVM's release branch is baking.
|
||||
|
||||
4. LLVM then announces the release of version `a.b`.
|
||||
|
||||
5. After LLVM's official release, we follow the "feature update" section again
|
||||
to create a new branch in the rust-lang/llvm-project repository, this time
|
||||
with a new date. The commit history should look much cleaner as just a few
|
||||
Rust-specific commits stacked on top of stock LLVM's release branch.
|
||||
|
|
|
|||
Loading…
Reference in New Issue