Hermes (#176)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <noreply@github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: 4 people

.github/workflows/build-android.yml

@@ -13,10 +13,28 @@ env:
 jobs:
   build:
     runs-on: ubuntu-latest
-    timeout-minutes: 30
+    timeout-minutes: ${{ inputs.js-engine == 'Hermes' && 60 || 30 }}
     steps:
       - uses: actions/checkout@v5
 
+      # Hermes for Android builds the full LLVH/BCGen/Boost.Context/VM chain
+      # twice (once as host tools, once for x86_64 NDK) plus an emulator image.
+      # Default ubuntu-latest runners only ship ~14 GB free on /, which the
+      # combined output exhausts during `:app:buildCMakeDebug[x86_64]` (gradle
+      # then aborts with `java.io.IOException: No space left on device`).
+      # Reclaim space *before* anything is downloaded.
+      - name: Free up disk space (Hermes only)
+        if: inputs.js-engine == 'Hermes'
+        uses: jlumbroso/free-disk-space@main
+        with:
+          tool-cache: false
+          android: false
+          dotnet: true
+          haskell: true
+          large-packages: true
+          docker-images: true
+          swap-storage: true
+
       - uses: actions/setup-java@v4
         with:
           distribution: temurin
@@ -29,6 +47,12 @@ jobs:
         working-directory: Tests
         run: npm install
 
+      - name: Install Ninja (Hermes host-compiler bootstrap)
+        if: inputs.js-engine == 'Hermes'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y ninja-build
+
       - name: Enable KVM
         run: |
           echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules

.github/workflows/build-win32.yml

@@ -13,7 +13,10 @@ on:
 jobs:
   build:
     runs-on: windows-2022
-    timeout-minutes: 15
+    # Hermes pulls in a large LLVH/Boost.Context/BCGen chain through
+    # `hermesvm_a`; on `windows-2022` the full configure+build comfortably
+    # exceeds the standard 15-minute window.  Keep other engines snappy.
+    timeout-minutes: ${{ inputs.js-engine == 'Hermes' && 60 || 15 }}
     steps:
       - uses: actions/checkout@v5
 

.github/workflows/ci.yml

@@ -7,7 +7,7 @@ on:
     branches: [main]
 
 jobs:
-  # ── Win32 ─────────────────────────────────────────────────────
+  # Win32
   Win32_x86_Chakra:
     uses: ./.github/workflows/build-win32.yml
     with:
@@ -32,7 +32,13 @@ jobs:
       platform: x64
       js-engine: V8
 
-  # ── UWP ───────────────────────────────────────────────────────
+  Win32_x64_Hermes:
+    uses: ./.github/workflows/build-win32.yml
+    with:
+      platform: x64
+      js-engine: Hermes
+
+  # UWP
   UWP_x64_Chakra:
     uses: ./.github/workflows/build-uwp.yml
     with:
@@ -57,7 +63,7 @@ jobs:
       platform: x64
       js-engine: V8
 
-  # ── Android ───────────────────────────────────────────────────
+  # Android
   Android_JSC:
     uses: ./.github/workflows/build-android.yml
     with:
@@ -68,7 +74,12 @@ jobs:
     with:
       js-engine: V8
 
-  # ── macOS ─────────────────────────────────────────────────────
+  Android_Hermes:
+    uses: ./.github/workflows/build-android.yml
+    with:
+      js-engine: Hermes
+
+  # macOS (no Apple + Hermes until the upstream shutdown crash is fixed)
   macOS_Xcode164:
     uses: ./.github/workflows/build-macos.yml
     with:
@@ -124,7 +135,7 @@ jobs:
       runs-on: macos-26
       simulator: 'iPhone 17'
 
-  # ── Linux ─────────────────────────────────────────────────────
+  # Linux
   Ubuntu_gcc:
     uses: ./.github/workflows/build-linux.yml
 

CMakeLists.txt

@@ -32,6 +32,14 @@ FetchContent_Declare(CMakeExtensions
 FetchContent_Declare(googletest
     URL "https://github.com/google/googletest/archive/refs/tags/v1.17.0.tar.gz"
     EXCLUDE_FROM_ALL)
+FetchContent_Declare(hermes
+    GIT_REPOSITORY https://github.com/facebook/hermes.git
+    # Pinned to the tip of the `static_h` branch as of 2026-06-03 so CI is
+    # reproducible.  Bump this SHA when you intentionally want to pick up
+    # upstream Hermes changes — keep it on the static_h branch (Static
+    # Hermes is the variant our NAPI integration targets).
+    GIT_TAG 348582831f50954895da8e80cc91112d51036c69
+    EXCLUDE_FROM_ALL)
 FetchContent_Declare(ios-cmake
     GIT_REPOSITORY https://github.com/leetal/ios-cmake.git
     GIT_TAG 4.4.1
@@ -157,6 +165,148 @@ if(BABYLON_DEBUG_TRACE)
     add_definitions(-DBABYLON_DEBUG_TRACE)
 endif()
 
+if(NAPI_JAVASCRIPT_ENGINE STREQUAL "Hermes")
+    # Hermes is currently an experimental engine for JsRuntimeHost and is not
+    # supported on Apple platforms (iOS or macOS).  Bail out early with a
+    # clear error rather than letting the build fail deep inside Hermes's
+    # Apple framework / toolchain machinery.
+    if(APPLE OR IOS)
+        message(FATAL_ERROR
+            "NAPI_JAVASCRIPT_ENGINE=Hermes is not supported on Apple platforms "
+            "(iOS or macOS).  Hermes support in JsRuntimeHost is experimental "
+            "and currently limited to Windows, Android, and Linux.")
+    endif()
+
+    # Configure Hermes static_h options BEFORE making it available so that
+    # cache variables take effect.  We disable the parts of Hermes we don't
+    # need (the unit-test suite, debugger) to keep build time reasonable and
+    # to avoid pulling extra targets into our build tree.  Notably we leave
+    # HERMES_ENABLE_NAPI ON (the default) — that's the whole point of
+    # integrating Hermes here.
+    #
+    # HERMES_ENABLE_TOOLS must stay ON: even when HERMES_ENABLE_TEST_SUITE is
+    # OFF, Hermes unconditionally adds external/node-api-cts and
+    # external/node-api-tests whenever HERMES_ENABLE_NAPI is on, and those
+    # subdirectories reference the `hermes` CLI tool target via
+    # $<TARGET_FILE:hermes>.  CMake fails to generate if the target doesn't
+    # exist, so we let Hermes build its tools.  None of them ship in our
+    # final binaries because they're EXCLUDE_FROM_ALL via FetchContent.
+    set(HERMES_ENABLE_TOOLS ON CACHE BOOL "" FORCE)
+    set(HERMES_ENABLE_TEST_SUITE OFF CACHE BOOL "" FORCE)
+    set(HERMES_ENABLE_DEBUGGER OFF CACHE BOOL "" FORCE)
+    set(HERMES_BUILD_APPLE_FRAMEWORK OFF CACHE BOOL "" FORCE)
+    set(HERMES_ENABLE_NAPI ON CACHE BOOL "" FORCE)
+    if(ANDROID)
+        # JsRuntimeHost's Android test app embeds Hermes directly, without
+        # Hermes's React Native Android/fbjni packaging.  Unicode-lite avoids
+        # pulling ICU/fbjni into this standalone N-API build.
+        set(HERMES_UNICODE_LITE ON CACHE BOOL "" FORCE)
+    endif()
+    # Hermes defaults HERMES_SLOW_DEBUG=ON, which compiles in internal
+    # sanity checks that fire even in optimized (RelWithDebInfo / Release)
+    # builds — e.g. heap-state assertions in HadesGC and the finalizer
+    # chain.  These can SIGABRT during Runtime teardown on some platforms
+    # (observed on macOS arm64 RelWithDebInfo: process exited with code
+    # 134 right after `145 passing`, before any gtest [OK] line, with no
+    # diagnostic in stderr).  Embedders don't need them.
+    set(HERMES_SLOW_DEBUG OFF CACHE BOOL "" FORCE)
+    # Hermes vendors Boost.Context (external/boost/boost_1_86_0/libs/context).
+    # The default fcontext implementation needs the platform-native assembler
+    # for context switching.  On Windows + MSBuild, MASM picks up CXX compile
+    # flags like /Zc:__cplusplus from the surrounding scope, emits A4018
+    # warnings for every prefix substring, eventually bails out before writing
+    # boost_context_obj.dir\Release\make_x86_64_ms_pe_masm.obj, and the link
+    # step fails with LNK1181.  Switch to the Win32 Fiber-based implementation
+    # (winfib) — no assembler needed, no MASM problem.  Hermes only uses the
+    # fiber API (per a comment in the bundled boost CMakeLists), so winfib is
+    # functionally equivalent for this embedder.
+    if(WIN32)
+        set(BOOST_CONTEXT_IMPLEMENTATION "winfib" CACHE STRING "" FORCE)
+    endif()
+    # ------------------------------------------------------------------
+    # Cross-compilation: bootstrap the Hermes host compilers automatically.
+    #
+    # `hermesc`/`shermes` are HOST tools that Hermes runs at build time (to
+    # emit InternalBytecode and, in -emit-c mode, the native internal unit).
+    # When cross-compiling (e.g. the Android NDK build) the in-tree Hermes
+    # tool targets are built for the *target* and can't run on the build host,
+    # so Hermes must be handed prebuilt HOST compilers via the standard
+    # IMPORT_HOST_COMPILERS mechanism (it `include()`s a CMake file that
+    # Hermes `export()`s when those tools are built).
+    #
+    # Rather than require a separate, manual "build host compilers" CI step
+    # plus a -DIMPORT_HOST_COMPILERS=... hand-off, do it here: configure and
+    # build a native (host-toolchain) copy of hermesc/shermes from THIS source
+    # tree, then point Hermes at the ImportHostCompilers.cmake it produces.
+    #
+    # This runs at configure time (via execute_process) on purpose: Hermes
+    # consumes IMPORT_HOST_COMPILERS during its own configure, so the exported
+    # file must already exist before FetchContent_MakeAvailable(hermes) below.
+    # An explicit -DIMPORT_HOST_COMPILERS=... still wins and skips the
+    # bootstrap, preserving the manual/prebuilt path.
+    if(CMAKE_CROSSCOMPILING AND NOT IMPORT_HOST_COMPILERS)
+        # Shared, source-relative location so the host tools are built once and
+        # reused across target ABIs (/Build is git-ignored).
+        set(_jsrh_hermes_host_dir "${CMAKE_CURRENT_SOURCE_DIR}/Build/HermesHostTools")
+        set(_jsrh_hermes_host_import "${_jsrh_hermes_host_dir}/ImportHostCompilers.cmake")
+
+        if(NOT EXISTS "${_jsrh_hermes_host_import}")
+            message(STATUS "Hermes: bootstrapping host compilers (hermesc/shermes) for cross-compilation")
+
+            # Prefer Ninja when available; otherwise fall back to the host's
+            # default generator (Unix Makefiles).
+            find_program(_jsrh_host_ninja ninja)
+            if(_jsrh_host_ninja)
+                set(_jsrh_host_generator -G Ninja)
+            else()
+                set(_jsrh_host_generator "")
+            endif()
+
+            # Configure a native build from the same source tree.  No toolchain
+            # file is passed, so CMake selects the host compiler.  Tests are
+            # off and unicode-lite is on to keep this bootstrap lean.
+            execute_process(
+                COMMAND "${CMAKE_COMMAND}"
+                    ${_jsrh_host_generator}
+                    -S "${CMAKE_CURRENT_SOURCE_DIR}"
+                    -B "${_jsrh_hermes_host_dir}"
+                    -D CMAKE_BUILD_TYPE=Release
+                    -D NAPI_JAVASCRIPT_ENGINE=Hermes
+                    -D HERMES_UNICODE_LITE=ON
+                    -D JSRUNTIMEHOST_TESTS=OFF
+                RESULT_VARIABLE _jsrh_host_cfg_result)
+            if(NOT _jsrh_host_cfg_result EQUAL 0)
+                message(FATAL_ERROR
+                    "Hermes host-compiler bootstrap: configure failed (${_jsrh_host_cfg_result}).")
+            endif()
+
+            execute_process(
+                COMMAND "${CMAKE_COMMAND}" --build "${_jsrh_hermes_host_dir}"
+                    --target hermesc shermes --config Release
+                RESULT_VARIABLE _jsrh_host_build_result)
+            if(NOT _jsrh_host_build_result EQUAL 0)
+                message(FATAL_ERROR
+                    "Hermes host-compiler bootstrap: build failed (${_jsrh_host_build_result}).")
+            endif()
+        endif()
+
+        if(NOT EXISTS "${_jsrh_hermes_host_import}")
+            message(FATAL_ERROR
+                "Hermes host-compiler bootstrap did not produce ${_jsrh_hermes_host_import}.")
+        endif()
+
+        set(IMPORT_HOST_COMPILERS "${_jsrh_hermes_host_import}" CACHE FILEPATH
+            "Imported Hermes host compilers (hermesc/shermes) for cross-compilation" FORCE)
+        message(STATUS "Hermes: using bootstrapped host compilers at ${IMPORT_HOST_COMPILERS}")
+    endif()
+
+    # Hermes ships its own bundled gtest as `llvh-gtest` (a different
+    # CMake target name from googletest's `gtest`), so the two coexist
+    # without clashing.  We never link llvh-gtest into our UnitTests
+    # executable, so there's no duplicate-symbol issue at link time.
+    FetchContent_MakeAvailable_With_Message(hermes)
+endif()
+
 if(NAPI_JAVASCRIPT_ENGINE STREQUAL "V8" AND JSRUNTIMEHOST_CORE_APPRUNTIME_V8_INSPECTOR)
     FetchContent_MakeAvailable_With_Message(asio)
     add_library(asio INTERFACE)

Core/AppRuntime/CMakeLists.txt

@@ -22,6 +22,23 @@ target_link_libraries(AppRuntime
     PRIVATE arcana
     PUBLIC JsRuntime)
 
+# AppRuntime_macOS.mm / AppRuntime_iOS.mm call NSLog (Foundation) and other
+# Apple ObjC++ APIs.  Xcode's "Link Frameworks Automatically" setting auto-
+# links Foundation/CoreFoundation/UIKit for ObjC translation units, so the
+# default `-G Xcode` macOS/iOS builds work without an explicit link.  Other
+# generators (notably Ninja, which we use for the Hermes macOS CI job to
+# work around the Xcode "new build system" rejecting Hermes's multi-target
+# generated source) leave those frameworks unresolved.  Declaring them
+# PUBLIC here propagates them onto the final executable's link line for
+# every generator, and also covers other Apple-side static deps in the
+# tree (e.g. UrlLib's `UrlRequest_Apple.mm` reference to NSBundle) without
+# needing to patch the dep itself.
+if(APPLE)
+    target_link_libraries(AppRuntime
+        PUBLIC "-framework Foundation"
+        PUBLIC "-framework CoreFoundation")
+endif()
+
 if(NAPI_JAVASCRIPT_ENGINE STREQUAL "V8" AND JSRUNTIMEHOST_CORE_APPRUNTIME_V8_INSPECTOR)
     add_subdirectory(V8Inspector)
 

Core/AppRuntime/Include/Babylon/AppRuntime.h

@@ -67,6 +67,15 @@ namespace Babylon
         // extra logic around the invocation of a dispatched callback.
         void Execute(Dispatchable<void()> callback);
 
+        // Engine-specific hook called from Dispatch immediately after a user
+        // callback completes.  Most engines auto-drain microtasks at scope
+        // exit, so the implementation is a no-op for Chakra/V8/JSC/JSI.
+        // Hermes does NOT auto-drain; its implementation calls
+        // `Napi::DrainJobs(env)` so Promise continuations and queueMicrotask
+        // callbacks scheduled during the user callback actually run before
+        // the next top-level dispatch.
+        void DrainMicrotasks(Napi::Env env);
+
         Options m_options;
 
         class Impl;

Core/AppRuntime/Source/AppRuntime.cpp

@@ -109,6 +109,13 @@ namespace Babylon
     {
         m_impl->Append([this, func{std::move(func)}](Napi::Env env) mutable {
             Execute([this, env, func{std::move(func)}]() mutable {
+                // Some engines (notably Hermes) require an open NAPI handle
+                // scope before any napi_* call that materializes a value.
+                // The other engines (V8/Chakra/JSC) already provide an outer
+                // scope at the RunEnvironmentTier level, so this extra
+                // scope is harmless there but mandatory for Hermes.
+                Napi::HandleScope scope{env};
+
                 try
                 {
                     func(env);
@@ -122,6 +129,13 @@ namespace Babylon
                     assert(false);
                     std::abort();
                 }
+
+                // Drain engine-level microtasks/jobs queued during the
+                // callback (Promise continuations, queueMicrotask, etc.) so
+                // they run before the next top-level Dispatch.  No-op for
+                // engines that drain automatically; Hermes needs an explicit
+                // pump.
+                DrainMicrotasks(env);
             });
         });
     }

Core/AppRuntime/Source/AppRuntime_Chakra.cpp

@@ -71,4 +71,11 @@ namespace Babylon
         // Detach must come after JsDisposeRuntime since it triggers finalizers which require env.
         Napi::Detach(env);
     }
+
+    void AppRuntime::DrainMicrotasks(Napi::Env)
+    {
+        // Chakra drains promise continuations through its
+        // JsSetPromiseContinuationCallback hook (see RunEnvironmentTier).
+        // No explicit pump needed here.
+    }
 }

Core/AppRuntime/Source/AppRuntime_Hermes.cpp

@@ -0,0 +1,28 @@
+#include "AppRuntime.h"
+#include <napi/env.h>
+
+namespace Babylon
+{
+    void AppRuntime::RunEnvironmentTier(const char*)
+    {
+        // All Hermes runtime + napi_env setup is encapsulated inside the napi
+        // library's env_hermes.cc (see Napi::Attach/Detach).  Keeping the
+        // engine-specific machinery there avoids dragging Hermes headers into
+        // AppRuntime's translation unit.
+        Napi::Env env = Napi::Attach();
+
+        Run(env);
+
+        Napi::Detach(env);
+    }
+
+    void AppRuntime::DrainMicrotasks(Napi::Env env)
+    {
+        // Hermes does not auto-drain its job queue.  Promise continuations,
+        // queueMicrotask callbacks, and pending NAPI finalizers all run via
+        // Runtime::drainJobs().  We pump it after each user callback so async
+        // code (Promises, Mocha's async tests, polyfill schedulers, etc.)
+        // observes the same "between turns" semantics it gets on V8/Chakra.
+        Napi::DrainJobs(env);
+    }
+}

Core/AppRuntime/Source/AppRuntime_JSI.cpp

@@ -45,4 +45,9 @@ namespace Babylon
 
         Napi::Detach(env);
     }
+
+    void AppRuntime::DrainMicrotasks(Napi::Env)
+    {
+        // JSI/V8 backed JSI auto-drains microtasks per scope.
+    }
 }