@@ -174,6 +174,66 @@ updating `emcc.rst` in a PR, the following should be done:
174
174
See notes above on installing sphinx.
175
175
176
176
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
+
177
237
[ site_repo ] : https://github.com/kripken/emscripten-site
178
238
[ releases_repo ] : https://chromium.googlesource.com/emscripten-releases
179
239
[ waterfall ] : https://ci.chromium.org/p/emscripten-releases/g/main/console
@@ -190,3 +250,10 @@ See notes above on installing sphinx.
190
250
[ flake8 ] : https://github.com/emscripten-core/emscripten/blob/main/.flake8
191
251
[ mypy ] : https://github.com/emscripten-core/emscripten/blob/main/.mypy
192
252
[ 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