Merge pull request #174 from jolt-lang/spike/chez-bootstrap

ci: cover the jolt build pipeline on Linux; README binary docs

.github/workflows/tests.yml

@@ -14,18 +14,44 @@ jobs:
         with:
           submodules: recursive   # vendor/irregex, used by the Chez regex shim
 
-      - name: Install Chez Scheme
+      # Build Chez from source rather than the distro package: the apt
+      # chezscheme ships petite+scheme only, with no kernel dev files
+      # (libkernel.a, scheme.h), so `jolt build` (the buildsmoke gate) can't link
+      # a binary and would skip. The source build provides them, plus the libs the
+      # kernel links against.
+      - name: Install build dependencies
         run: |
           sudo apt-get update
-          sudo apt-get install -y chezscheme
-          # the gate invokes `chez`; Debian/Ubuntu installs it as `scheme`. A symlink
-          # won't do — Chez derives its boot-file name from argv0, so `chez` would look
-          # for a nonexistent chez.boot. A wrapper that exec's `scheme` keeps argv0.
-          if ! command -v chez >/dev/null 2>&1; then
-            printf '#!/bin/sh\nexec scheme "$@"\n' | sudo tee /usr/local/bin/chez >/dev/null
-            sudo chmod +x /usr/local/bin/chez
-          fi
-          chez --version || true
+          sudo apt-get install -y build-essential git liblz4-dev zlib1g-dev libncurses-dev uuid-dev
+
+      - name: Cache Chez Scheme
+        id: cache-chez
+        uses: actions/cache@v4
+        with:
+          path: /opt/chez
+          key: chez-${{ runner.os }}-v10.4.1-x11off
+
+      - name: Build Chez Scheme from source
+        if: steps.cache-chez.outputs.cache-hit != 'true'
+        run: |
+          git clone --depth 1 --branch v10.4.1 https://github.com/cisco/ChezScheme.git /tmp/chez-src
+          cd /tmp/chez-src
+          # --disable-x11: the expression editor's X11 clipboard isn't needed and
+          # would pull an X11 build/link dep.
+          ./configure --installprefix=/opt/chez --threads --disable-x11
+          make -j"$(nproc)"
+          sudo make install
+          sudo chown -R "$USER" /opt/chez
+
+      - name: Put chez on PATH
+        run: |
+          # Installed as `scheme`; the gate invokes `chez`. A wrapper that execs
+          # scheme keeps argv0 so Chez finds its boot files. Placed next to scheme
+          # so build.ss derives the csv dir (libkernel.a/scheme.h) from it.
+          printf '#!/bin/sh\nexec /opt/chez/bin/scheme "$@"\n' > /opt/chez/bin/chez
+          chmod +x /opt/chez/bin/chez
+          echo '/opt/chez/bin' >> "$GITHUB_PATH"
+          /opt/chez/bin/chez --version
 
       - name: Install JDK + Clojure (certify oracle)
         run: |
@@ -35,7 +61,9 @@ jobs:
           clojure --version
 
       - name: Gate
-        # `make ci` runs the behavior gates (corpus/unit/smoke/sci/certify). The
-        # self-host byte-fixpoint (make selfhost) is a dev-machine check — it only
-        # holds on the Chez that minted the seed. See jolt-8479.
+        # `make ci` runs the behavior gates (corpus/unit/smoke/buildsmoke/sci/
+        # certify). buildsmoke now links a real binary (the source-built Chez has
+        # the kernel dev files). The self-host byte-fixpoint (make selfhost) is a
+        # dev-machine check — it only holds on the Chez that minted the seed. See
+        # jolt-8479.
         run: make ci

README.md

@@ -45,6 +45,27 @@ $ bin/joltc -e '(/ 1 2)'
 1/2
 ```
 
+## Compile a binary
+
+`bin/joltc build` ahead-of-time compiles a project into a single self-contained
+executable — the runtime, `clojure.core`, the standard library, the app, and its
+`deps.edn` dependencies are linked in, so the result needs no Chez install, no
+JVM, and no source on disk to run.
+
+```bash
+bin/joltc build -m myapp.core -o myapp   # compile myapp.core's -main into ./myapp
+./myapp arg1 arg2                        # runs anywhere; args reach -main
+```
+
+Modes trade dynamism for speed: the default (release) build uses the proven code
+generator; `--opt` also runs the inference + scalar-replacement passes over the
+closed-world program; `--dev` is unoptimized.
+
+This needs Chez's kernel development files (`libkernel.a`, `scheme.h`) and a C
+compiler. They come with a from-source Chez install; a distro `chezscheme`
+package ships only the runtime, so `build` won't link a binary there.
+RFC 0007 (`docs/rfc/`) covers the design and the three-mode model.
+
 ## Architecture
 
 A small Chez runtime (`host/chez/*.ss`: value model, persistent collections, seqs,

host/chez/build.ss

@@ -86,8 +86,9 @@
         (string-append
           (if (> (string-length lz4) 0) (string-append "-L" lz4 "/lib ") "")
           "-llz4 -lz -lncurses -framework Foundation -liconv -lm"))
-      ;; Best-effort Linux/other; untested here.
-      "-llz4 -lz -lncurses -ldl -lpthread -lm"))
+      ;; Linux: the Chez kernel pulls in compression (lz4/z), the expression
+      ;; editor (ncurses + terminfo), threads, dlopen, libuuid, and clock_gettime.
+      "-llz4 -lz -lncurses -ltinfo -ldl -lm -lpthread -luuid -lrt"))
 
 ;; --- runtime manifest (mirrors host/chez/cli.ss's load order) ---------------
 (define bld-runtime-manifest