Dependencies and locks

Use kalandra install to fetch the source libraries declared in a manifest. Checking and compilation use the installed dependencies; they never download or update them automatically. Git is required for installation. Local repositories and public HTTPS repositories are supported.

For a local library that needs no Git checkout or lock, use a project package mapping instead.

• Map a local library directly

Create a local source library

Run this tutorial in a new empty directory using a POSIX shell. Create the library and application directories:

mkdir -p geometry/src my-app/src

Save the library manifest as geometry/kalandra.toml:

format = 1

[package]
name = "geometry"
version = "0.1.0"
entry = "src/public.k"

Save the public module as geometry/src/public.k:

export fn double(value: int) -> int:
  value * 2

Save the application as my-app/src/main.k:

from "geometry" import double

fn main() -> int:
  double(21)

Initialize a local Git repository, commit its files, then write the application manifest with the library's canonical absolute path. The identity settings apply only to this example commit:

git init --initial-branch=main geometry
git -C geometry add .
git -C geometry -c user.name="Docs Example" -c user.email="docs@example.invalid" -c commit.gpgsign=false commit -m "Initial library"
geometry_repo=$(cd geometry && pwd -P)
cat > my-app/kalandra.toml <<TOML
format = 1

[project]
entry = "src/main.k"

[dependencies]
geometry = { git = "$geometry_repo", rev = "main" }
TOML

A local repository needs an absolute canonical path. A public HTTPS repository can use its URL instead. rev accepts a full lowercase 40-digit commit ID or a supported branch/tag request; installation always records an exact commit in the lock. Abbreviated object IDs and arbitrary revision expressions are rejected.

Install, build and run

kalandra install --project my-app/kalandra.toml
kalandra-check --project my-app/kalandra.toml
kalandra --project my-app/kalandra.toml -o my-app/program
./my-app/program

The application returns 42. Each library resolves its own aliases and private dependency versions. Distinct source identities retain distinct nominal types.

Commit the lock

Commit kalandra.lock beside the application manifest. Keep the generated .kalandra cache out of version control. The lock records exact commits and source checksums for the complete dependency graph. Builds use those selections without rewriting the lock.

kalandra install --project my-app/kalandra.toml --frozen
kalandra install --project my-app/kalandra.toml --frozen --offline

Frozen installation requires a matching lock and preserves its exact selections. Frozen offline mode requires the selected snapshots already in the cache; it does not fetch missing sources. Move the complete project cache when you need an already installed project to build offline elsewhere.

Update deliberately

Change geometry/src/public.k to use value * 3, then commit the change and explicitly refresh the application's geometry dependency:

git -C geometry add .
git -C geometry -c user.name="Docs Example" -c user.email="docs@example.invalid" -c commit.gpgsign=false commit -m "Update multiplier"
kalandra update geometry --project my-app/kalandra.toml
kalandra-check --project my-app/kalandra.toml
kalandra --project my-app/kalandra.toml -o my-app/program
./my-app/program

The rebuilt program returns 63. Ordinary reinstall keeps the existing locked commit when a branch request has not changed. update refreshes the selected direct dependency while preserving unrelated locked selections. To change an exact revision or requested ref, edit the manifest and install normally. Existing executables do not change with their source lock.

Supported dependency sources

Authenticated/SSH transport, package registries, version-range solving and a public native-library ABI are not supported. A package is checked source, not an arbitrary build hook run during compilation.