Skip to content

v8-updates.md

Latest commit

 

History

History
154 lines (107 loc) · 5.15 KB

v8-updates.md

File metadata and controls

154 lines (107 loc) · 5.15 KB
Raw

V8 Updates

To update the version of V8 used by workerd, the steps are:

  1. Check https://chromiumdash.appspot.com/ and identify the latest version of V8 used by the beta versions of Chrome beta.

  2. Install depot_tools if it is not already present on your machine.

    https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up

  3. Fetch a local copy of V8:

    mkdir v8
cd v8
fetch v8

    You should probably put this outside of your workerd repo to avoid confusing Bazel.

  4. Sync the local copy of V8 to the version used by workerd.

    First, find workerd's current version of V8 in build/deps/v8.MODULE.bazel. We will call this <old_version>.

    Then sync your fetched version v8 based on the tag.

    cd <path_to_v8>/v8
git checkout <old_version>
gclient sync

  5. Create a V8 branch for workerd's V8 patches in your local copy of V8.

    git checkout -b workerd-patches
git am --keep-non-patch <path_to_workerd>/patches/v8/*

    --keep-non-patch is the counterpart of the -k in step 7. It keeps subject prefixes such as the [wasm] that upstream V8 commits carry, so the patches regenerated in step 7 keep their existing filenames.

  6. Rebase the workerd V8 changes onto the new version of V8. For example, assuming we are updating to <new_version>, the command would be:

    git rebase --onto <new_version> <old_version>

    There is usually some minor patch editing required during a rebase.

    Ideally at this stage, you should be able to build and test the local V8 with the patches applied. See the V8 Testing page.

  7. Re-generate workerd's V8 patches.

    git format-patch --full-index -k --no-signature --no-stat --zero-commit <new_version>

  8. Remove the existing patches from <path_to_workerd>/patches/v8 and copy over the latest generated patches from the V8 directory.

  9. Update the VERSION for V8 in build/deps/v8.MODULE.bazel.

    The list of patches should be refreshed if new patches are being added or existing patches are being removed.

    INTEGRITY needs to be updated to the new value. You can get the new value in bazel's preferred format just by looking into the mismatch error while trying to compile workerd using the newer V8 version or by running openssl dgst -sha256 -binary <tarball_filename> | openssl base64 -A where <tarball_filename> is the file available at https://github.com/v8/v8/archive/refs/tags/<new_version>.tar.gz

  10. Update V8's dependencies in deps.jsonc, then regenerate deps.MODULE.bazel by running update-deps.py.

    You can find the commit versions for V8's dependencies under <path_to_v8>/DEPS.

    These currently include perfetto, com_googlesource_chromium_icu and simdutf. Note that V8 depends on perfetto and simdutf via chromium so you can't trivially figure out what version of the github code V8 depends on. Instead, it should be safe to just bump these dependencies to the latest version on github.

  11. Check workerd's tests pass with the updated V8.

    bazel test //...

  12. Commit your workerd changes and push them for review.

Update Helper

ci/v8_update.py provides an alternative workflow for automating the mechanical parts of steps 1 through 10. It has not been thoroughly tested, so review its changes carefully and fall back to the manual workflow above if it fails.

Check whether Chrome Beta uses a newer V8 version:

python3 ci/v8_update.py check-update

The command prints <current_version> -> <new_version> and exits with status 1 when an update is available. It prints nothing and exits successfully when workerd is current. Pass --machine-readable to print only the new version.

Run the update using the reported version:

python3 ci/v8_update.py update <new_version>

The helper creates a shallow V8 checkout at /tmp/workerd-v8/v8, applies and rebases the patches, regenerates patches/v8/*.patch, and updates:

  • V8's VERSION, INTEGRITY, patch list, and ICU commit in build/deps/v8.MODULE.bazel;
  • the dragonbox, fast_float, fp16, and highway commits in build/deps/deps.jsonc.

If the rebase stops because of conflicts, resolve and continue it in the temporary checkout:

cd /tmp/workerd-v8/v8
git status
# Resolve the conflicts and stage the files.
git rebase --continue

Repeat until the rebase completes. Patch conflicts require human review to ensure that workerd-specific behavior is preserved. Then return to the workerd checkout and finish the update:

python3 ci/v8_update.py finish <new_version>

Do not run finish until the rebase has completed. It regenerates the patches and updates the pins listed above.

The helper does not run update-deps.py. Compare the old and new V8 DEPS files for changes to dragonbox, fast_float, fp16, highway, perfetto, and simdutf, then run the dependency updater for each changed revision:

python3 build/deps/update-deps.py <dependency>

Complete steps 11 and 12 from the manual workflow after reviewing the generated changes.