45876998ad
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).
110 lines
4.7 KiB
Markdown
110 lines
4.7 KiB
Markdown
# Jolt
|
|
|
|
[](https://github.com/jolt-lang/jolt/actions/workflows/tests.yml)
|
|
|
|
A Clojure implementation on [Chez Scheme](https://cisco.github.io/ChezScheme/).
|
|
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](https://cisco.github.io/ChezScheme/) (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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
make remint # iterates host/chez/bootstrap.ss to a byte-fixpoint
|
|
```
|
|
|
|
## Run
|
|
|
|
```bash
|
|
bin/joltc -e EXPR # evaluate a Clojure expression and print the result
|
|
```
|
|
|
|
```bash
|
|
$ 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](https://github.com/ashinn/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
|
|
|
|
```bash
|
|
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](test/conformance/SPEC.md).
|
|
|
|
## License
|
|
|
|
[Eclipse Public License 1.0](https://opensource.org/licenses/EPL-1.0)
|