javax.script Engine for JavaScript Based on V8

This is a V8-based javax.script engine for Java.

Prerequisites to build

• git
• make
• JDK 25 (set JAVA_HOME env. var to that JDK)
• Typical build utilities: bash, tar, zip, curl (often already present)
• Python 3 (required by V8 tooling)
• C/C++ toolchain for your OS
  • Linux: gcc/g++ or clang, plus common build packages (varies by distro)
  • macOS: Xcode Command Line Tools (xcode-select --install)

Quick Checks

git --version
make --version
python3 --version
${JAVA_HOME}/bin/java -version

Build and Test

• Clone the depot_tools into a directory outside this repo. This provides key tools used to fetch and build V8 (gclient, fetch, gn, ninja...).

  git clone https://chromium.googlesource.com/chromium/tools/depot_tools

• Set the depot_tools repo directory in PATH

  export PATH="<your-depot-tools-dir>:$PATH"

• To fetch/sync the V8 sources, specifically version 14.4.221 and dependencies:

  make get-v8

• To do a clean build:

  make clean all

• (Optional) To run jtreg tests:

  export JT_HOME=<your_jtreg_home_dir>
  make test

• To run the interactive shell:

  bash jjs.sh
  v8> java.lang.System.out.println("hello world")
  hello world
  v8> java.lang.System.exit(0)

• There are samples in the samples directory. To run a sample script:

  bash jjs.sh samples/helloworld.js

• There are also Java samples. To run a Java sample:

  bash run-java-sample.sh samples/HelloWorld.java

• To create a distribution bundle:

  make dist bundles

  The resulting .tar.gz bundle is written to build/<platform-specific-dir>/bundles/.

Enabling V8 flags via environment variable

JVMV8_FLAGS environment variable can be set with V8 flags

To enable dumping heap snapshot on out of memory crash

export JVMV8_FLAGS=--heap-snapshot-on-oom

To enable tracing/logging,

export JVMV8_FLAGS=--trace

export JVMV8_FLAGS=--trace-exception

export JVMV8_FLAGS=--log-all

• Recommended usage note

The "v8" engine provides access to many resources (types, objects) in the embedding Java runtime. As such, using this engine to run arbitrary or untrusted JavaScript code is strongly discouraged.

Users should prefer the "v8-no-java" engine, where access to Java resources has to be explicitly granted by the embedding Java application (e.g. by means of a callback function).

Moreover, when using both engines, it is recommended that script code be not interpolated with user input arguments without proper validation.