Static Hermes (shermes) Setup and Usage Guide

Overview

Static Hermes is an experimental ahead-of-time compiler for JavaScript that compiles to native code via C. It provides type inference and optimization capabilities, though it's still in early development with various limitations.

Setup Instructions

1. Clone and Switch to Static Branch

git clone https://github.com/facebook/hermes.git
cd hermes
git checkout -b static_h origin/static_h

2. Build Static Hermes

# Configure the build with CMake
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug

# Build shermes and its dependencies
cmake --build ./build --target shermes-dep

# The shermes binary will be located at: build/bin/shermes

For a release build with optimizations:

cmake -S . -B build_release -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build ./build_release --target shermes-dep

Usage Commands

Execute JavaScript Directly

./build/bin/shermes -typed -exec script.js

Compile JavaScript to C Code

./build/bin/shermes -typed -emit-c -o output.c script.js

Debug Mode Execution

./build/bin/shermes -g -typed -exec script.js

Command Line Options

-typed - Enable type checking and optimizations
-exec - Execute the JavaScript file
-emit-c - Generate C code output
-o <file> - Specify output file for C code
-g - Enable debug mode

Example Scripts

1. Factorial Function (example1-factorial.js)

// Factorial calculation example
function factorial(n) {
  if (n <= 1) return 1;
  return n * factorial(n - 1);
}

function main() {
  print("Factorial of 5:", factorial(5));
  print("Factorial of 10:", factorial(10));
}

main();

2. Performance Benchmark (example2-benchmark.js)

// Benchmark example from the discussion
function bench(lc, fc) {
  var n, fact;
  var res = 0;
  while (--lc >= 0) {
    n = fc;
    fact = n;
    while (--n > 1)
      fact *= n;
    res += fact;
  }
  return res;
}

print("Benchmark result:", bench(1000, 20));

3. Typed Annotations (example3-typed.js)

// Example with typed annotations (experimental)
"use strict";

// @flow
function add(a /*: number */, b /*: number */) /*: number */ {
  return a + b;
}

function fibonacci(n /*: number */) /*: number */ {
  if (n <= 1) return n;
  return fibonacci(n - 1) + fibonacci(n - 2);
}

print("Add 5 + 3:", add(5, 3));
print("Fibonacci(10):", fibonacci(10));

4. Array Operations (example4-array-operations.js)

// Array operations example
"use strict";

function sumArray(arr) {
  var sum = 0;
  for (var i = 0; i < arr.length; i++) {
    sum += arr[i];
  }
  return sum;
}

function mapDouble(arr) {
  var result = [];
  for (var i = 0; i < arr.length; i++) {
    result[i] = arr[i] * 2;
  }
  return result;
}

// Create test array
var numbers = [1, 2, 3, 4, 5];

print("Original array:", numbers);
print("Sum of array:", sumArray(numbers));
print("Doubled array:", mapDouble(numbers));

Running the Examples

# Run factorial example
./build/bin/shermes -typed -exec example1-factorial.js

# Run benchmark with typed mode
./build/bin/shermes -typed -exec example2-benchmark.js

# Run typed example
./build/bin/shermes -typed -exec example3-typed.js

# Run array operations
./build/bin/shermes -typed -exec example4-array-operations.js

# Compile to C code
./build/bin/shermes -typed -emit-c -o factorial.c example1-factorial.js

Important Limitations

Experimental Status: Not ready for production use
TypeScript Support: Experimental and incomplete
Type Inference: Often defaults to any when uncertain
Standard Library: No built-in setTimeout or many standard functions
Legacy JS Classes: Not fully supported
Error Messages: May show warnings about type inference

Test Suite

Static Hermes includes test files in test/shermes/ directory. You can run these tests to verify your build:

# Example test run
./build/bin/shermes -exec test/shermes/function-props.js

References

GitHub Discussion: facebook/hermes#1137
Main Hermes Documentation: doc/BuildingAndRunning.md
Test Examples: test/shermes/ directory

Troubleshooting

If build fails, ensure you have all dependencies installed (CMake, Ninja, Python, ICU)
On macOS: brew install cmake git ninja
On Ubuntu: apt install build-essential cmake git ninja-build libicu-dev python3 tzdata libreadline-dev
Make sure you're on the static_h branch, not main%

tantaman/static_hermes.md