Content-address generated artifacts. The hash of the normalized spec, body, dependencies, options, Zig version, and target becomes the artifact path, so an unchanged form reuses its library and a changed form gets a fresh one. The JVM never reloads a stale library.
.clj-zig/cache/macos-aarch64/app.core/add-83a1c0f9e1b2dead/
source.zig
libadd-83a1c0f9e1b2dead.dylib
manifest.edn
This namespace owns the cache domain: the pure content-address logic (hashing, the cache key, artifact and resource paths, the module fingerprint primitives) and the effectful artifact resolution (filesystem fingerprinting, the classpath bundled-library lookup, the manifest, and the compile-or-reuse ensure-library!). The pure and effectful functions sit side by side behind section comments; the split is function-level, not namespace-level.
Content-address generated artifacts. The hash of the normalized spec,
body, dependencies, options, Zig version, and target becomes the artifact
path, so an unchanged form reuses its library and a changed form gets a
fresh one. The JVM never reloads a stale library.
.clj-zig/cache/macos-aarch64/app.core/add-83a1c0f9e1b2dead/
source.zig
libadd-83a1c0f9e1b2dead.dylib
manifest.edn
This namespace owns the cache domain: the pure content-address logic
(hashing, the cache key, artifact and resource paths, the module
fingerprint primitives) and the effectful artifact resolution
(filesystem fingerprinting, the classpath bundled-library lookup, the
manifest, and the compile-or-reuse ensure-library!). The pure and
effectful functions sit side by side behind section comments; the
split is function-level, not namespace-level.(artifact-paths {:keys [root] :as coords})The artifact directory and file paths for a build, under root
(default .clj-zig/cache). Each path component is checked, so a malformed
spec cannot write outside the cache.
The artifact directory and file paths for a build, under `root` (default `.clj-zig/cache`). Each path component is checked, so a malformed spec cannot write outside the cache.
(bundled-resource-path coords)The classpath resource path for a baked library, mirroring the cache
layout under the resource root. The library's content hash is in the
path, so a resource matches a function's hash for a target or it does
not. Components are checked, as in artifact-paths.
The classpath resource path for a baked library, mirroring the cache layout under the resource root. The library's content hash is in the path, so a resource matches a function's hash for a target or it does not. Components are checked, as in `artifact-paths`.
(cache-key {:keys [spec body source deps options zig-version target aux-files
modules]})The content hash for these build inputs. The generated source enters
the hash directly, so a change to the source generator yields a new key
even when the spec and body are unchanged; the spec, body, dependencies,
options, Zig version, and target enter it as well. A body that imports
other Zig files adds their contents under :aux, so editing an imported
file recompiles; a body with no imports hashes exactly as before. External
Zig modules enter as :modules, a name-to-fingerprint map, so a changed
module relinks its dependents while leaving every other key untouched.
The content hash for these build inputs. The generated `source` enters the hash directly, so a change to the source generator yields a new key even when the spec and body are unchanged; the spec, body, dependencies, options, Zig version, and target enter it as well. A body that imports other Zig files adds their contents under `:aux`, so editing an imported file recompiles; a body with no imports hashes exactly as before. External Zig modules enter as `:modules`, a name-to-fingerprint map, so a changed module relinks its dependents while leaving every other key untouched.
(clean!)(clean! root)Remove the entire artifact cache under root (default .clj-zig/cache).
Also clears the module-fingerprint memo so a post-clean build re-reads
module contents rather than reusing a fingerprint for a tree the cache
no longer holds.
Remove the entire artifact cache under `root` (default `.clj-zig/cache`). Also clears the module-fingerprint memo so a post-clean build re-reads module contents rather than reusing a fingerprint for a tree the cache no longer holds.
(content-fingerprint contents)The content fingerprint of a module's file closure: each file's path
paired with the hash of its contents. Order-independent, so it depends
only on the set of files and their contents. contents is a seq of
{:path :content} read by the effectful fingerprint path.
The content fingerprint of a module's file closure: each file's path
paired with the hash of its contents. Order-independent, so it depends
only on the set of files and their contents. `contents` is a seq of
`{:path :content}` read by the effectful fingerprint path.(dir-signature stats)A cheap, order-independent signature over a module's file closure, keyed
on each file's path, size, and mtime, no contents read. An untouched tree
yields the same signature; a changed size or mtime flips it. stats is a
seq of {:path :size :mtime} gathered by the effectful fingerprint path.
A cheap, order-independent signature over a module's file closure, keyed
on each file's path, size, and mtime, no contents read. An untouched tree
yields the same signature; a changed size or mtime flips it. `stats` is a
seq of `{:path :size :mtime}` gathered by the effectful fingerprint path.(ensure-library! {:keys [spec source root aux-files] :as inputs} compile!-fn)Return the cached artifact paths for these inputs, resolving a library
in three steps: a present filesystem artifact, then a baked library on
the classpath, then a fresh compile through compile!-fn. A baked
library is extracted into the cache and loaded without invoking Zig.
Identical inputs reuse a resolved library; any change resolves a fresh
path. inputs carries :spec, :body, :source, :deps, :options,
:zig-version, :target, and an optional :root.
Return the cached artifact paths for these `inputs`, resolving a library in three steps: a present filesystem artifact, then a baked library on the classpath, then a fresh compile through `compile!-fn`. A baked library is extracted into the cache and loaded without invoking Zig. Identical inputs reuse a resolved library; any change resolves a fresh path. `inputs` carries `:spec`, `:body`, `:source`, `:deps`, `:options`, `:zig-version`, `:target`, and an optional `:root`.
(evict! {:keys [spec root] :as inputs})Remove the single cached artifact for these inputs, so the next build
recompiles instead of reusing it. Inputs match ensure-library!.
Remove the single cached artifact for these `inputs`, so the next build recompiles instead of reusing it. Inputs match `ensure-library!`.
The filesystem reader module-fingerprint uses outside tests: :stat
gathers a closure's stat entries for the signature, :read its contents
for the fingerprint.
The filesystem reader `module-fingerprint` uses outside tests: `:stat` gathers a closure's stat entries for the signature, `:read` its contents for the fingerprint.
(git-fingerprint {:keys [git/sha root]})The fingerprint of a pinned :git/sha module reference, derived from
the sha and root alone: a pinned ref is already content-addressed, so no
file is read. The pinned counterpart of content-fingerprint for a dev
:path ref; module-fingerprint chooses between them.
The fingerprint of a pinned `:git/sha` module reference, derived from the sha and root alone: a pinned ref is already content-addressed, so no file is read. The pinned counterpart of `content-fingerprint` for a dev `:path` ref; `module-fingerprint` chooses between them.
(library-present? paths)True when a usable library exists. A zero-byte file (left by a failed build) does not count, so a poisoned path recompiles instead of loading an invalid library.
True when a usable library exists. A zero-byte file (left by a failed build) does not count, so a poisoned path recompiles instead of loading an invalid library.
(memoized-fingerprint entry signature compute)Resolve a module's fingerprint against a prior memo entry ({:signature :fingerprint}, or nil when none) and the current signature. Returns
[fingerprint next-entry]. When the signature matches the memo, the
fingerprint is reused and compute is never called; otherwise compute
produces a fresh fingerprint that the returned entry records. Pure; the
atom that carries the entry across calls is effectful.
Resolve a module's fingerprint against a prior memo `entry` (`{:signature
:fingerprint}`, or nil when none) and the current `signature`. Returns
`[fingerprint next-entry]`. When the signature matches the memo, the
fingerprint is reused and `compute` is never called; otherwise `compute`
produces a fresh fingerprint that the returned entry records. Pure; the
atom that carries the entry across calls is effectful.(module-fingerprint ref {:keys [stat read]})The fingerprint for one external module reference, the single value it
contributes to a dependent function's content hash (ADR 34). A
pinned :git/sha ref fingerprints from the sha and root, with no
filesystem read; a dev :path ref fingerprints its file closure, memoized
behind the cheap dir-signature so an unchanged tree reuses the
fingerprint without rereading contents. fs-io supplies :stat and
:read over the closure; tests inject fakes.
The fingerprint for one external module reference, the single value it contributes to a dependent function's content hash (ADR 34). A pinned `:git/sha` ref fingerprints from the sha and root, with no filesystem read; a dev `:path` ref fingerprints its file closure, memoized behind the cheap `dir-signature` so an unchanged tree reuses the fingerprint without rereading contents. `fs-io` supplies `:stat` and `:read` over the closure; tests inject fakes.
(module-roots modules)Each resolvable external module's root source path, keyed by import name,
for the compile shell to pass as -M<name>=<root>; nil when none resolve. A
pinned reference with no local checkout is omitted (ADR 36). The path
counterpart to modules-fingerprint, which feeds the content hash.
Each resolvable external module's root source path, keyed by import name, for the compile shell to pass as `-M<name>=<root>`; nil when none resolve. A pinned reference with no local checkout is omitted (ADR 36). The path counterpart to `modules-fingerprint`, which feeds the content hash.
(modules-fingerprint modules)(modules-fingerprint modules io)The fingerprint of each external module in a map from name to ref, keyed by import name, for the content hash; nil when there are none. Two wrappers over the same module share a fingerprint, so the cache stays content-addressed.
The fingerprint of each external module in a map from name to ref, keyed by import name, for the content hash; nil when there are none. Two wrappers over the same module share a fingerprint, so the cache stays content-addressed.
The classpath root under which a library ships its baked native code. The layout below it mirrors the filesystem cache, so a baked artifact is found by the same target, namespace, name, and hash.
The classpath root under which a library ships its baked native code. The layout below it mirrors the filesystem cache, so a baked artifact is found by the same target, namespace, name, and hash.
(read-manifest paths)Read the manifest for a built artifact, or nil when none exists. The manifest is written as data, so it round-trips through the EDN reader rather than the Clojure reader: a tampered cache dir cannot then craft a payload that leans on Clojure-reader quirks.
Read the manifest for a built artifact, or nil when none exists. The manifest is written as data, so it round-trips through the EDN reader rather than the Clojure reader: a tampered cache dir cannot then craft a payload that leans on Clojure-reader quirks.
(target-triple)The development target as <os>-<arch>, part of the cache key and the
artifact path.
The development target as `<os>-<arch>`, part of the cache key and the artifact path.
(write-manifest! paths
{:keys [spec deps options zig-version target]}
artifact-key)Write the human-readable manifest describing a built artifact.
Write the human-readable manifest describing a built artifact.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |