Dependencies

Ard dependencies are declared in ard.toml, resolved in ard.lock, and restored into a shared cache. Builds use the lockfile and cache; they do not fetch or update dependencies automatically.

Declaring dependencies

A project can depend on Git packages or local path packages:

name = "my_app"
ard = ">= 0.13.0"

[dependencies]
cooper = { git = "https://github.com/akonwi/cooper.git", commit = "76f7c1b" }
shared = { path = "../shared" }

The dependency key is the import root visible to the package that declares it:

use cooper
use shared/strings

Root modules

A bare dependency import loads that package’s root module. The root module is the file whose name matches the dependency’s name in its ard.toml.

For example, a dependency with this manifest:

name = "decode"

and this layout:

decode/
├── ard.toml
├── decode.ard
└── path.ard

can be imported as:

use decode       // loads decode.ard
use decode/path  // loads path.ard

You do not need to repeat the package name as use decode/decode. If a dependency alias differs from the package name, use the alias at the call site; Ard still finds the root module from the dependency’s manifest.

Dependency aliases are package-local. Your root project can import only its direct dependencies. A dependency’s own dependencies are available to that dependency, but they are not automatically re-exported into your root project’s import namespace.

Adding a Git dependency

Use ard add to add or update a Git dependency:

ard add github.com/akonwi/cooper@v0.1.0
ard add github.com/akonwi/cooper@76f7c1b as tui
ard add github.com/akonwi/cooper@latest

ard add:

1. resolves the requested tag, commit, or latest ref,
2. updates ard.toml,
3. writes the resolved graph to ard.lock, and
4. fetches Git dependencies into Ard’s shared cache.

Updating dependencies

Use ard update to move Git dependencies to the latest commit on their default branch:

ard update            # update every direct Git dependency
ard update cooper     # update one dependency
ard update cooper tui # update several

ard update:

1. resolves the latest commit for each target,
2. rewrites the dependency’s ard.toml entry to the resolved commit,
3. updates ard.lock, and
4. fetches the new commit into the shared cache.

A dependency that is already at the latest commit is left untouched. Path dependencies are skipped, since they track a local directory rather than a commit. The exception is a path dependency whose ard.lock entry still pins another source, such as a Git dependency you switched to a local checkout: ard update locks it to its path.

Updating pins the resolved commit for that Git source across the whole graph. If the same repository is also pulled in transitively by another dependency, it is updated there too — Ard keeps a single commit per Git source, and the explicit update wins over the commit a transitive dependency pinned.

You can still update a single dependency to a specific ref with ard add:

ard add github.com/akonwi/cooper@v0.2.0
ard add github.com/akonwi/cooper@latest

Lockfile and cache

ard.lock records the exact package graph used by the project, including resolved commits and cache integrity hashes. Commit ard.lock with your project.

Git dependencies are restored into Ard’s shared cache:

~/.ard/cache/git/<source-hash>/<commit>/

You can override the cache location with ARD_CACHE_DIR, which is useful for CI or tests.

Ordinary commands such as ard check, ard run, ard build, and ard test expect locked dependencies to already be present in the cache. If a cache entry is missing, run:

ard deps fetch

To verify that ard.lock matches ard.toml and that cached dependencies match ard.lock, run:

ard deps verify

ard.toml decides what each dependency is, and ard.lock only pins it. If you edit a Git dependency’s commit, tag, or git source by hand, commands fail with an “ard.lock is out of date” error, instead of building the previously locked commit. The error names the ard add command that locks the requested ref.

Removing a dependency

Remove a direct dependency with:

ard remove cooper

This removes the dependency entry from ard.toml and prunes unreachable packages from ard.lock.

Local path dependencies

Path dependencies point directly at a local package root:

[dependencies]
shared = { path = "../shared" }

They are resolved from the path in ard.toml and are not copied into the cache. Path dependencies are useful for local development across multiple packages.

To develop against an unpushed change to a Git dependency, point it at a local checkout:

[dependencies]
cooper = { path = "../cooper" }

Commands build the checkout right away, even though ard.lock still pins the Git commit. The checkout’s own Git dependencies reuse the commits ard.lock already pins for them. If the checkout adds or changes one, run ard update cooper to lock it. ard deps verify reports the mismatch, so a stale lock is not committed by accident. Either restore the Git entry when you’re done, or run ard update cooper to lock the path; this re-locks only that dependency.

FFI companions

Dependency packages may own Go FFI companions, such as ffi/*.go. The compiler routes extern calls to the package that declares them, so a dependency can provide both its Ard API and host-language implementation.

Validation

Every imported Ard module is type-checked by your compiler when it is loaded — project-owned modules and dependencies alike — and any diagnostics are reported against the module’s own source. If a dependency reports errors you did not write, it usually means the dependency has not been updated for your compiler version; pin an older compatible tag or update the dependency.

The standard library is the one exception: it ships inside the compiler and is validated when the compiler itself is built, so imports never re-report its internals.