## Summary
- `bun run build:local` now handles everything: configuring JSC,
building JSC, and building Bun in a single command on all platforms
(macOS, Linux, Windows). Previously required manually running `bun run
jsc:build:debug`, deleting a duplicate `InspectorProtocolObjects.h`
header, and then running the Bun build separately.
- Incremental JSC rebuilds: JSC is built via `add_custom_target` that
delegates to JSC's inner Ninja, which tracks WebKit source file changes
and only rebuilds what changed. `ninja -Cbuild/debug-local` also works
after the first build.
- Cross-platform support:
- macOS: Uses system ICU automatically
- Linux: Uses system ICU via find_package instead of requiring bundled
static libs
- Windows: Builds ICU from source automatically (only when libs don't
already exist), sets up static CRT and ICU naming conventions
### Changes
- cmake/tools/SetupWebKit.cmake: Replace the old WEBKIT_LOCAL block
(which just set include paths and assumed JSC was pre-built) with full
JSC configure + build integration for all platforms
- cmake/targets/BuildBun.cmake: Add jsc as a build dependency, use
system ICU on Linux for local builds, handle bmalloc linking for local
builds
- CONTRIBUTING.md / docs/project/contributing.mdx: Simplify "Building
WebKit locally" docs from ~15 lines of manual steps to 3 lines
## Test plan
- [x] macOS arm64: clean build, incremental rebuild, WebKit source
change rebuild
- [x] Windows x64: clean build with ICU, incremental rebuild with ICU
skip
- [x] Linux x64: build with system ICU via find_package
- [x] No duplicate InspectorProtocolObjects.h errors
- [x] build/debug-local/bun-debug --version works
Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <noreply@anthropic.com>
## Summary
Add a CI step that runs JSC JIT stress tests under QEMU when
`SetupWebKit.cmake` is modified. This complements #26571 (basic baseline
CPU verification) by also testing JIT-generated code.
## Motivation
PR #26571 added QEMU-based verification that catches illegal
instructions in:
- Startup code
- Static initialization
- Basic interpreter execution
However, JIT compilers (DFG, FTL, Wasm BBQ/OMG) generate code at runtime
that could emit AVX or LSE instructions even if the compiled binary
doesn't. The JSC stress tests from #26380 exercise all JIT tiers through
hot loops that trigger tier-up.
## How it works
1. Detects if `cmake/tools/SetupWebKit.cmake` is modified in the PR
2. If WebKit changes are detected, runs `verify-jit-stress-qemu.sh`
after the build
3. Executes all 78 JIT stress test fixtures under QEMU with restricted
CPU features:
- x64: `qemu-x86_64 -cpu Nehalem` (SSE4.2, no AVX)
- aarch64: `qemu-aarch64 -cpu cortex-a53` (ARMv8.0-A, no LSE)
4. Any SIGILL from JIT-generated code fails the build
## Platforms tested
| Target | CPU Model | What it catches |
|---|---|---|
| `linux-x64-baseline` | Nehalem | JIT emitting AVX/AVX2/AVX512 |
| `linux-x64-musl-baseline` | Nehalem | JIT emitting AVX/AVX2/AVX512 |
| `linux-aarch64` | Cortex-A53 | JIT emitting LSE atomics, SVE |
| `linux-aarch64-musl` | Cortex-A53 | JIT emitting LSE atomics, SVE |
## Timeout
The step has a 30-minute timeout since QEMU emulation is ~10-50x slower
than native. This only runs on WebKit update PRs, so it won't affect
most CI runs.
## Refs
- #26380 - Added JSC JIT stress tests
- #26571 - Added basic QEMU baseline verification
Fixes illegal instruction (SIGILL) crashes on ARMv8.0 aarch64 CPUs
(Cortex-A53, Raspberry Pi 4, AWS a1 instances).
## Root cause
Upstream mimalloc force-enables `MI_OPT_ARCH` on arm64, which adds
`-march=armv8.1-a` and emits LSE atomic instructions (`casa`, `swpa`,
`ldaddl`). These are not available on ARMv8.0 CPUs.
## Fix
- Pass `MI_NO_OPT_ARCH=ON` to mimalloc on aarch64 (has priority over
`MI_OPT_ARCH` in mimalloc's CMake)
- Update WebKit to autobuild-596e48e22e3a1090e5b802744a7938088b1ea860
which explicitly passes `-march` flags to the WebKit build
## Verification
Includes QEMU-based baseline CPU verification CI steps (#26571) that
catch these regressions automatically.
### What does this PR do?
Updates WebKit to
5b6a0ac49b
### How did you verify your code works?
---------
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Jarred Sumner <jarred@jarredsumner.com>
Co-authored-by: Claude Bot <claude-bot@bun.sh>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
### What does this PR do?
Updates WebKit to
87c6cde57d
### How did you verify your code works?
---------
Co-authored-by: Jarred Sumner <jarred@jarredsumner.com>
### What does this PR do?
Without this change, building with `-DWEBKIT_LOCAL=ON` fails with:
```
/work/bun/src/bun.js/bindings/BunObject.cpp:12:10: fatal error: 'JavaScriptCore/JSBase.h' file not found
12 | #include <JavaScriptCore/JSBase.h>
| ^~~~~~~~~~~~~~~~~~~~~~~~~
1 error generated.
```
The reason for this is because the directory structure differs between
downloaded and local WebKit.
Downloaded WebKit:
```
build/debug/cache/webkit-6d0f3aac0b817cc0/
└── include/
└── JavaScriptCore/
└── JSBase.h ← Direct path
```
Local WebKit:
```
vendor/WebKit/WebKitBuild/Debug/
└── JavaScriptCore/Headers/
└── JavaScriptCore/
└── JSBase.h ← Nested path
```
The include paths are thus configured differently for each build type.
For Remote WebKit (when WEBKIT_LOCAL=OFF):
- SetupWebKit.cmake line 22 sets: WEBKIT_INCLUDE_PATH =
${WEBKIT_PATH}/include
- BuildBun.cmake line 1253 adds:
include_directories(${WEBKIT_INCLUDE_PATH})
- This resolves to: build/debug/cache/webkit-6d0f3aac0b817cc0/include/
- So #include <JavaScriptCore/JSBase.h> finds the file at
include/JavaScriptCore/JSBase.h ✅
For Local WebKit (when WEBKIT_LOCAL=ON):
- The original code only added:
${WEBKIT_PATH}/JavaScriptCore/Headers/JavaScriptCore
- This resolves to:
vendor/WebKit/WebKitBuild/Debug/JavaScriptCore/Headers/JavaScriptCore/
- So #include <JavaScriptCore/JSBase.h> fails because there's no
JavaScriptCore/ subdirectory at that level ❌
- The fix adds: ${WEBKIT_PATH}/JavaScriptCore/Headers
- Now the include path includes:
vendor/WebKit/WebKitBuild/Debug/JavaScriptCore/Headers/
- So #include <JavaScriptCore/JSBase.h> finds the file at
Headers/JavaScriptCore/JSBase.h ✅
### How did you verify your code works?
Built locally.
Co-authored-by: Carl Smedstad <carsme@archlinux.org>
### What does this PR do?
Before this change, downloading WebKit would fail silently if there were
e.g. a connection or TLS certificate issue. I experienced this when
trying to build bun in an overly-restrictive sandbox.
After this change, the failure reason will be visible.
### How did you verify your code works?
<details>
<summary>Brought down my network interface and ran the build:</summary>
```sh
$ node ./scripts/build.mjs \
-GNinja \
-DCMAKE_BUILD_TYPE=Debug \
-B build/debug \
--log-level=NOTICE \
-DBUN_EXECUTABLE="$(which node)" \
-DNPM_EXECUTABLE="$(which npm)" \
-DZIG_EXECUTABLE="$(which zig)" \
-DENABLE_ASAN=OFF
Globbed 1971 sources [180.67ms]
CMake Configure
$ cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug -B /work/bun/build/debug --log-level NOTICE -DBUN_EXECUTABLE=/bin/node -DNPM_EXECUTABLE=/bin/npm -DZIG_EXECUTABLE=/bin/zig -DENABLE_ASAN=OFF -S /work/bun -DCACHE_STRATEGY=auto
sccache: Using local cache strategy.
...
```
</details>
Result:
```
CMake Error at cmake/tools/SetupWebKit.cmake:99 (message):
Failed to download WebKit: 6;"Could not resolve hostname"
Call Stack (most recent call first):
cmake/targets/BuildBun.cmake:1204 (include)
CMakeLists.txt:66 (include)
```
### What does this PR do?
Enables `CHECK_REF_COUNTED_LIFECYCLE` in WebKit (
https://github.com/oven-sh/WebKit/pull/121 )
See also
a978fae619
#### `CHECK_REF_COUNTED_LIFECYCLE`?
A compile-time macro that enables lifecycle validation for
reference-counted objects in debug builds.
**Definition**
```cpp
#if ASSERT_ENABLED || ENABLE(SECURITY_ASSERTIONS)
#define CHECK_REF_COUNTED_LIFECYCLE 1
#else
#define CHECK_REF_COUNTED_LIFECYCLE 0
#endif
```
**Purpose**
Detects three categories of bugs:
1. Missing adoption - Objects stored in RefPtr without using adoptRef()
2. Ref during destruction - ref() called while destructor is running
(causes dangling pointers)
3. Thread safety violations - Unsafe ref/deref across threads
**Implementation**
When enabled, RefCountDebugger adds two tracking flags:
- m_deletionHasBegun - Set when destructor starts
- m_adoptionIsRequired - Cleared when adoptRef() is called
These flags are checked on every ref()/deref() call, with assertions
failing on violations.
**Motivation**
Refactored debug code into a separate RefCountDebugger class to:
- Improve readability of core refcount logic
- Eliminate duplicate code across RefCounted, ThreadSafeRefCounted, etc.
- Simplify adding new refcount classes
**Overhead**
Zero in release builds - the flags and checks are compiled out entirely.
### How did you verify your code works?
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
- WTFMove → WTF::move / std::move: Replaced WTFMove() macro with
WTF::move() function for WTF types, std::move() for std types
- SortedArrayMap removed: Replaced with if-else chains in
EventFactory.cpp, JSCryptoKeyUsage.cpp
- Wasm::Memory::create signature changed: Removed VM parameter
- URLPattern allocation: Changed from WTF_MAKE_ISO_ALLOCATED to
WTF_MAKE_TZONE_ALLOCATED
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
### What does this PR do?
- **Use `Latin1Character` instead of `LChar`**
- **Fix for
0875bc8f62**
### How did you verify your code works?
---
# WebKit Update Summary (September 2025)
## Overview
This document summarizes the major changes in WebKit/JavaScriptCore from
the September 2025 update. The update includes approximately 254
JSC-related commits with significant improvements to performance,
stability, and developer experience.
## Critical Bug Fixes
### Memory Safety
- **operationMaterializeObjectInOSR fix** (5c7aadfa0a96): Fixed
uninitialized Butterfly storage during OSR exits with sunk Array
allocations. This prevents potential crashes when arrays with holes are
materialized during OSR exit.
- **FTL materialization fixes** (a72d19840714, ed1e6fe03899): Added
missing internal object type handling in FTL materialization, improving
stability during optimization bailouts.
### Promise and Async Improvements
- **JSPromiseReaction object** (a1cb5e087a46, later reverted in
b0566a4db201): Initially introduced to improve promise reaction handling
but was reverted due to compatibility issues with Bun's modifications.
- **Async stack traces enhancements**:
- Added support for `Promise.any` in async stack traces (d9a997b3edaa)
- Added empty JSValue checking for async stack trace safety
(9d26223d4bcb)
- Promise.all support was added and later reverted due to performance
concerns
## Performance Optimizations
### JIT Compiler Improvements
- **B3 Immutable Loads** (570a3530f949, 62300f8db3d9): Added
immutability annotations and CSE optimizations for loads that can look
for targets in dominators
- **BBQ JIT enhancements**:
- Fixed callee-save register handling (c7ae05719045)
- Simplified F32 copysign operations (e0651af57025)
- **DFG optimizations**:
- Fixed RegExp constant folding with materialized NewRegExp nodes
(7b53a04a5afa)
- Improved RegExp object node handling in strength reduction
(eeb65e05095b)
### WebAssembly Improvements
- **WASM SIMD Support**:
- Added v128 support for IPInt call and tail-call instructions
(73f0c9d430cb)
- Implemented v128 support in local.get, local.set, global.get,
global.set (67d7bf15139a)
- Added x86_64 SIMD integer arithmetic and float instructions
- **WASM Memory Management**:
- Introduced WasmInstanceAnchor for better instance lifecycle management
(f9f1ed183bf7)
- Attached AbstractHeap to wasm memory access for better optimization
(f183c6f7def4)
- Added signal handling for null checks in wasm (bf18b5b709f3)
- **WASM Debugging**: Added LLDB debugging infrastructure for
WebAssembly (e03c10225cc8)
## API and Language Features
### Iterator Helpers
- Merged `Iterator.prototype.sliding` into `Iterator.prototype.windows`
(1d49e823702d)
- Optimized iterator next method calls using CachedCall (5ee92514060c)
### Math Extensions
- Improved performance of `Math.sumPrecise` implementation
(602294057337)
### Error Handling
- Enhanced error messages for for-of loops without Symbol.iterator
(0051bbf2491f)
## Infrastructure Changes
### Character Type Refactoring
- **LChar to Latin1Character rename** (63b97b511366, 1424f0687876):
Major refactoring replacing the `LChar` type with `Latin1Character`
throughout the codebase for better clarity
- Additional fixes for Latin1Character usage (711eab3243f0,
50bf8e6fd4ca, 88e29ab76aec)
### Build System
- Fixed builds with GCC 15.x (e33b18bc59d6)
- Added gitattributes for JSC test files (82c4cc796da6)
- Improved test runner with comprehensive verbose logging (7ef95c177a42)
- Added memory-limited annotations for tests using excessive memory
(b991cd17d612)
### Testing Infrastructure
- Improved handling of missing test executables (db1e3bbb3be2)
- Added support for non-customized ICU 74.2 in intl tests (c922a28b6642)
- Fixed various test configuration issues and timeouts
## Bun-Specific Modifications
### Preserved Customizations
- Maintained `BUN_JSC_ADDITIONS` for Bun-specific features
- Kept async context support for AsyncLocalStorage
- Preserved V8 heap snapshot compatibility layer
- Maintained custom inspector extensions
### Conflicts Resolved
- Successfully merged upstream changes while preserving Bun's event loop
integration
- Resolved conflicts in promise handling while maintaining Bun's async
behavior
- Fixed re-declaration issues with `isAsyncFrame` for async stack traces
## Breaking Changes and Reverts
### Reverted Features
1. **JSPromiseReaction object**: Reverted due to conflicts with Bun's
promise handling
2. **Promise.all async stack trace support**: Reverted due to ~4%
performance regression in JetStream3/doxbee-async benchmark
3. **Array.prototype.flat C++ implementation**: Reverted (reason not
specified in commit)
## Security Improvements
- Type safety improvements with uncheckedDowncast for Wasm::Callee
(48425afd643d)
- Added bounds checking and validation for Wasm array operations
(b5148db1c4c1)
- Improved memory safety with proper initialization of materialized
objects
## Platform Support
- macOS: Continued support for x64/arm64
- Linux: Maintained glibc/musl compatibility
- Windows: Preserved x64 support
- Fixed platform-specific alignment issues for x86_64 (94a60eb123c5)
## Notable Debugging Enhancements
- LLDB infrastructure for WebAssembly debugging
- Improved verbose command logging in test runners
- Enhanced stack trace capabilities for async functions
- Better error reporting for missing Symbol.iterator
## Performance Metrics
- Several memory optimizations for test execution
- JIT memory reservation size adjustments for debug builds
- Optimized iterator operations with cached calls
- Improved Math.sumPrecise performance
## Future Considerations
- The JSPromiseReaction implementation may need revisiting with adjusted
architecture
- Async stack trace support for Promise.all requires performance
optimization
- Continued work on WASM SIMD support for additional operations
## Migration Notes for Bun Team
1. **LChar usage**: All references to `LChar` have been replaced with
`Latin1Character`
2. **Promise handling**: The reverted JSPromiseReaction changes indicate
potential architectural conflicts that may need addressing
3. **Test configuration**: New memory-limited annotations should be used
for memory-intensive tests
4. **Build flags**: Ensure USE_BUN_JSC_ADDITIONS and USE_BUN_EVENT_LOOP
remain enabled
### What does this PR do?
### How did you verify your code works?
---------
Co-authored-by: Claude Bot <claude-bot@bun.sh>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
### What does this PR do?
Evidently, Ubuntu turns them on by default.
Claude:
```
> What is the typical overhead for glibcxx assertions?
⏺ The overhead of glibc/libstdc++ assertions can be significant, especially in
performance-critical code:
Typical Overhead Ranges:
libstdc++ (C++ standard library) assertions:
- 5-15% overall performance impact in typical applications
- Up to 30-50% in container-heavy code (vectors, maps, etc.)
- Iterator validity checks are particularly expensive
glibc (C library) assertions:
- 2-8% overall impact in typical applications
- Up to 20% in malloc/free intensive code
- Heap consistency checks, buffer overflow detection
```
### What does this PR do?
Enables async stack traces
### How did you verify your code works?
Added tests
---------
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
### What does this PR do?
### How did you verify your code works?
---------
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Claude Bot <claude-bot@bun.sh>
Co-authored-by: Claude <noreply@anthropic.com>
### What does this PR do?
### How did you verify your code works?
---------
Co-authored-by: Jarred-Sumner <709451+Jarred-Sumner@users.noreply.github.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
## Summary
- Updates WebKit commit from `684d4551ce5f62683476409d7402424e0f6eafb5`
to `aa4997abc9126f5a7557c9ecb7e8104779d87ec4`
- Build completed successfully with no errors
- Verified functionality with hello world test
## Test plan
- [x] Build completed successfully
- [x] Hello world test passes with `bun bd`
- [x] No build errors encountered
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Claude Bot <claude-bot@bun.sh>
Co-authored-by: Claude <noreply@anthropic.com>
## Summary
- Updates WebKit from 75f6499 to eb92990 (latest release from
oven-sh/webkit)
- This brings in the latest WebKit improvements and fixes
## Test plan
- [ ] Verify the build completes successfully
- [ ] Run existing test suite to ensure no regressions
🤖 Generated with [Claude Code](https://claude.ai/code)
---------
Co-authored-by: Claude Bot <claude-bot@bun.sh>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Jarred Sumner <jarred@jarredsumner.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
### What does this PR do?
<!-- **Please explain what your changes do**, example: -->
<!--
This adds a new flag --bail to bun test. When set, it will stop running
tests after the first failure. This is useful for CI environments where
you want to fail fast.
-->
### How did you verify your code works?
ran fuzzy-wuzzy.test.ts
<!-- **For code changes, please include automated tests**. Feel free to
uncomment the line below -->
<!-- I wrote automated tests -->
<!-- If JavaScript/TypeScript modules or builtins changed:
- [ ] I included a test for the new code, or existing tests cover it
- [ ] I ran my tests locally and they pass (`bun-debug test
test-file-name.test`)
-->
<!-- If Zig files changed:
- [ ] I checked the lifetime of memory allocated to verify it's (1)
freed and (2) only freed when it should be
- [ ] I included a test for the new code, or an existing test covers it
- [ ] JSValue used outside of the stack is either wrapped in a
JSC.Strong or is JSValueProtect'ed
- [ ] I wrote TypeScript/JavaScript tests and they pass locally
(`bun-debug test test-file-name.test`)
-->
<!-- If new methods, getters, or setters were added to a publicly
exposed class:
- [ ] I added TypeScript types for the new methods, getters, or setters
-->
<!-- If dependencies in tests changed:
- [ ] I made sure that specific versions of dependencies are used
instead of ranged or tagged versions
-->
<!-- If a new builtin ESM/CJS module was added:
- [ ] I updated Aliases in `module_loader.zig` to include the new module
- [ ] I added a test that imports the module
- [ ] I added a test that require() the module
-->
