docs: update "upgrading node" guide (#14649)
I think there's more to do here, and I'll continue to add to & update this documentation as I go through the process of upgrading node in the context of the GN build.
This commit is contained in:
Jeremy Apthorp
GitHub
parent
0e91db2188
commit
b8a8bf82ac
1 changed files with 66 additions and 63 deletions
|
|
@ -2,14 +2,15 @@
|
|||
|
||||
## Discussion
|
||||
|
||||
One upgrade issue is building all of Electron with a single copy
|
||||
of V8 to ensure compatibility. This is important because
|
||||
upstream Node and [libchromiumcontent](upgrading-chromium.md)
|
||||
both use their own versions of V8.
|
||||
Chromium and Node.js both depend on V8, and Electron contains
|
||||
only a single copy of V8, so it's important to ensure that the
|
||||
version of V8 chosen is compatible with the build's version of
|
||||
Node.js and Chromium.
|
||||
|
||||
Upgrading Node is much easier than upgrading libchromiumcontent,
|
||||
so fewer conflicts arise if one upgrades libchromiumcontent first,
|
||||
then chooses the upstream Node release whose V8 is closest to it.
|
||||
Upgrading Node is much easier than upgrading Chromium, so fewer
|
||||
conflicts arise if one upgrades Chromium first, then chooses the
|
||||
upstream Node release whose version of V8 is closest to the one
|
||||
Chromium contains.
|
||||
|
||||
Electron has its own [Node fork](https://github.com/electron/node)
|
||||
with modifications for the V8 build details mentioned above
|
||||
|
|
@ -32,16 +33,15 @@ So in short, the primary steps are:
|
|||
|
||||
1. Update Electron's Node fork to the desired version
|
||||
2. Backport Node's V8 patches to our copy of V8
|
||||
3. Update Electron to use new version of Node
|
||||
* Update submodules
|
||||
* Update Node.js build configuration
|
||||
3. Update the GN build files, porting changes from node's GYP files
|
||||
4. Update Electron's DEPS to use new version of Node
|
||||
|
||||
## Updating Electron's Node [fork](https://github.com/electron/node)
|
||||
|
||||
1. Ensure that `master` on `electron/node` has updated release tags from `nodejs/node`
|
||||
2. Create a branch in https://github.com/electron/node: `electron-node-vX.X.X` where the base that you're branching from is the tag for the desired update
|
||||
- `vX.X.X` Must use a version of node compatible with our current version of chromium
|
||||
3. Re-apply our commits from the previous version of node we were using (`vY.Y.Y`) to `v.X.X.X`
|
||||
- `vX.X.X` Must use a version of Node compatible with our current version of Chromium
|
||||
3. Re-apply our commits from the previous version of Node we were using (`vY.Y.Y`) to `v.X.X.X`
|
||||
- Check release tag and select the range of commits we need to re-apply
|
||||
- Cherry-pick commit range:
|
||||
1. Checkout both `vY.Y.Y` & `v.X.X.X`
|
||||
|
|
@ -54,65 +54,68 @@ So in short, the primary steps are:
|
|||
|
||||
## Updating [V8](https://github.com/electron/node/src/V8) Patches
|
||||
|
||||
We need to generate a patch file from each patch applied to V8.
|
||||
We need to generate a patch file from each patch that Node
|
||||
applies to V8.
|
||||
|
||||
1. Get a copy of Electron's libcc fork
|
||||
- `$ git clone https://github.com/electron/libchromiumcontent`
|
||||
2. Run `script/update` to get the latest libcc
|
||||
- This will be time-consuming
|
||||
3. Remove our copies of the old Node v8 patches
|
||||
- (In libchromiumcontent repo) Read `patches/common/v8/README.md` to see which patchfiles
|
||||
were created during the last update
|
||||
- Remove those files from `patches/common/v8/`:
|
||||
- `git rm` the patchfiles
|
||||
- edit `patches/common/v8/README.md`
|
||||
- commit these removals
|
||||
4. Inspect Node [repo](https://github.com/electron/node) to see what patches upstream Node
|
||||
used with their v8 after bumping its version
|
||||
- `git log --oneline "deps/v8"`
|
||||
5. Create a checklist of the patches. This is useful for tracking your work and for
|
||||
having a quick reference of commit hashes to use in the `git diff-tree` step below.
|
||||
6. Read `patches/common/v8/README.md` to see which patchfiles came from the previous version of V8 and therefore need to be removed.
|
||||
- Delete each patchfile referenced in `patches/common/v8/README.md`
|
||||
7. Apply all patches with the [`get-patch` script](https://github.com/electron/libchromiumcontent/blob/master/script/README.md#get-patch):
|
||||
- `./script/get-patch --repo src/v8 --output-dir patches/v8 --commit abc123 def456 ...`
|
||||
8. Update `patches/common/v8/README.md` with references to all new patches that have been added so that the next person will know which need to be removed.
|
||||
9. Update Electron's submodule references:
|
||||
```sh
|
||||
$ cd electron/vendor/node
|
||||
electron/vendor/node$ git fetch
|
||||
electron/vendor/node$ git checkout electron-node-vA.B.C
|
||||
electron/vendor/node$ cd ../libchromiumcontent
|
||||
electron/vendor/libchromiumcontent$ git fetch
|
||||
electron/vendor/libchromiumcontent$ git checkout upgrade-to-chromium-X
|
||||
electron/vendor/libchromiumcontent$ cd ../..
|
||||
electron$ git add vendor
|
||||
electron$ git commit -m "update submodule references for node and libcc"
|
||||
electron$ git push origin upgrade-to-chromium-<VERSION>
|
||||
electron$ script/bootstrap.py -d
|
||||
electron$ script/build.py -c -D
|
||||
```
|
||||
```sh
|
||||
$ cd third_party/electron_node
|
||||
$ CURRENT_NODE_VERSION=vX.Y.Z
|
||||
# Find the last commit with the message "deps: update V8 to <some version>"
|
||||
# This commit corresponds to Node resetting V8 to its pristine upstream
|
||||
# state at the stated version.
|
||||
$ LAST_V8_UPDATE="$(git log --grep='^deps: update V8' --format='%H' -1 deps/v8)"
|
||||
# This creates a patch file containing all changes in deps/v8 from
|
||||
# $LAST_V8_UPDATE up to the current Node version, formatted in a way that
|
||||
# it will apply cleanly to the V8 repository (i.e. with `deps/v8`
|
||||
# stripped off the path and excluding the v8/gypfiles directory, which
|
||||
# isn't present in V8.
|
||||
$ git format-patch \
|
||||
--relative=deps/v8 \
|
||||
$LAST_V8_UPDATE..$CURRENT_NODE_VERSION \
|
||||
deps/v8 \
|
||||
':(exclude)deps/v8/gypfiles' \
|
||||
--stdout \
|
||||
> ../../electron/common/patches/v8/node_v8_patches.patch
|
||||
```
|
||||
|
||||
This list of patches will probably include one that claims to
|
||||
make the V8 API backwards-compatible with a previous version of
|
||||
V8. Unfortunately, those patches almost always change the V8 API
|
||||
in a way that is incompatible with Chromium.
|
||||
|
||||
It's usually easier to update Node to work without the
|
||||
compatibility patch than to update Chromium to work with the
|
||||
compatibility patch, so it's recommended to revert the
|
||||
compatibility patch and fix any errors that arise when compiling
|
||||
Node.
|
||||
|
||||
## Update Electron's `DEPS` file
|
||||
|
||||
Update the `DEPS` file in the root of
|
||||
[electron/electron](https://github.com/electron/electron) to
|
||||
point to the git hash of the updated Node.
|
||||
|
||||
## Notes
|
||||
|
||||
- libcc and V8 are treated as a single unit
|
||||
- Node maintains its own fork of V8
|
||||
- They backport a small amount of things as needed
|
||||
- Documentation in node about how [they work with V8](https://nodejs.org/api/v8.html)
|
||||
- We update code such that we only use one copy of V8 across all of electron
|
||||
- E.g electron, libcc, and node
|
||||
- Documentation in Node about how [they work with V8](https://nodejs.org/api/v8.html)
|
||||
- We update code such that we only use one copy of V8 across all of Electron
|
||||
- E.g Electron, Chromium, and Node.js
|
||||
- We don’t track upstream closely due to logistics:
|
||||
- Upstream uses multiple repos and so merging into a single repo
|
||||
would result in lost history. So we only update when we’re planning
|
||||
a node version bump in electron.
|
||||
- libcc is large and time-consuming to update, so we typically
|
||||
choose the node version based on which of its releases has a version
|
||||
of V8 that’s closest to the version in libcc that we’re using.
|
||||
a Node version bump in Electron.
|
||||
- Chromium is large and time-consuming to update, so we typically
|
||||
choose the Node version based on which of its releases has a version
|
||||
of V8 that’s closest to the version in Chromium that we’re using.
|
||||
- We sometimes have to wait for the next periodic Node release
|
||||
because it will sync more closely with the version of V8 in the new libcc
|
||||
- Electron keeps all its patches in libcc because it’s simpler than
|
||||
because it will sync more closely with the version of V8 in the new Chromium
|
||||
- Electron keeps all its patches in the repo because it’s simpler than
|
||||
maintaining different repos for patches for each upstream project.
|
||||
- Crashpad, node, libcc, etc. patches are all kept in the same place
|
||||
- Building node:
|
||||
- There’s a chance we need to change our build configuration
|
||||
to match the build flags that node wants in `node/common.gypi`
|
||||
- Crashpad, Node.js, Chromium, Skia etc. patches are all kept in the same place
|
||||
- Building Node:
|
||||
- We maintain our own GN build files for Node.js to make it easier to ensure
|
||||
that eevrything is built with the same compiler flags.
|
||||
This means that every time we upgrade Node.js we have to do a modest amount of
|
||||
work to synchronize the GN files with the upstream GYP files.
|
||||
|
|
|
|||
Loading…
Reference in a new issue