simon/jolt

Yogthos 45876998ad Docs: Chez-only, drop the Janet-era references and obsolete migration notes

Bring the docs in line with the actual implementation now that Chez is the sole
substrate.

Deleted the migration/spike/handoff artifacts that only documented the Janet
era or the port effort: the port plan, phase-0 and foundational-runtime spike
writeups (+ the stray root-level copy), the self-hosting design notes, the
architecture-refactor plan, and spike/chez/RESULTS.md.

Rewrote the current reference docs against the Chez facts: building-and-deps and
tools-deps (no jpm/build step — bin/joltc off the checked-in seed, deps via
jolt.deps into ~/.jolt/gitlibs), libraries (SQLite is built-in jdbc.core over
libsqlite3, not a Janet driver), the conformance/spec test-flow docs (the Chez
corpus runner + certify, no .janet harnesses), and the transient / type-hint /
seed-overlay design notes (Chez representations: mutable transients, flat
copy-on-write vectors, HAMT maps, the seed/overlay twin). Fixed the README
collections line (vectors aren't 32-way tries) and added the ffi/transient gate
targets. rfc 0001's numerics open-question is resolved (the Scheme tower).

Renamed the built-in HTTP adapter to jolt.http.server only (dropped the
ring-janet.adapter alias — a Janet-era name).

2026-06-22 09:05:35 -04:00

4.7 KiB

Raw Blame History

Jolt

A Clojure implementation on Chez Scheme. Jolt reads Clojure source, analyzes it to a host-neutral IR, emits Scheme, and runs it on Chez. The compiler is self-hosted: it is written in Clojure (jolt-core/) and compiles itself. It ships a Clojure-compatible standard library.

Requirements

Only Chez Scheme (the gate invokes it as chez). The conformance gate additionally uses Clojure on the JVM as an oracle, but running jolt does not.

Build

There is no build step. The bootstrap seed (host/chez/seed/{prelude,image}.ss) is checked in, so a fresh clone runs immediately:

git clone --recurse-submodules https://github.com/jolt-lang/jolt.git
cd jolt
bin/joltc -e '(+ 1 2)'        # => 3

After changing a compiler source — the reader (host/chez/reader.ss), the analyzer/IR/backend (jolt-core/jolt/*.clj), or the clojure.core overlay (jolt-core/clojure/core/*.clj) — re-mint the seed:

make remint                   # iterates host/chez/bootstrap.ss to a byte-fixpoint

Run

bin/joltc -e EXPR             # evaluate a Clojure expression and print the result

$ bin/joltc -e '(->> (range 10) (filter even?) (map (fn [x] (* x x))) (reduce +))'
120
$ bin/joltc -e '(/ 1 2)'
1/2

Architecture

A small Chez runtime (host/chez/*.ss: value model, persistent collections, seqs, vars/namespaces, host interop) hosts a portable Clojure overlay (jolt-core/): the reader/analyzer/IR/backend (jolt-core/jolt/) and clojure.core in dependency-ordered tiers (jolt-core/clojure/core/NN-*.clj). The stdlib namespaces (clojure.string/set/walk/edn/pprint/…) are portable Clojure under src/jolt/clojure/.

bin/joltc loads the checked-in seed and the spine, then compiles and evaluates on Chez (read → analyze → IR → emit → eval). host/chez/bootstrap.ss rebuilds that seed from source on pure Chez; the build is a self-hosting fixpoint (a rebuild reproduces the checked-in seed byte-for-byte).

Differences from Clojure

Jolt targets Clojure semantics but runs on Chez, not the JVM.

Host platform. No JVM and no Java interop — import, gen-class, proxy of Java classes, and java.* are unavailable. A class token resolves to a name; a small set of host classes is recognized for instance?.
Numbers. The full Scheme numeric tower, matching the JVM: exact integers and bignums, exact ratios ((/ 1 2) ⇒ 1/2), and flonum doubles. = is category-aware ((= 3 3.0) ⇒ false); == is value-equality ((== 3 3.0) ⇒ true). integer?/int? are exact integers, float?/double? are flonums, ratio? is an exact non-integer. No BigDecimal (decimal? is always false).
Concurrency. future/promise/agent/pmap run on real OS threads over a shared heap, matching JVM semantics (not isolated-heap snapshots). Atoms use a per-atom mutex with JVM-style CAS. clojure.core.async provides blocking channels and go/<!/>!/alts!/timeout.
Regex. Backed by irregex (vendored), PCRE/Java-style patterns.
Collections. Immutable persistent vectors, cons lists, and HAMT maps/sets. Hash-map/hash-set iteration order is unspecified — use sorted-map/sorted-set when order matters. Transients are real mutable scratch collections.

Supported and Clojure-compatible: lazy/infinite sequences, transducers, destructuring, multimethods with hierarchies, protocols/records (deftype/defrecord/reify/extend-protocol), metadata, namespaces, runtime eval/load-string/defmacro, and the reader (#(), #_, #?, tagged literals, #"…").

Test

make test                     # the full gate
make corpus                   # conformance corpus vs the JVM-sourced spec
make unit                     # host-specific unit cases
make selfhost                 # bootstrap fixpoint (rebuild == checked-in seed)
make smoke                    # bin/joltc CLI smoke
make sci                      # load borkdude/sci's source through joltc (compat stress)
make ffi                      # HTTP-server GC-safety + http-client temp paths
make transient                # transient mutation + linear-time builds
make certify                  # JVM oracle (skips if clojure is absent)

The conformance corpus (test/chez/corpus.edn) is a host-neutral language spec whose expected values are sourced from reference JVM Clojure. See test/conformance/SPEC.md.

License

Eclipse Public License 1.0

4.7 KiB Raw Blame History