|
1 | 1 | # @nativescript/windows-v8 |
2 | 2 |
|
3 | | -NativeScript Windows runtime on **V8** — the same engine our classic runtime is built on. No Node. |
4 | | - |
5 | | -## As an app runtime (drop-in for `@nativescript/windows`) |
6 | | -Publishes as `@nativescript/windows-v8`, the **same** WinUI 3 framework as `@nativescript/windows` |
7 | | -with a napi-backed V8 runtime DLL — swap the dependency and an app runs unchanged. Build the |
8 | | -framework with the engine flag: |
9 | | -```sh |
10 | | -pwsh -File ../../template/build.ps1 -Engine v8 # or: npm run build |
11 | | -``` |
12 | | -The engine → runtime-DLL adapter (the C ABI the WinUI 3 host P/Invokes) follows the reference |
13 | | -implementation in `../windows-quickjs/src/abi.rs`. See `../README.md` for the full contract. |
14 | | - |
15 | | -## Standalone host |
16 | | -Reuses napi-android's `v8-api.cpp` (napi over V8's C++ API), **ported to V8 14.7**, compiled against |
17 | | -the `v8` crate's bundled headers and linked against its prebuilt rusty_v8 (V8 14.7). The Android |
18 | | -bring-up (`jsr.cpp`) is replaced by `csrc/win_jsr.cpp`. Full WinRT demo passes (`exit 0`): |
19 | | -static-method resolution, typed WinRT calls, a 20-call stress loop, and a `JsonObject` round-trip. |
20 | | - |
21 | | -```sh |
22 | | -cargo build --release --manifest-path packages/windows-v8/Cargo.toml |
23 | | -target/release/nativescript-windows.exe |
24 | | -``` |
25 | | - |
26 | | -## Why this was tractable (no ABI nightmare) |
27 | | -The `v8` crate's default config has **pointer compression and the sandbox OFF** (they're opt-in |
28 | | -cargo features we don't enable), so V8 uses plain/uncompressed pointers — there are **no ABI-matching |
29 | | -defines** and none of the corruption risk that config would bring. The port was therefore a bounded |
30 | | -API migration, not an ABI hunt. |
31 | | - |
32 | | -## What the port involved (V8 13 → 14.7) |
33 | | -- Build recipe: C++20 + `/Zc:__cplusplus` (MSVC reports the real `__cplusplus`), locate the crate's |
34 | | - `v8/include`, stub `<android/log.h>`, `NAPI_EXTERN` → `__declspec(dllexport)`, define `__V8_13__` |
35 | | - (take the shim's modern `SetAccessorProperty` etc. paths). No pointer-compression/sandbox defines. |
36 | | -- API migrations: `String::Write/WriteUtf8/WriteOneByte` → `*V2` (+ `WriteFlags`); mandatory pointer |
37 | | - **type tags** on internal fields / `External` (safe defaults `kEmbedderDataTypeTagDefault` / |
38 | | - `kExternalPointerTypeTagDefault`); `Context::GetIsolate()` removed → `Isolate::GetCurrent()`; |
39 | | - interceptor setters return `v8::Intercepted` (`ReturnValue<void>`). |
40 | | -- Platform init done from **Rust** (`v8::new_default_platform` → `V8::initialize`) because |
41 | | - `NewDefaultPlatform`'s `std::unique_ptr<Platform>` return can't be linked from the MSVC-STL shim |
42 | | - (rusty_v8 uses V8's bundled libc++). See below. |
43 | | - |
44 | | -## The libc++ boundary — solved, including zero-copy |
45 | | -rusty_v8 is built with V8's bundled libc++, so V8 API methods whose signatures involve |
46 | | -`std::shared_ptr`/`unique_ptr<BackingStore>` can't be linked directly from this MSVC-STL shim. |
47 | | -Handled without any copy: |
48 | | -- Reads use `ArrayBuffer::Data()` (the direct `void*` accessor — no `BackingStore`). |
49 | | -- `napi_create_external_arraybuffer` is **true zero-copy**: it goes through rusty_v8's own |
50 | | - `extern "C"` bindings (`v8__ArrayBuffer__NewBackingStore__with_data`, the unique→shared converter, |
51 | | - `v8__ArrayBuffer__New__with_backing_store`) which pass the backing store as raw pointers / an |
52 | | - opaque 16-byte `shared_ptr`, then bridges the returned pointer back to a `Local` (a `Local` is one |
53 | | - pointer). The buffer aliases the source memory; the napi finalizer runs from the BackingStore |
54 | | - deleter on GC. **Verified:** `interop.arrayBufferFromBuffer(CryptographicBuffer.GenerateRandom(8))` |
55 | | - → `byteLength=8`, `instanceof ArrayBuffer`, no copy. So the IBuffer→ArrayBuffer perf path is intact. |
| 3 | +NativeScript Windows runtime on **V8** |
0 commit comments