06e0899578
The vendored spork/http is gone — jpm owns janet packages. In its place: - The janet.* bridge autoloads jpm-installed modules on first reference: janet.spork.http/server requires spork/http from the module path and caches its bindings (failures are negatively cached). Works for any module, in every mode, including inside net/server connection fibers. - deps.edn grows a :jpm/module coordinate: jolt-deps verifies the module is importable at resolve time, optionally running `jpm install` on the :jpm/install package once when it isn't, and otherwise fails with the install hint. Contributes no source roots. ring-app declares spork/http this way. Docs: README's interop section, docs/tools-deps.md (:jpm/module reference), and the ring-app README (including the jpm-version caveat for spork HEAD's .janet native sources, which older jpm rejects).
129 lines
6.4 KiB
Markdown
129 lines
6.4 KiB
Markdown
# deps.edn support — design notes
|
|
|
|
How Jolt loads pure-Clojure libraries from a `deps.edn`, and why it's built the
|
|
way it is. For how to *use* it, see [building-and-deps.md](building-and-deps.md).
|
|
|
|
Scope, decided up front:
|
|
|
|
- **git + local deps only** — no Maven/`~/.m2` resolution.
|
|
- **pure `clj`/`cljc`** — anything needing the JVM won't load or run; expected.
|
|
- **no classpath abstraction** — `require` just needs to find a dep's namespaces;
|
|
"the classpath" is an ordered list of source directories.
|
|
- **piggyback on jpm** — reuse jpm's git fetch + cache; don't write a package
|
|
manager.
|
|
- **separate tool** — resolution lives in `jolt-deps`, beside the runtime, the
|
|
way `jpm` sits beside `janet`. The `jolt` runtime knows nothing about deps.edn.
|
|
|
|
## How jpm handles dependencies
|
|
|
|
jpm's package code (`jpm/pm.janet`) splits into a fetch half and a build half,
|
|
and we use only the first:
|
|
|
|
- **`resolve-bundle`** normalizes a dep spec to `{:url :tag :type :shallow}`,
|
|
accepting `:url`/`:repo` + `:tag`/`:sha`/`:commit`/`:ref`. A deps.edn
|
|
`{:git/url … :git/sha …}` maps straight onto it.
|
|
- **`download-bundle url :git tag shallow`** clones into a content-addressed cache
|
|
(`<modpath>/.cache/git_<tag>_<sanitized-url>`) and returns the path —
|
|
`git init` + `remote add` + fetch + reset, plus submodules. No build step.
|
|
- **`bundle-install`** is the half we skip: it then runs `project.janet` build
|
|
rules, which a Clojure lib doesn't have. It's cleanly separable from the clone.
|
|
|
|
So jpm gives us git resolution and a cache for free; calling `download-bundle`
|
|
needs `jpm/config/load-default` first (it sets `gitpath` and the cache dyns).
|
|
|
|
## How it works
|
|
|
|
`src/jolt/deps.janet` reads `deps.edn` (Janet parses it directly — EDN and Janet
|
|
syntax overlap for the `:deps`/`:paths` subset), then walks `:deps`:
|
|
|
|
- `:git/url` (+ `:git/sha` or `:git/tag`) → `resolve-bundle` + `download-bundle`
|
|
into `jpm_tree/.cache`;
|
|
- `:local/root` → the path as-is;
|
|
- `:mvn/*` and anything else → ignored.
|
|
|
|
Each resolved dependency contributes its own `:paths` (default `["src"]`) as
|
|
source roots; the walk is **breadth-first** so every top-level coordinate
|
|
registers before any transitive one — a top-level pin always wins, matching
|
|
tools.deps, and a coordinate conflict warns on stderr naming both. The result
|
|
is a de-duplicated, ordered list of directories. `resolve-deps-cached` memoizes
|
|
that list in the project-local `.cpcache/jolt-deps.jdn`, keyed on a hash of the
|
|
project `deps.edn` + the user-level `deps.edn` + the selected aliases. jpm is
|
|
loaded lazily (`require`, not `import`) so it's pulled in only when resolving —
|
|
never embedded in a built binary.
|
|
|
|
Three tools.deps features are mirrored in reduced form. **Aliases**: `:aliases`
|
|
entries supply `:extra-paths`/`:extra-deps` (accumulate across the aliases
|
|
selected with `-A:a:b`) and `:main-opts` (last-wins, run with `-M:alias`).
|
|
**User config**: a `deps.edn` under `$JOLT_CONFIG` (else
|
|
`$XDG_CONFIG_HOME/jolt`, else `~/.jolt`) merges beneath the project file,
|
|
per key, project wins. **Tasks**: the honest subset of babashka's — a string
|
|
task is a shell command, a map task is `{:main-opts […] :doc "…"}`; bare
|
|
Clojure expressions aren't supported because the reader hands back parsed
|
|
data, and round-tripping it to source isn't worth the fragility.
|
|
|
|
Clones default to a global sha-immutable cache (`$JOLT_GITLIBS`, else
|
|
`<config-dir>/gitlibs`) shared across projects, the `tools.gitlibs`
|
|
`~/.gitlibs` model; per-project trees remain available by passing `tree`
|
|
explicitly.
|
|
|
|
The loader (`evaluator.janet/find-ns-file`) resolves a namespace by searching the
|
|
context's `:source-paths` in order (the stdlib `src/jolt` first), trying `<ns>.clj`
|
|
then `<ns>.cljc`. Extra roots come from `JOLT_PATH` or `init`'s `:paths` option.
|
|
|
|
`jolt-deps` (`src/jolt/deps_cli.janet`, its own `declare-executable`) ties it
|
|
together: it resolves the roots and runs the `jolt` binary with them on
|
|
`JOLT_PATH`. The runtime's only dependency interface is that env var.
|
|
|
|
`jolt uberscript` bundles a namespace and everything it requires into one
|
|
standalone `.clj`. It requires the entry namespace and uses the order in which
|
|
the loader finishes loading files — a dependency finishes before the file that
|
|
required it, so the order is topological — then concatenates that source. The
|
|
baked-in stdlib is excluded (it's part of the runtime, not bundled).
|
|
|
|
Gotcha worth remembering: the `jolt` CLI's context is built into its image at
|
|
build time, so `JOLT_PATH` is applied at runtime in `main`, not in `init` (whose
|
|
env read would be frozen at build).
|
|
|
|
## Limitations
|
|
|
|
- Pure `clj`/`cljc` only — JVM interop, host classes, and unimplemented
|
|
`clojure.core` corners fail. Coverage is per-function: a namespace can load with
|
|
most functions working and a few not.
|
|
- Source only; compiled `.class` files in a git dep are ignored.
|
|
- git `:git/sha` must be a full SHA (`git fetch` can't resolve a short one).
|
|
|
|
## Conformance
|
|
|
|
`test/integration/deps-conformance-test.janet` resolves a few real pure-`cljc`
|
|
git libraries and reports whether their namespaces load and a sample call works.
|
|
It's network-gated behind `JOLT_CONFORMANCE=1` so CI stays offline. Use it to
|
|
check a library against the current interpreter, and to drive fixes for whatever
|
|
gap a failure points at (the same loop as the clojure-test-suite battery). A
|
|
library fails when it relies on something Jolt doesn't provide — JVM interop, or
|
|
a regex feature like Unicode property classes (`\p{…}`).
|
|
|
|
## Not yet
|
|
|
|
- **Compiling deps into a binary image.** `uberscript` already produces a
|
|
standalone `.clj`; baking a project's dependencies directly into a custom
|
|
executable image is a heavier variant that isn't implemented.
|
|
|
|
## Janet dependencies: `:jpm/module`
|
|
|
|
A jolt project can depend on janet libraries. jpm owns their installation;
|
|
`deps.edn` declares the requirement and `jolt-deps` verifies it at resolve
|
|
time:
|
|
|
|
```clojure
|
|
:deps {janet/spork-http {:jpm/module "spork/http"
|
|
:jpm/install "spork"}}
|
|
```
|
|
|
|
- `:jpm/module` — the janet module path that must be importable.
|
|
- `:jpm/install` (optional) — the jpm package to install when it isn't;
|
|
`jolt-deps` runs `jpm install <name>` once, then re-checks. Without it the
|
|
resolve fails with the install hint.
|
|
|
|
A `:jpm/module` dep contributes no source roots. At runtime the `janet.*`
|
|
interop bridge autoloads the module on first reference
|
|
(`janet.spork.http/server`, …), so nothing else is needed.
|