Rhino JavaScript Engine

Rhino is organized into several Java modules. Choose the modules based on your integration needs:

• rhino: The core runtime. Required for all users.
• rhino-tools: Includes the shell, debugger, and the Global object (provides print, load, etc.). Use this if you need a full development environment, but be aware it includes potentially 'dangerous' functions like file system access.
• rhino-xml: Required only if you need the E4X XML standard implementation.
• rhino-engine: Implements the standard Java ScriptEngine interface. Recommended only for projects that need to switch between different script engines; otherwise, use the Rhino API directly for better flexibility.
• rhino-all: An 'all-in-one' JAR containing rhino-runtime, rhino-tools, and rhino-xml. Best for running via java -jar.
• rhino-kotlin: Enhanced support for Kotlin code.

Rhino has specific Java version requirements:

• To Run: Requires Java 17 or higher.
• To Build: Requires Java 21 or higher (Java 25 is highly recommended).

The build uses the --release flag to ensure compatibility with Java 17 features.

Rhino uses the spotless plugin for code formatting. If your build fails due to formatting violations, use the spotlessApply Gradle task to reformat the necessary files.

Requirement: You must be building on Java 17 or higher for Spotless to run.

Rhino benchmarks are executed using the JMH framework via Gradle. To run all available benchmarks, execute the jmh task from the top-level directory of the project.

Use the BENCHMARK environment variable to filter benchmarks using a regular expression matching their names. Use the EVALMODE environment variable to switch between Interpreter and Compiler modes.

To run Android integration tests, you must have an Android SDK installed. You have two options:

1. System-wide installation: Install Android Studio with the SDK and ensure your ANDROID_HOME environment variable is correctly configured.
2. Local project installation (Recommended): Use the provided script to install the SDK locally within the project directory. This avoids modifying your system settings and registers the SDK in local.properties for this Gradle build only.

Run the following script from the <RHINO_ROOT>:

./install-android-sdk

Note: This script automatically accepts all license terms and installs the SDK into <RHINO_ROOT>/android-sdk.

The V8 Benchmark Suite is a collection of pure JavaScript benchmarks used for tuning JavaScript engines. To use the suite, you must follow these requirements:

1. Load the Framework: You must load base.js (the benchmark framework) before loading any individual benchmark files.
2. Choose a Runner:
   • HTML version: Use run.html for running benchmarks in a web browser.
   • Standalone JavaScript version: Use run.js for running benchmarks in a JavaScript environment (like Node.js or Rhino).

Individual benchmark licenses are included within their respective JavaScript files.

To contribute to Rhino, follow these steps:

1. Run ./gradlew check to ensure the entire build passes, including code formatting, style checks, and tests.
2. Write tests for your changes. You can use existing tests in testsrc/org/mozilla/javascript/tests as a guide.
3. If fixing ECMAScript spec compatibility, check test262.properties to see if any tests can be re-enabled.
4. Push your changes to GitHub and open a pull request.

Rhino supports remapping stack-trace line numbers, parser error positions, and debugger source handoffs back to the original source using source maps. This feature is opt-in: you must attach a SourceMapper to a ScriptCompileSpec during compilation.

Once attached:

• RhinoException.lineNumber() reports the original source line.
• Parser error messages quote the original source text.
• The debugger receives the primary original source content at compilation time.

SourceMapV3 mapper = SourceMapV3.parse(mapJsonString);

Script script = cx.compileScript(
    ScriptCompileSpec.fromSource(transpiledSource)
        .sourceName("bundle.js")
        .sourceMapper(mapper)
        .build());

You can test your changes against different JDKs by setting the RHINO_TEST_JAVA_VERSION environment variable. This requires that the appropriate JDK is installed and discoverable by Gradle.

To troubleshoot JDK discovery, use ./gradlew -q javaToolchains.

RHINO_TEST_JAVA_VERSION=17 ./gradlew check

To run the full test suite, you must first initialize and update the git submodules, then execute the Gradle check task.

git submodule init
git submodule update
./gradlew check

If you want to create a single JAR file that includes the runtime, tools, and XML implementation (equivalent to rhino-all), use the shadowJar task. You can then run it directly using the java -jar command.

./gradlew shadowJar
java -jar rhino-all/build/libs/rhino-all-2.0.0-SNAPSHOT.jar

To build and run the Rhino shell using the Gradle wrapper, use the following command. This is the quickest way to get a shell running for development.

Note: For the best command-line editing experience, use the shadowJar or classpath methods described in the building section, as the Gradle wrapper can interfere with JLine's terminal manipulation.

./gradlew run -q --console=plain