How to Port the V8 JavaScript Engine to HarmonyOS – A Complete Guide

1. Background

The Roma framework is a self‑developed dynamic cross‑platform solution that already supports iOS, Android and Web, with more than 200 pages and 200 Lego floors in the JD Finance app. To run Roma‑based business on HarmonyOS without extra cost, the framework must be adapted to HarmonyOS.

Roma runs on a JavaScript engine: on iOS it uses the built‑in JavaScriptCore, on Android it uses V8. HarmonyOS, however, lacks a suitable JS engine, so a JS engine must be ported to the platform.

2. JS Engine Selection

Popular JavaScript engines include:

V8 – used by Chrome, Edge, Node.js, Electron (Google)

SpiderMonkey – used by Firefox (Mozilla)

JavaScriptCore – used by Safari (Apple)

Chakra – used by IE (Microsoft)

Hermes – used by React Native (Facebook)

JerryScript/Duktape/QuickJS – small, embeddable engines for IoT devices

V8 is the most widely adopted engine. It powers Chrome (≈60% market share), Node.js (the de‑facto standard for server‑side JavaScript), Electron (desktop apps), and virtually all Chromium‑based browsers, including many Chinese browsers. V8 enables JavaScript to run on Web, apps, desktop, server and IoT.

3. How V8 Works

3.1 Parser (Lexical & Syntax Analysis)

V8 parses source code into an Abstract Syntax Tree (AST). Lexical analysis tokenizes the source (e.g., var a = 2; becomes tokens: var, a, =, 2, ;). The AST represents the program’s structure without execution logic.

3.2 Ignition – the Interpreter

Ignition converts the AST into bytecode and interprets it line‑by‑line, providing fast startup and low memory usage while collecting profiling data for the optimizing compiler TurboFan.

What is Bytecode?

Bytecode is an intermediate representation between AST and machine code. It is architecture‑agnostic, compact, and can be executed by the interpreter. It enables “compile‑once, run‑anywhere” semantics.

Bytecode Advantages

Not tied to a specific CPU architecture.

Faster to generate than native machine code.

Smaller memory footprint than machine code.

Supports “compile‑once, run‑anywhere”.

V8 can print bytecode with node --print-bytecode test.js. Example output shows instruction offsets, registers, and source positions.

3.3 TurboFan – the Optimizing Compiler

TurboFan performs Just‑In‑Time (JIT) compilation. It monitors execution, marks hot functions, and recompiles them into highly optimized machine code. If assumptions break (e.g., a function’s argument type changes), TurboFan de‑optimizes back to bytecode.

Inlining and Escape Analysis

TurboFan can inline small functions and perform escape analysis to eliminate unnecessary allocations, further improving performance.

3.4 Orinoco – Garbage Collector

Orinoco is V8’s concurrent, generational garbage collector. It uses concurrent marking, incremental collection, and multi‑threading to reduce pause times and improve memory utilization.

4. Selecting a V8 Porting Toolchain

Cross‑compilation is required because the target platform (HarmonyOS) may differ in OS, architecture (x86 vs arm64), or both. The process involves building V8 on the host, then generating a snapshot for the target.

V8’s official build system uses gn + ninja . HarmonyOS provides a native build system based on cmake + ninja . The plan is to translate V8’s gn configuration to cmake.

4.1 CMake Overview

CMake can generate Makefiles or Ninja files for many IDEs (Visual Studio, Xcode, Eclipse). A typical CMake workflow:

cmake_minimum_required(VERSION 2.8)
# Enable C++11
#project(camke_demo)
include_directories(${PROJECT_SOURCE_DIR}/../include/...)
set(SRC ...)
add_library(camke_demo_lib STATIC ${SRC})
add_executable(${PROJECT_NAME} ${SRC})

Build steps:

mkdir build
cd build
cmake ..          # or cmake -G Ninja ..
make   # or ninja

4.2 Cross‑Compilation Settings in CMake

Two approaches:

