Skip to content

Commit 6f3d5e4

Browse files
tshepangtshepang
authored
date-check: updating-llvm (#1424)
1 parent 36e15ae commit 6f3d5e4

File tree

1 file changed

+82
-85
lines changed

1 file changed

+82
-85
lines changed

‎src/backend/updating-llvm.md

+82-85
Original file line numberDiff line numberDiff line change
@@ -19,18 +19,13 @@ policy!), but for now these are rough guidelines!
1919

2020
## Why update LLVM?
2121

22-
There are a few reasons nowadays that we want to update LLVM in one way or
23-
another:
22+
There are two reasons we would want to update LLVM:
2423

2524
* A bug could have been fixed! Often we find bugs in the compiler and fix
2625
them upstream in LLVM. We'll want to pull fixes back to the compiler itself as
2726
they're merged upstream.
2827

29-
* A new feature may be available in LLVM that we want to use in rustc,
30-
but we don't want to wait for a full LLVM release to test it out.
31-
32-
* LLVM itself may have a new release and we'd like to update to this LLVM
33-
release.
28+
* LLVM itself may have a new release.
3429

3530
Each of these reasons has a different strategy for updating LLVM, and we'll go
3631
over them in detail here.
@@ -57,59 +52,67 @@ the branch we're already using. The steps for this are:
5752
src/llvm-project` typically.
5853
10. Wait for PR to be merged
5954

60-
The tl;dr; is that we can cherry-pick bugfixes at any time and pull them back
61-
into the rust-lang/llvm-project branch that we're using, and getting it into the
62-
compiler is just updating the submodule via a PR!
63-
64-
Example PRs look like:
55+
An example PR:
6556
[#59089](https://github.com/rust-lang/rust/pull/59089)
6657

67-
## Feature updates
68-
69-
> Note that this information is as of the time of this writing, <!--
70-
date-check --> October 2021. The process for updating LLVM changes with
71-
practically all LLVM updates, so this may be out of date!
72-
73-
Unlike bugfixes, updating to pick up a new feature of LLVM typically requires a
74-
lot more work. This is where we can't reasonably cherry-pick commits backwards
75-
so we need to do a full update. There's a lot of stuff to do here, so let's go
76-
through each in detail.
77-
78-
1. Create a new branch in the [rust-lang/llvm-project repository]. This branch
79-
should be named `rustc/a.b-yyyy-mm-dd` where `a.b` is the current version
80-
number of LLVM in-tree at the time of the branch and the remaining part is
81-
today's date. Move this branch to the commit in LLVM that you'd like, which
82-
for this is probably the current LLVM HEAD.
83-
84-
2. Apply Rust-specific patches to the llvm-project repository. All features and
85-
bugfixes are upstream, but there's often some weird build-related patches
86-
that don't make sense to upstream which we have on our repositories. These
87-
patches are around the latest patches in the rust-lang/llvm-project branch
88-
that rustc is currently using.
58+
## New LLVM Release Updates
8959

90-
3. Build the new LLVM in the `rust` repository. To do this you'll want to update
91-
the `src/llvm-project` repository to your branch and the revision you've
92-
created. It's also typically a good idea to update `.gitmodules` with the new
93-
branch name of the LLVM submodule. Make sure you've committed changes to
94-
`src/llvm-project` to ensure submodule updates aren't reverted. Some commands
95-
you should execute are:
60+
<!-- date-check: Aug 2022 -->
61+
62+
Unlike bugfixes,
63+
updating to a new release of LLVM typically requires a lot more work.
64+
This is where we can't reasonably cherry-pick commits backwards,
65+
so we need to do a full update.
66+
There's a lot of stuff to do here,
67+
so let's go through each in detail.
68+
69+
1. LLVM announces that its latest release version has branched.
70+
This will show up as a branch in the [llvm/llvm-project repository],
71+
typically named `release/$N.x`,
72+
where `$N` is the version of LLVM that's being released.
73+
74+
1. Create a new branch in the [rust-lang/llvm-project repository]
75+
from this `release/$N.x` branch,
76+
and name it `rustc/a.b-yyyy-mm-dd`,
77+
where `a.b` is the current version number of LLVM in-tree
78+
at the time of the branch,
79+
and the remaining part is the current date.
80+
81+
2. Apply Rust-specific patches to the llvm-project repository.
82+
All features and bugfixes are upstream,
83+
but there's often some weird build-related patches
84+
that don't make sense to upstream.
85+
These patches are typically the latest patches in the
86+
rust-lang/llvm-project branch that rustc is currently using.
87+
88+
3. Build the new LLVM in the `rust` repository.
89+
To do this,
90+
you'll want to update the `src/llvm-project` repository to your branch,
91+
and the revision you've created.
92+
It's also typically a good idea to update `.gitmodules` with the new
93+
branch name of the LLVM submodule.
94+
Make sure you've committed changes to
95+
`src/llvm-project` to ensure submodule updates aren't reverted.
96+
Some commands you should execute are:
9697

9798
* `./x.py build src/llvm` - test that LLVM still builds
9899
* `./x.py build src/tools/lld` - same for LLD
99100
* `./x.py build` - build the rest of rustc
100101

101-
You'll likely need to update [`llvm-wrapper/*.cpp`][`llvm-wrapper`] to compile
102-
with updated LLVM bindings. Note that you should use `#ifdef` and such to ensure
102+
You'll likely need to update [`llvm-wrapper/*.cpp`][`llvm-wrapper`]
103+
to compile with updated LLVM bindings.
104+
Note that you should use `#ifdef` and such to ensure
103105
that the bindings still compile on older LLVM versions.
104106

105107
Note that `profile = "compiler"` and other defaults set by `./x.py setup`
106-
download LLVM from CI instead of building it from source. You should
107-
disable this temporarily to make sure your changes are being used, by setting
108+
download LLVM from CI instead of building it from source.
109+
You should disable this temporarily to make sure your changes are being used.
110+
This is done by having the following setting in `config.toml`:
111+
108112
```toml
109113
[llvm]
110114
download-ci-llvm = false
111115
```
112-
in config.toml.
113116

114117
4. Test for regressions across other platforms. LLVM often has at least one bug
115118
for non-tier-1 architectures, so it's good to do some more testing before
@@ -122,7 +125,7 @@ through each in detail.
122125
* macOS
123126
* Windows
124127

125-
and afterwards run some docker containers that CI also does:
128+
Afterwards, run some docker containers that CI also does:
126129

127130
* `./src/ci/docker/run.sh wasm32`
128131
* `./src/ci/docker/run.sh arm-android`
@@ -135,16 +138,39 @@ through each in detail.
135138
and then you can send a PR to `rust-lang/rust`. You'll change at least
136139
`src/llvm-project` and will likely also change [`llvm-wrapper`] as well.
137140

138-
For prior art, previous LLVM updates look like
139-
[#62474](https://github.com/rust-lang/rust/pull/62474)
140-
[#62592](https://github.com/rust-lang/rust/pull/62592)
141-
[#67759](https://github.com/rust-lang/rust/pull/67759)
142-
[#73526](https://github.com/rust-lang/rust/pull/73526)
143-
[#81451](https://github.com/rust-lang/rust/pull/81451). Note that sometimes it's
144-
easiest to land [`llvm-wrapper`] compatibility as a PR before actually updating
145-
`src/llvm-project`. This way while you're working through LLVM issues others
146-
interested in trying out the new LLVM can benefit from work you've done to
147-
update the C++ bindings.
141+
> For prior art, here are some previous LLVM updates:
142+
> - [LLVM 11](https://github.com/rust-lang/rust/pull/73526)
143+
> - [LLVM 12](https://github.com/rust-lang/rust/pull/81451)
144+
> - [LLVM 13](https://github.com/rust-lang/rust/pull/87570)
145+
> - [LLVM 14](https://github.com/rust-lang/rust/pull/93577)
146+
> - [LLVM 15](https://github.com/rust-lang/rust/pull/99464)
147+
148+
Note that sometimes it's easiest to land [`llvm-wrapper`] compatibility as a PR
149+
before actually updating `src/llvm-project`.
150+
This way,
151+
while you're working through LLVM issues,
152+
others interested in trying out the new LLVM can benefit from work you've done
153+
to update the C++ bindings.
154+
155+
3. Over the next few months,
156+
LLVM will continually push commits to its `release/a.b` branch.
157+
We will often want to have those bug fixes as well.
158+
The merge process for that is to use `git merge` itself to merge LLVM's
159+
`release/a.b` branch with the branch created in step 2.
160+
This is typically
161+
done multiple times when necessary while LLVM's release branch is baking.
162+
163+
4. LLVM then announces the release of version `a.b`.
164+
165+
5. After LLVM's official release,
166+
we follow the process of creating a new branch on the
167+
rust-lang/llvm-project repository again,
168+
this time with a new date.
169+
It is only then that the PR to update Rust to use that version is merged.
170+
171+
The commit history of `rust-lang/llvm-project`
172+
should look much cleaner as a `git rebase` is done,
173+
where just a few Rust-specific commits are stacked on top of stock LLVM's release branch.
148174

149175
### Caveats and gotchas
150176

@@ -158,35 +184,6 @@ keep in mind while going through them:
158184
* Creating branches is a privileged operation on GitHub, so you'll need someone
159185
with write access to create the branches for you most likely.
160186

161-
## New LLVM Release Updates
162-
163-
Updating to a new release of LLVM is very similar to the "feature updates"
164-
section above. The release process for LLVM is often months-long though and we
165-
like to ensure compatibility ASAP. The main tweaks to the "feature updates"
166-
section above is generally around branch naming. The sequence of events
167-
typically looks like:
168-
169-
1. LLVM announces that its latest release version has branched. This will show
170-
up as a branch in the [llvm/llvm-project repository] typically named
171-
`release/$N.x` where `$N` is the version of LLVM that's being released.
172-
173-
2. We then follow the "feature updates" section above to create a new branch of
174-
LLVM in our rust-lang/llvm-project repository. This follows the same naming
175-
convention of branches as usual, except that `a.b` is the new version. This
176-
update is eventually landed in the rust-lang/rust repository.
177-
178-
3. Over the next few months, LLVM will continually push commits to its
179-
`release/a.b` branch. Often those are bug fixes we'd like to have as well.
180-
The merge process for that is to use `git merge` itself to merge LLVM's
181-
`release/a.b` branch with the branch created in step 2. This is typically
182-
done multiple times when necessary while LLVM's release branch is baking.
183-
184-
4. LLVM then announces the release of version `a.b`.
185-
186-
5. After LLVM's official release, we follow the "feature update" section again
187-
to create a new branch in the rust-lang/llvm-project repository, this time
188-
with a new date. The commit history should look much cleaner as just a few
189-
Rust-specific commits stacked on top of stock LLVM's release branch.
190187

191188
[rust-lang/llvm-project repository]: https://github.com/rust-lang/llvm-project
192189
[llvm/llvm-project repository]: https://github.com/llvm/llvm-project

0 commit comments

Comments
 (0)