Merge pull request #11249 from electron/upgrading-chromium-tweaks

Apply some of my summit notes to the upgrading-chrome docs.
This commit is contained in:
Charles Kerr 2017-11-28 00:55:12 +01:00 committed by GitHub
commit 2ad425955b
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 87 additions and 59 deletions

View file

@ -1,7 +1,6 @@
# Upgrading Chromium
This document is meant to serve as an overview of what steps are needed
on each Chromium upgrade in Electron.
This is an overview of the steps needed to upgrade Chromium in Electron.
- Upgrade libcc to a new Chromium version
- Make Electron code compatible with the new libcc
@ -10,68 +9,87 @@ on each Chromium upgrade in Electron.
- Update Electron docs if necessary
## Upgrade `libcc` to a new Chromium
## Upgrade `libcc` to a new Chromium version
1. Get the code and initialize the project:
- ```sh
$ git clone git@github.com:electron/libchromiumcontent.git
$ cd libchromiumcontent
$ ./script/bootstrap -v```
2. Find the new beta/stable Chromium version from [OmahaProxy](https://omahaproxy.appspot.com/).
3. Put it into the `libchromiumcontent/VERSION` file, then run `$ ./script/update`
- It will probably fail applying patches.
4. Fix `*.patch` files in the `/patches` and `/patches-mas` folders.
5. (Optional) Run a separate script to apply patches (`script/update` uses it internally):
- `$ ./script/apply-patches`
- There is also another script `/script/patch.py` that could be more useful
- Check `--help` to learn how it works with `$ ./script/patch.py -h`
6. Run the build when all patches can be applied without errors
2. Update the Chromium snapshot
- Choose a version number from [OmahaProxy](https://omahaproxy.appspot.com/)
and update the `VERSION` file with it
- This can be done manually by visiting OmahaProxy in a browser, or automatically:
- One-liner for the latest stable mac version: `curl -so- https://omahaproxy.appspot.com/mac > VERSION`
- One-liner for the latest win64 beta version: `curl -so- https://omahaproxy.appspot.com/all | grep "win64,beta" | awk -F, 'NR==1{print $3}' > VERSION`
- run `$ ./script/update`
- Brew some tea -- this may run for 30m or more.
- It will probably fail applying patches.
3. Fix `*.patch` files in the `patches/` and `patches-mas/` folders.
4. (Optional) `script/update` applies patches, but if multiple tries are needed
you can manually run the same script that `update` calls:
`$ ./script/apply-patches`
- There is a second script, `script/patch.py` that may be useful.
Read `./script/patch.py -h` for more information.
5. Run the build when all patches can be applied without errors
- `$ ./script/build`
- If some patches are no longer compatible with the Chromium code, fix compilation errors.
7. When build succeeds, create a `dist` for Electron
- If some patches are no longer compatible with the Chromium code,
fix compilation errors.
6. When the build succeeds, create a `dist` for Electron
- `$ ./script/create-dist --no_zip`
- It will create `dist/main` folder in the root of the libcc repo
- You will need it to build Electron.
8. (Optional) Update script contents if there are errors resultant of some files being removed or renamed. (`--no_zip` prevents script from create `dist` archives, you don't need them.)
- It will create a `dist/main` folder in the libcc repo's root.
You will need this to build Electron.
7. (Optional) Update script contents if there are errors resulting from files
that were removed or renamed. (`--no_zip` prevents script from create `dist`
archives. You don't need them.)
## Update Electron Code
## Update Electron's code
1. Get the code:
- ```sh
$ git clone git@github.com:electron/electron.git
$ cd electron
```
2. If you already have libcc built on you machine in its own repo, you need to tell Electron explicitly to use it:
$ git clone git@github.com:electron/electron.git
$ cd electron
```
2. If you have libcc built on your machine in its own repo,
tell Electron to use it:
- ```sh
$ ./script/bootstrap.py -v \
$ ./script/bootstrap.py -v \
--libcc_source_path <libcc_folder>/src \
--libcc_shared_library_path <libcc_folder>/shared_library \
--libcc_static_library_path <libcc_folder>/static_library
```
- If you haven't yet built libcc but it's already supposed to be upgraded to a new Chromium, bootstrap Electron as usual
`$ ./script/bootstrap.py -v`
- Ensure that libcc submodule (`vendor/libchromiumcontent`) points to a right revision
```
3. If you haven't yet built libcc but it's already supposed to be upgraded
to a new Chromium, bootstrap Electron as usual
`$ ./script/bootstrap.py -v`
- Ensure that libcc submodule (`vendor/libchromiumcontent`) points to the
right revision
3. Set CLANG_REVISION in` script/update-clang.sh` to match the version Chromium is using.
4. Set `CLANG_REVISION` in `script/update-clang.sh` to match the version
Chromium is using.
- Located in `electron/libchromiumcontent/src/tools/clang/scripts/update.py`
4. Checkout Chromium if you haven't already:
5. Checkout Chromium if you haven't already:
- https://chromium.googlesource.com/chromium/src.git/+/{VERSION}/tools/clang/scripts/update.py
- (Replace the `{VERSION}` placeholder in the url above to the Chromium version libcc uses.)
5. Build Electron.
- (Replace the `{VERSION}` placeholder in the url above to the Chromium
version libcc uses.)
6. Build Electron.
- Try to build Debug version first: `$ ./script/build.py -c D`
- You will need it to run tests
6. Fix compilation and linking errors
7. Ensure that Release build can be built too
7. Fix compilation and linking errors
8. Ensure that Release build can be built too
- `$ ./script/build.py -c R`
- Often the Release build will have different linking errors that you'll need to fix.
- Some compilation and linking errors are caused by missing source/object files in the libcc `dist`
8. Update `./script/create-dist` in the libcc repo, recreate a `dist`, and run Electron bootstrap script once again.
- Often the Release build will have different linking errors that you'll
need to fix.
- Some compilation and linking errors are caused by missing source/object
files in the libcc `dist`
9. Update `./script/create-dist` in the libcc repo, recreate a `dist`, and
run Electron bootstrap script once again.
### Tips for fixing compilation errors
- Fix build config errors first
- Fix fatal errors first, like missing files and errors related to compiler flags or defines
- Fix fatal errors first, like missing files and errors related to compiler
flags or defines
- Try to identify complex errors as soon as possible.
- Ask for help if you're not sure how to fix them
- Disable all Electron features, fix the build, then enable them one by one
@ -86,20 +104,31 @@ Follow all the steps above to fix Electron code on all supported platforms.
## Updating Crashpad
If there are any compilation errors related to the Crashpad, it probably means you need to update the fork to a newer revision: see [Upgrading Crashpad](https://github.com/electron/electron/tree/master/docs/development/upgrading-crashpad.md) for instructions on how to do that.
If there are any compilation errors related to the Crashpad, it probably means
you need to update the fork to a newer revision. See
[Upgrading Crashpad](https://github.com/electron/electron/tree/master/docs/development/upgrading-crashpad.md)
for instructions on how to do that.
## Updating NodeJS
Upgrade `vendor/node` to the Node release that corresponds to the v8 version being used in the new Chromium release. See the v8 versions in Node on
Upgrade `vendor/node` to the Node release that corresponds to the v8 version
used in the new Chromium release. See the v8 versions in Node on
See [Upgrading Node](https://github.com/electron/electron/tree/master/docs/development/upgrading-node.md) for instructions on how to do this.
See [Upgrading Node](https://github.com/electron/electron/tree/master/docs/development/upgrading-node.md)
for instructions on this.
## Verify ffmpeg Support
## Verify ffmpeg support
Electron ships with a version of `ffmpeg` that includes proprietary codecs by default. A version without these codecs is built and distributed with each release as well. Each Chrome upgrade should verify that switching this version is still supported.
Electron ships with a version of `ffmpeg` that includes proprietary codecs by
default. A version without these codecs is built and distributed with each
release as well. Each Chrome upgrade should verify that switching this version
is still supported.
You can verify Electron's support for multiple `ffmpeg` builds by loading the following page. It should work with the default `ffmpeg` library distributed with Electron and not work with the `ffmpeg` library built without proprietary codecs.
You can verify Electron's support for multiple `ffmpeg` builds by loading the
following page. It should work with the default `ffmpeg` library distributed
with Electron and not work with the `ffmpeg` library built without proprietary
codecs.
```html
<!DOCTYPE html>
@ -129,7 +158,7 @@ You can verify Electron's support for multiple `ffmpeg` builds by loading the fo
</html>
```
## Useful Links
## Useful links
- [Chrome Release Schedule](https://www.chromium.org/developers/calendar)
- [OmahaProxy](http://omahaproxy.appspot.com)

View file

@ -105,21 +105,20 @@ We need to generate a patch file from each patch applied to V8.
- `git commit patches/v8/`
8. Update `patches/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 libc"
electron$ git pso upgrade-to-chromium-62
electron$ script/bootstrap.py -d
electron$ script/build.py -c -D```
- ```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 referefences for node and libc"
electron$ git pso upgrade-to-chromium-62
electron$ script/bootstrap.py -d
electron$ script/build.py -c -D
```
## Notes