761a2b8f72
The reader expanded ^X form to (with-meta form X), which evaluated the tag (so
^String errored 'Unable to resolve symbol: String') and, as a param, was no
longer a bare symbol (so the arg bound to nil). Now a keyword/symbol/string hint
on a symbol attaches to the symbol's :meta and the symbol stays bare, so type
hints are transparent in params, lets, and bodies. Map metadata still uses a
runtime with-meta form.
meta now returns a symbol's :meta, and def applies the name's metadata
(^:dynamic, ^:private, ^Type tag, ^{:doc}) to the var, so (meta (var x)) is
consistent. Specs in metadata-spec; grammar note in the ebnf.
README notes regex \p{...} as unsupported (separate from this).
91 lines
4.6 KiB
Markdown
91 lines
4.6 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, and we recurse into its `deps.edn` for transitive deps. The result
|
|
is a de-duplicated, ordered list of directories. `resolve-deps-cached` memoizes
|
|
that list in the tree keyed on a hash of `deps.edn`, so an unchanged file doesn't
|
|
re-fetch. jpm is loaded lazily (`require`, not `import`) so it's pulled in only
|
|
when resolving — never embedded in a built binary.
|
|
|
|
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.
|