Directly set CMAKE_C_COMPILER, CMAKE_CXX_COMPILER, and CMAKE_LINKER in CMakeLists.txt.

Provide a separate toolchain file via -DCMAKE_TOOLCHAIN_FILE=toolchain.cmake that defines compiler paths, target system name ( Linux), and processor ( arm).

5. Major Differences When Porting V8 vs. Ordinary C++ Libraries

Ordinary libraries can be cross‑compiled by invoking the target toolchain directly. V8’s built‑ins and snapshots are generated by the mksnapshot tool, which runs JIT‑generated code during the build. Therefore, the host must simulate the target architecture.

5.1 Built‑ins

Built‑ins are native functions/modules compiled into V8 (e.g., Math, String, Date). They are generated by mksnapshot and stored in embedded.S. The source code for built‑ins lives in v8/src/builtins and is emitted as C++ or assembly via the CodeStubAssembler (CSA) API.

5.2 Snapshot

A snapshot serializes part of the JavaScript heap (objects, compiled bytecode, global state) so V8 can start quickly. mksnapshot can execute an optional script before serialization, ensuring that functions used by the script are pre‑compiled.

When cross‑compiling, mksnapshot uses a CPU simulator (e.g., simulator‑arm64.h) to run the generated built‑ins on the host, producing target‑specific assembly and snapshot data.

6. Detailed V8 Porting Steps

Compile mksnapshot for the host (e.g., macOS M1).

Run the host mksnapshot to generate ARM64 built‑ins and snapshot files ( embedded.S, snapshot.cc).

Use the HarmonyOS SDK toolchain (cmake + ninja) to compile embedded.S together with the rest of V8 source, producing a static library ( libv8_snapshot.a) for the target.

6.1 Build Environment

Host: macOS M1, Xcode 14.2. HarmonyOS SDK: DevEco Studio NEXT Beta5, HarmonyOS‑NEXT‑DB5. Target architecture: arm64‑v8a.

6.2 Build Commands

# Host build
mkdir build && cd build
cmake -G Ninja ..
ninja
# Copy host tools for later target build
cp bytecode_builtins_list_generator torque mksnapshot /usr/local/bin
# Target build
mkdir ohosbuild && cd ohosbuild
cmake -DOHOS_STL=c++_shared -DOHOS_ARCH=arm64-v8a -DOHOS_PLATFORM=OHOS \
      -DCMAKE_TOOLCHAIN_FILE=/Applications/DevEco-Studio.app/Contents/sdk/HarmonyOS-NEXT-DB5/openharmony/native/build/cmake/ohos.toolchain.cmake \
      -G Ninja ..
ninja

The resulting ohosbuild directory contains the HarmonyOS‑specific V8 static library ready for integration.

7. Using V8 in a HarmonyOS Native Project

Create a native C++ module in DevEco Studio.

Copy V8’s include directory and the compiled .a library into the module’s cpp folder.

Update the module’s CMakeLists.txt to set C++17 and link the V8 library.

Add NAPI methods to expose C++ functionality to JavaScript/TS.

Sample demo shows a simple NAPI export, its usage from the ArkTS side, and the runtime output.

8. Future Trends for JavaScript Engines

With the rise of IoT, lightweight execution is crucial. Strategies include:

Writing applications in TypeScript with strict typing.

Compiling TypeScript directly to bytecode, skipping the parse step at runtime.

Running bytecode on a lightweight interpreter that JIT‑compiles to target CPU code.

Removing dynamic‑language overhead (e.g., TurboFan) to reduce CPU, memory, and power consumption.

Facebook’s Hermes and HarmonyOS’s Panda engine follow similar principles, focusing on static typing and minimal runtime overhead.

Porting V8 to HarmonyOS is a substantial embedded‑systems effort involving cross‑compilation, CMake, GN, Ninja, C++, and Torque. While a native V8 build is possible, Huawei now provides a built‑in V8‑based JavaScript engine (c‑API) from API level 11, offering a more convenient integration path.