add rough draft of node, crashpad update notes
This commit is contained in:
Charles Kerr
Shelley Vohr
parent
c18afc924b
commit
f8858a7577
2 changed files with 178 additions and 0 deletions
36
docs/development/upgrading-crashpad.md
Normal file
36
docs/development/upgrading-crashpad.md
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
- Get the version of crashpad that we're going to use.
|
||||
- `libcc/src/third_party/crashpad/README.chromium` will have a line `Revision:` with a checksum.
|
||||
- clone [Electron's Crashpad fork](https://github.com/electron/crashpad) and create a new branch
|
||||
- `git clone https://chromium.googlesource.com/crashpad/crashpad`
|
||||
- `git checkout 01110c0a3b`
|
||||
- `git remote add electron https://github.com/electron/crashpad`
|
||||
- `git checkout -b electron-crashpad-vA.B.C.D`
|
||||
- `A.B.C.D` is the Chromium version found in `libcc/VERSION`
|
||||
and will be something like `62.0.3202.94`
|
||||
|
||||
- Make a checklist of the Electron patches we need to apply
|
||||
e.g. `git log --oneline`
|
||||
or view http://github.com/electron/crashpad/commits/previous-branch-name
|
||||
- Foreach patch:
|
||||
- (in new branch) `git cherry-pick checksum`
|
||||
- resolve any conflicts
|
||||
- make sure it builds
|
||||
- add && commit
|
||||
- Push your work:
|
||||
`git push electron electorn-crashpad-v62.0.3202.94`
|
||||
|
||||
- Update Electron to build the new crashpad:
|
||||
- `cd vendor/crashpad`
|
||||
- `git fetch`
|
||||
- `git checkout electron-crashpad-v62.0.3202.94`
|
||||
- Regenerate Ninja files
|
||||
- from Electron root's root, run `script/update.py`
|
||||
- `script/build.py -c D --target=crashpad_client`
|
||||
- `script/build.py -c D --target=crashpad_handler`
|
||||
- If both of these work, it's probably good.
|
||||
- Push changes to submodule reference
|
||||
- (from electron root) `git add vendor/crashpad`
|
||||
- `git push origin upgrade-to-chromium-62`
|
||||
|
||||
|
||||
|
||||
142
docs/development/upgrading-node.md
Normal file
142
docs/development/upgrading-node.md
Normal file
|
|
@ -0,0 +1,142 @@
|
|||
# Upgrading Node
|
||||
|
||||
## Discussion
|
||||
|
||||
One upgrade issue is building all of Electron with a single copy
|
||||
of V8 to ensure compatability. This is important because
|
||||
upstream Node and [libchromiumcontent](upgrading-chrome.md)
|
||||
both use their own versions of V8.
|
||||
|
||||
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.
|
||||
|
||||
Electron has its own [Node fork](https://github.com/electron/node)
|
||||
with modifications for the V8 build details mentioned above
|
||||
and for exposing API needed by Electron. Once an upstream Node
|
||||
release is chosen, it's placed in a branch in Electron's Node fork
|
||||
and any Electron Node patches are applied there.
|
||||
|
||||
Another factor is that the Node project patches its version of V8.
|
||||
As mentioned above, Electron builds everything with a single copy
|
||||
of V8, so Node's V8 patches must be ported to that copy.
|
||||
|
||||
Once all of Electron's dependencies are building and using the same
|
||||
copy of V8, the next step is to fix any Electron code issues caused
|
||||
by the Node upgrade.
|
||||
|
||||
[FIXME] something about a Node debugger in Atom that we (e.g. deepak)
|
||||
use and need to confirm doesn't break with the Node upgrade?
|
||||
|
||||
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
|
||||
|
||||
## Updating [Electron's Node fork](https://github.com/electron/node)
|
||||
|
||||
1. Create a branch in https://github.com/electron/node: `electron-node-vX.X.X`
|
||||
- `vX.X.X` Must use a version of node compatible with our current version of chromium
|
||||
2. 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`
|
||||
2. `git cherry-pick FIRST_COMMIT_HASH..LAST_COMMIT_HASH`
|
||||
- Resolve merge conflicts in each file encountered, then:
|
||||
1. `git add <conflict-file>`
|
||||
2. `git cherry-pick --continue`
|
||||
3. Repeat until finished
|
||||
|
||||
|
||||
## Updating [V8](https://github.com/electron/node/src/V8) Patches
|
||||
|
||||
We need to generate a patch file from each patch applied to V8.
|
||||
|
||||
- Get a copy of Electron's libchromiumcontent fork
|
||||
- Run `script/update` to get the latest libcc
|
||||
- This will be time-consuming
|
||||
- Remove our copies of the old Node v8 patches
|
||||
- (In libchromiumcontent repo) Read `patches/v8/README.md` to see which patchfiles
|
||||
were created during the last update
|
||||
- Remove those files from `patches/v8/`:
|
||||
- `git rm` the patchfiles
|
||||
- edit `patches/v8/README.md`
|
||||
- commit these removals
|
||||
- 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`
|
||||
- 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.
|
||||
- For each patch, do:
|
||||
1. (In node repo) `git diff-tree --patch HASH > ~/path_to_libchromiumcontent/patches/v8/xxx-patch_name.patch`
|
||||
- `xxx` is an incremented three-digit number (to force patch order)
|
||||
- `patch_name` should loosely match the node commit messages,
|
||||
e.g. `030-cherry_pick_cc55747,patch` if the Node commit message was "cherry-pick cc55747"
|
||||
2. (remainder of steps in libchromium repo)
|
||||
Manually edit the `.patch` file to match upstream V8's directory:
|
||||
- If a diff section has no instances of `deps/V8`, remove it altogether.
|
||||
- We don’t want those patches because we’re only patching V8.
|
||||
- Replace instances of `a/deps/v8`/filename.ext` with `a/filename.ext`
|
||||
- This is needed because upstream Node keeps its V8 files in a subdirectory
|
||||
3. Ensure that local status is clean: `git status` to make sure there are no unstaged changes.
|
||||
4. Confirm that the patch applies cleanly with
|
||||
`script/patch.py -r src/V8 -p patches/v8/xxx-patch_name.patch.patch`
|
||||
5. Create a new copy of the patch:
|
||||
- `cd src/v8 && git diff > ../../test.patch && cd ../..`
|
||||
- This is needed because the first patch has Node commit checksums that we don't want
|
||||
6. Confirm that checksums are the only difference between the two patches:
|
||||
- `diff -u test.patch patches/v8/xxx-patch_name.patch`
|
||||
7. Replace the old patch with the new:
|
||||
- `mv test.patch patches/v8/xxx-patch_name.patch`
|
||||
8. Add the patched code to the index _without_ committing:
|
||||
- `cd src/v8 && git add . && cd ../..`
|
||||
- We don't want to commit the changes (they're kept in the patchfiles)
|
||||
but need them locally so that they don't show up in subsequent diffs
|
||||
while we iterate through more patches
|
||||
9. Add the patch file to the index:
|
||||
- `git add a patches/v8/`
|
||||
10. Optionally commit each patch file to ensure you can back up if you mess up a step:
|
||||
- `git commit patches/v8/`
|
||||
- Update `patches/v8/README.md`
|
||||
=FIXME== (In libchromiumcontent repo) Read `patches/v8/README.md` to see which patchfiles
|
||||
|
||||
|
||||
## 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
|
||||
- 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.
|
||||
- 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
|
||||
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`
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in a new issue