Getting Started with WebKit
Build the browser application and matching native bridge before running web content in an existing Hera session.
A working WebKit embedding needs both the Rust application and a native libhera-wpe.so built against the target's WPE installation. Building the Rust package alone checks its API and application logic, but it does not produce the engine, subprocesses, or native bridge that page loading requires.
The steps below use the repository's browser as a complete example. Once that application works in the target environment, its host provides a reference for integrating the same package into another application.
Build the Rust Application
From the repository root, use the Hera builder and its configured SDK:
podman run --rm -v "$PWD":/work hera-builder:latest \
bash -lc 'cd /work && apps/browser/scripts/build-rust.sh'The wrapper delegates to build-rust.py, which shares the target environment setup with Hera's main build. It produces an optimized ARM64 application with locked, offline Cargo dependencies and stages the browser's font manifest and assets beside it. The builder must already contain the SDK and cached dependencies; HERA_SDK_ROOT and CARGO_TARGET_DIR select alternative locations.
Build a Compatible Engine and Bridge
The native CMake project requires wpe-webkit-2.0 version 2.54 or newer, WPEPlatform and its headless platform, EGL, GLESv2, and xkbcommon. Its shared library must match the architecture, libc, and WPE ABI installed on the device.
For the provided ARM64 build environment, run the following on an ARM64 host:
podman build -t hera-wpe-builder \
-f crates/webkit/native/Dockerfile apps/browser
podman run --rm -v "$PWD":/work hera-wpe-builder \
apps/browser/scripts/build-native.shThe Dockerfile builds the pinned WPE 2.54.1 source with checksum verification into /opt/wpe-2.54.1. If the target uses a different installation prefix, supply the matching WPE_PREFIX build argument. WebKit's subprocess paths are configured for that prefix, so the build and deployed engine locations must agree.
On a suitably prepared target, the app-owned scripts can instead build an isolated engine and bridge directly:
export HERA_WPE_PREFIX=/home/hera/wpe-2.54.1
apps/browser/scripts/build-wpe-sdk.sh
apps/browser/scripts/build-native.shInstall the development dependencies listed by the Dockerfile before taking this route. For cross-compilation, pass a matching toolchain file and sysroot to the native build script rather than linking against the build machine's WPE libraries.
Stage the Runtime Together
Deploy the built browser executable and libhera-wpe.so into the same application directory, with fonts.json and assets/ beside them. Place the launcher at scripts/run-pi.sh beneath that directory. The engine installation must include its subprocess executables, libraries, and resources, together with the runtime dependencies described in deployment.
Keeping the font assets in their existing layout lets the native toolbar resolve its registered icon face. The daemon needs a matching font registry for that toolbar; web page fonts remain managed by WebKit.
Open a Page
With a Hera desktop session already running on the device, launch the browser as an unprivileged client:
HERA_WPE_PREFIX=/home/hera/wpe-2.54.1 \
./scripts/run-pi.sh https://example.comThe launcher supplies the adjacent bridge and manifest, then reuses the desktop session bus or starts a temporary one. You can override the socket with --socket PATH, choose another bridge with --bridge PATH, or use --cpu to compare CPU frame export with the default path.
The first frame log reports the transport actually used. If page production or import fails, use the verification guide to distinguish engine startup, native export, scene submission, and display presentation.
Source Reference
The following files in the Hera checkout define the behavior described on this page.
apps/browser/scripts/build-rust.pyapps/browser/scripts/build-native.shapps/browser/scripts/build-wpe-sdk.shapps/browser/scripts/run-pi.shcrates/webkit/native/Dockerfilecrates/webkit/native/CMakeLists.txt