Skip to content

Commit 1433a23

Browse files
authored
[Docs] Add process docs on updating LLVM libraries (#20138)
1 parent 7858816 commit 1433a23

File tree

1 file changed

+67
-0
lines changed

1 file changed

+67
-0
lines changed

docs/process.md

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -174,6 +174,66 @@ updating `emcc.rst` in a PR, the following should be done:
174174
See notes above on installing sphinx.
175175

176176

177+
## Updating the LLVM libraries
178+
179+
We maintain our ports of compiler-rt, libcxx, libcxxabi, and libunwind under
180+
https://github.com/emscripten-core/emscripten/tree/main/system/lib from
181+
[the upstream LLVM repository][llvm_repo] and periodically update them to a newer
182+
version when a new LLVM release comes out.
183+
184+
We maintain [a fork of LLVM][llvm_emscripten_fork] for library updates, where we
185+
create a branch for each new LLVM major release. For example, the branch for
186+
LLVM 16 is
187+
https://github.com/emscripten-core/llvm-project/tree/emscripten-libs-16. We
188+
create a new branch for a major version update and reuse the existing branch for
189+
a minor version update. We mostly do updates per LLVM major release.
190+
191+
To update our libraries to a newer LLVM release:
192+
193+
1. If you are updating an existing branch the first step is to run
194+
[`push_llvm_changes.py`][push_llvm_changes_emscripten] to make sure the
195+
current branch is up-to-date with the current emscripten codebase.
196+
```
197+
./system/lib/push_llvm_changes.py <Emscripten's LLVM fork directory>
198+
```
199+
(The existing library branch should be checked out in your Emscripten's LLVM
200+
fork directory.)
201+
An example of such PR is emscripten-core/llvm-project#5.
202+
203+
If you are creating a new branch, first make sure the previous/existing
204+
branch is up-to-date using
205+
[`push_llvm_changes.py`][push_llvm_changes_emscripten]. Then
206+
create the new branch and cherry-pick all the emscripten-specific changes
207+
from the old branch, resolving any conflicts that might arise.
208+
209+
In either case, once that branch is up-to-date use the update scripts to copy
210+
the llvm branch contents into the emscripten tree. Its important in both
211+
cases to run [`push_llvm_changes.py`][push_llvm_changes_emscripten] first to
212+
ensure that no emscripten changes are lost in the process.
213+
1. Create a PR to merge new LLVM release tag in the upstream repo into our new
214+
library branch. For example, if we want to merge LLVM 16.0.6 release into our
215+
`emscripten-libs-16` branch, you can do
216+
```
217+
git co emscripten-libs-16
218+
git remote add upstream https://github.com/llvm/llvm-project
219+
git fetch --tags upstream
220+
git merge llvmorg-16.0.6
221+
```
222+
An example of such PR is emscripten-core/llvm-project#3.
223+
1. Now we have merged all the changes to our LLVM fork branch, pull those
224+
changes with the new version back into the Emscripten repo. You can use
225+
[`update_compiler_rt.py`][update_compiler_rt_emscripten],
226+
[`update_libcxx.py`][update_libcxx_emscripten],
227+
[`update_libcxxabi.py`][update_libcxxabi_emscripten],
228+
[`update_libunwind.py`][update_libunwind_emscripten] for that. For example,
229+
```
230+
./system/lib/update_comiler_rt.py <Emscripten's LLVM fork directory>
231+
```
232+
(The library branch should be checked out in your Emscripten's LLVM fork
233+
directory.)
234+
An example of such PR is emscripten-core/emscripten#19515.
235+
236+
177237
[site_repo]: https://github.com/kripken/emscripten-site
178238
[releases_repo]: https://chromium.googlesource.com/emscripten-releases
179239
[waterfall]: https://ci.chromium.org/p/emscripten-releases/g/main/console
@@ -190,3 +250,10 @@ See notes above on installing sphinx.
190250
[flake8]: https://github.com/emscripten-core/emscripten/blob/main/.flake8
191251
[mypy]: https://github.com/emscripten-core/emscripten/blob/main/.mypy
192252
[update_docs]: https://github.com/emscripten-core/emscripten/blob/main/tools/maint/update_docs.py
253+
[llvm_repo]: https://github.com/llvm/llvm-project
254+
[llvm_emscripten_fork]: https://github.com/emscripten-core/llvm-project
255+
[push_llvm_changes_emscripten]: https://github.com/emscripten-core/emscripten/blob/main/system/lib/push_llvm_changes.py
256+
[update_compiler_rt_emscripten]: https://github.com/emscripten-core/emscripten/blob/main/system/lib/update_compiler_rt.py
257+
[update_libcxx_emscripten]: https://github.com/emscripten-core/emscripten/blob/main/system/lib/update_libcxx.py
258+
[update_libcxxabi_emscripten]: https://github.com/emscripten-core/emscripten/blob/main/system/lib/update_libcxxabi.py
259+
[update_libunwind_emscripten]: https://github.com/emscripten-core/emscripten/blob/main/system/lib/update_libunwind.py

0 commit comments

Comments
 (0)