Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,37 @@ jobs:
grep -q 'href="/jolt-project/css/screen.css"' "$root/_site/guide/index.html" \
|| { echo "jolt build lost the base path"; exit 1; }

# serve binds with ring-chez-adapter under jolt (serve.jolt) and with
# http-kit under bb (serve.clj). This starts the jolt one on a free port
# and checks it answers under the base path, 404s outside it, and
# returns a binary asset byte for byte.
- name: Serve under jolt
run: |
set -euo pipefail
root="$(mktemp -d)/serve-project"
mkdir -p "$root/docs/guide" "$root/docs/media"
printf '# Serve\n\nServed by jolt.\n' > "$root/docs/guide/index.md"
printf '{:base-path "/serve-project" :asset-dirs ["media"]}\n' > "$root/docs/site.edn"
head -c 4096 /dev/urandom > "$root/docs/media/blob.bin"
port="$(python3 -c 'import socket; s = socket.socket(); s.bind(("127.0.0.1", 0)); print(s.getsockname()[1])')"
jolt run serve "$root" "$port" > serve.log 2>&1 &
pid=$!
trap 'kill "$pid" 2>/dev/null || true' EXIT
for _ in $(seq 1 120); do
grep -q '^Serving ' serve.log && break
kill -0 "$pid" 2>/dev/null || { cat serve.log; echo "jolt run serve exited"; exit 1; }
sleep 1
done
grep -q '^Serving ' serve.log || { cat serve.log; echo "jolt run serve never started"; exit 1; }
base="http://127.0.0.1:$port"
test "$(curl -s -o /dev/null -w '%{http_code}' "$base/serve-project/")" = 200 \
|| { echo "homepage not served under the base path"; exit 1; }
test "$(curl -s -o /dev/null -w '%{http_code}' "$base/elsewhere/")" = 404 \
|| { echo "a path outside the base path was not a 404"; exit 1; }
curl -s "$base/serve-project/media/blob.bin" | cmp - "$root/docs/media/blob.bin" \
|| { echo "binary asset changed in transit"; exit 1; }
echo "jolt run serve works"

# The tests build sites from fixtures, which proves the renderer but
# not that the engine works against a real project laid out on disk.
# This builds one end to end and checks the properties that actually
Expand Down
26 changes: 13 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,11 @@
The static-site generator behind jlt-commons project documentation. A project
writes markdown, and this turns it into a site that GitHub Pages serves.

It is a small babashka program, and `build`, `clean` and `test` also run
under `jolt` (jolt reads `bb.edn` tasks directly). `serve` still needs `bb`:
it binds the port with `http-kit`, which jolt doesn't have. External dependencies
(`markdown-clj`, `selmer`, and the `jolt-lang/yaml`/`jolt-lang/time` shims
that make those two resolve under jolt) are fetched on first run.
It is a small Clojure program that runs on `jolt`, which reads the tasks in
`bb.edn` directly. External dependencies (`markdown-clj`, `selmer`, the
`jolt-lang/yaml`/`jolt-lang/time` shims that make those two resolve under
jolt, and `ring-chez-adapter` for the preview server) are fetched on first
run. Every task also still runs under babashka as `bb <task>`.

## The idea

Expand Down Expand Up @@ -91,19 +91,19 @@ callout.
```bash
jolt run build ../your-project # generate ../your-project/_site/
jolt run clean ../your-project # delete the build output
jolt test # the test suite (or bb test)
bb serve ../your-project # build, then serve, honouring :base-path
bb serve ../your-project 4000
jolt run test # the test suite
jolt run serve ../your-project # build, then serve, honouring :base-path
jolt run serve ../your-project 4000
```

`build`, `clean` and `test` run under either tool. Under `jolt` it's
`jolt run <task>`, not bare `jolt <task>`: `build` collides with jolt's own
native `build -m NS` compiler subcommand. `serve` stays `bb`-only, since it
uses `http-kit`.
Use `jolt run <task>`, not bare `jolt <task>`, because `build` collides with
jolt's own native `build -m NS` compiler subcommand. The preview server binds
with `ring-chez-adapter` under jolt and with `http-kit` under bb, so
`bb serve` works the same way.

`_site/` is generated. Add it to the project's `.gitignore`.

