diff --git a/docs/development/upgrading-chromium.md b/docs/development/upgrading-chromium.md index b7a08c7053d5..3f450a85d86a 100644 --- a/docs/development/upgrading-chromium.md +++ b/docs/development/upgrading-chromium.md @@ -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 /src \ --libcc_shared_library_path /shared_library \ --libcc_static_library_path /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 @@ -129,7 +158,7 @@ You can verify Electron's support for multiple `ffmpeg` builds by loading the fo ``` -## Useful Links +## Useful links - [Chrome Release Schedule](https://www.chromium.org/developers/calendar) - [OmahaProxy](http://omahaproxy.appspot.com) diff --git a/docs/development/upgrading-node.md b/docs/development/upgrading-node.md index 5d30eb77e99c..108e36a52458 100644 --- a/docs/development/upgrading-node.md +++ b/docs/development/upgrading-node.md @@ -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