API index¶

cl-nix-forge.lib.${system} is one flat attrset of 30 functions. This page lists all of them; each row links to its full entry.

The Module column preserves the lib/core/ versus lib/batteries/ distinction that the functional grouping of these pages cuts across. lib/core/ contains the core APIs. lib/batteries/ contains optional convenience APIs for common downstream flake patterns.

Building systems¶

See Building systems.

Function	Module	Summary
`lispDerivation`	`core/asdf-derivation.nix`	Build and test one or more ASDF systems from a source tree
`lispMultiDerivation`	`core/asdf-derivation.nix`	Several systems from one source tree, deduplicated
`mkLispSource`	`core/source.nix`	The `src` a Lisp build should see, as an allowlist
`lispWithSystems`	`core/asdf-derivation.nix`	A Lisp binary wrapped so it can load the given systems
`lispScript`	`core/asdf-derivation.nix`	Package a Lisp script with that dependency environment

Dependencies and native libraries¶

See Dependencies and native libraries.

Function	Module	Summary
`fromDerivation`	`core/external.nix`	Wrap any Nix derivation as a `lispDependencies` leaf
`fromNixpkgsLisp`	`core/external.nix`	Wrap a nixpkgs Lisp package, implementation required
`markNativeLibrary`	`core/native.nix`	Declare a derivation a producer of a native library
`nativeLibraryPath`	`core/native.nix`	`<drv>/lib` directories, `:`-joined
`nativeLibraryEnv`	`core/native.nix`	Those directories as a derivation `env` attrset
`nativeLibraryWrapperArgs`	`core/native.nix`	The same path as `makeWrapper` arguments
`libraryPathVar`	`core/native.nix`	`LD_LIBRARY_PATH` or `DYLD_LIBRARY_PATH` for this host

Checks and coverage¶

See Checks and coverage.

Function	Module	Summary
`mkTestCheck`	`batteries/checks.nix`	A named check running the derivation's `asdf:test-system`
`mkScriptCheck`	`core/script-check.nix`	A check through an arbitrary Lisp entry point
`mkCommandCheck`	`batteries/checks.nix`	Run a command, assert its artifacts, publish them as `$out`
`mkCheckMatrix`	`core/matrix.nix`	The same suite under several Lisp implementations
`mkCoverageReport`	`batteries/coverage.nix`	An sb-cover HTML report as a derivation (SBCL only)

Flake outputs and delivery¶

See Flake outputs and delivery.

Function	Module	Summary
`mkPackageFlake`	`batteries/package-flake.nix`	Every output an org-standard package's flake declares, as one call
`mkExecutable`	`batteries/app.nix`	Deliver a standalone binary via `asdf:program-op`
`mkApp`	`batteries/outputs.nix`	A flake `apps.<system>.<name>` entry for a derivation
`mkTestApp`	`batteries/outputs.nix`	`nix run .#test`, running the repo's `run-tests.lisp`
`mkOverlay`	`batteries/outputs.nix`	`overlays.default`, naming packages by their own `pname`
`mkDevShell`	`batteries/devshell.nix`	A `nix develop` shell with the resolved registry exported
`mkDocsSite`	`batteries/docs.nix`	A mkdocs-material site as a package
`collect`	`batteries/siblings.nix`	Pull named sibling packages out of flake inputs

Reading a `.asd`¶

See Reading a .asd.

Function	Module	Summary
`fromAsdSystem`	`batteries/version.nix`	The `:version` a `.asd` declares, as one string
`asdSystemVersions`	`batteries/version.nix`	The same extraction, keyed by system name
`asdSystemDependencies`	`batteries/version.nix`	The `:depends-on` names, keyed by system, for a given `features`

Internals¶

See Internals. Public implementation support, not the API to reach for first.

Function	Module	Summary
`ancestryWalker`	`core/dedup.nix`	The dependency walk that collapses same-source derivations
`unionAttrsBy`	`core/dedup.nix`	Union attrsets, folding collisions through a combiner

Keeping this page honest¶

The invariant is that this index and lib/default.nix name exactly the same 30 attributes. It is checkable in one command from the repository root:

nix eval --impure --json --expr \
  'let pkgs = import <nixpkgs> {}; in builtins.attrNames
     (import ./lib/default.nix { inherit (pkgs) lib; inherit pkgs; })'

A function added to lib/default.nix needs a row here and a full entry on the reference page for its group. checks.api-index-contract in flake.nix now enforces the first half: it reads this file and every attribute name lib/default.nix exports, and fails evaluation — before anything is built — naming each attribute that has no row. mkdocs build --strict (checks.docs) enforces the rest, since a row whose link target does not exist is a dead anchor.

The check searches for the linked form [`name`]( rather than a bare mention, because a bare mention is exactly the state it exists to reject: The check covers both the table row and the linked reference entry, so each exported attribute has one discoverable API entry.

The command above still answers "what is exported?" directly, which is the question to ask when writing the row rather than when verifying it.