`bb serve` mounts the build at the project's configured `:base-path`, so the
`jolt run serve` mounts the build at the project's configured `:base-path`, so the
local URL matches the deployed one. A project with `:base-path "/your-project"`
previews at `http://localhost:3000/your-project/`, and the server prints that
full URL when it starts. A root-hosted project is served at `/` as before.
Expand Down
30 changes: 17 additions & 13 deletions bb.edn
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,12 @@
;; unchanged (bb already has real java.time; this just adds tick's
;; API on top of it).
io.github.jolt-lang/time {:git/url "https://github.com/jolt-lang/time.git"
:git/sha "cdd785069e0e08a16c1ea9aae60f9532de21fad8"}}
:git/sha "cdd785069e0e08a16c1ea9aae60f9532de21fad8"}
;; The HTTP server behind `serve` under jolt. Only site/serve.jolt
;; requires it, and bb never loads that file (bb's serve.clj uses
;; http-kit, which bb bundles).
io.github.jolt-lang/ring-chez-adapter {:git/url "https://github.com/jolt-lang/ring-chez-adapter.git"
:git/sha "387cf67ea7b6a8573c6ee6abca6026a45bc3b6bf"}}
:tasks
{;; tick.core first, unconditionally -- see the io.github.jolt-lang/time
;; comment above :deps. Everything after it in this list, and every
Expand All @@ -53,20 +58,19 @@
(def project-dir
(fn []
(or (first *command-line-args*)
(do (println "Usage: bb <task> <path-to-project> [...]")
(println " e.g. bb serve ../raylib-jlt")
(do (println "Usage: jolt run <task> <path-to-project> [...]")
(println " e.g. jolt run serve ../raylib-jlt")
(System/exit 1)))))

info {:doc "What this is and how to point it at a project"
:task (do
(println "docs-engine — the jlt-commons documentation site generator\n")
(println " jolt run build <project> generate <project>/_site/")
(println " jolt run clean <project> delete <project>/_site/")
(println " jolt test run the test suite")
(println " bb serve <project> [port] build, then serve at localhost:3000\n")
(println "build/clean/test run under either tool (jolt run <task>, not bare jolt <task>:")
(println "build collides with jolt's own build -m NS subcommand). serve stays")
(println "bb-only: it uses http-kit.\n")
(println " jolt run build <project> generate <project>/_site/")
(println " jolt run clean <project> delete <project>/_site/")
(println " jolt run test run the test suite")
(println " jolt run serve <project> [port] build, then serve at localhost:3000\n")
(println "Use jolt run <task>, not bare jolt <task>: build collides with jolt's own")
(println "build -m NS subcommand. Every task also runs under babashka as bb <task>.\n")
(println "A project configures itself in docs/site.edn. See README.md."))}

test {:doc "Run the full test suite"
Expand All @@ -78,15 +82,15 @@
:task (let [{:keys [fail error]} (t/run-tests 'site.markdown-test 'site.project-test 'site.core-test 'site.search-test)]
(when (pos? (+ fail error)) (System/exit 1)))}

build {:doc "Generate a project's site into its _site/ (bb build <project>, or jolt run build <project>)"
build {:doc "Generate a project's site into its _site/ (jolt run build <project>)"
:requires ([site.core :as core])
:task (core/generate! (project/resolve-project (project-dir)))}

clean {:doc "Delete a project's _site/ build output (bb clean <project>, or jolt run clean <project>)"
clean {:doc "Delete a project's _site/ build output (jolt run clean <project>)"
:requires ([site.core :as core])
:task (core/clean! (project/resolve-project (project-dir)))}

serve {:doc "Build, then serve a project locally (bb serve <project> [port], default 3000)"
serve {:doc "Build, then serve a project locally (jolt run serve <project> [port], default 3000)"
:requires ([site.serve :as serve])
:task (serve/serve! (project/resolve-project (project-dir))
(second *command-line-args*))}}}
3 changes: 2 additions & 1 deletion src/site/core.clj
Original file line number Diff line number Diff line change
Expand Up @@ -380,7 +380,8 @@
;; Everything below builds a plain Ring handler `(fn [req]) -> {:status
;; :headers :body}` and touches no HTTP-server library at all, so it costs
;; build/clean/test nothing. site.serve is the thin wrapper that actually
;; binds a port, with org.httpkit.server, so `serve` runs under bb only.
;; binds a port: serve.clj with org.httpkit.server under bb/JVM, and
;; serve.jolt with ring-chez.adapter under jolt.
;; Splitting it this way is what makes build/clean/test loadable under jolt
;; at all — org.httpkit.server isn't resolvable there, and previously every
;; task here required it via this namespace regardless of whether it ever
Expand Down
5 changes: 3 additions & 2 deletions src/site/serve.clj
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,9 @@
library involved at all; this namespace is the thin wrapper around
org.httpkit.server that turns it into a running server.

http-kit isn't available under jolt, so `serve` is bb-only; no other
task requires this namespace."
Under jolt, site/serve.jolt replaces this file and binds with
ring-chez.adapter instead. No task other than `serve` requires this
namespace."
(:require [org.httpkit.server :as hk]
[site.core :as core]))

Expand Down
23 changes: 23 additions & 0 deletions src/site/serve.jolt
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
(ns site.serve
"The local preview server's jolt half. jolt resolves <ns>.jolt before
<ns>.clj, so under jolt this file replaces site/serve.clj, and bb and
the JVM never see it. site.core builds the Ring handler; this namespace
binds the port with ring-chez.adapter, which runs over jolt's own
sockets, where serve.clj uses http-kit."
(:require [ring-chez.adapter :as adapter]
[site.core :as core]))

(defn serve!
"Builds, then serves output-dir at http://localhost:<port><base-path>
until interrupted."
[project port-str]
(core/generate! project)
(let [port (Integer/parseInt (or port-str "3000"))
output-dir (:output-dir project)
base (core/base-path (:base-path project))]
;; ring-chez binds 127.0.0.1 by default; :host says so explicitly, since
;; this is a local-only preview server.
(adapter/run-server (core/make-static-handler output-dir base)
{:port port :host "127.0.0.1"})
(println (str "Serving " output-dir " at http://localhost:" port base "/"))
@(promise)))
Loading