Module deps

Atom Dependency Handling

This module provides the core types for working with an Atom manifest’s dependencies. It defines the structure for specifying different types of dependencies in an atom’s manifest file, including atom references, direct Nix fetchers, and build-time sources.

Dependency Types

The manifest supports two main categories of dependencies:

• Atom dependencies ([deps.from.<set-name>]) - References to other atoms by label and version constraint.
• Direct Nix dependencies ([deps.direct.nix]) - Direct references to external sources using Nix fetchers (URLs, Git repos, tarballs, build-time sources).

Key Types

• Dependency - The main dependency structure containing all dependency types.
• AtomReq - Requirements for atom dependencies (version constraints).
• NixFetch - Direct Nix fetcher dependencies with optional version interpolation.

Manifest Format

Package Configuration

[package]
label = "my-atom"
version = "0.1.0"

[package.sets]
# Remote atom sets
company-atoms = "git@github.com:our-company/atoms"
# Local atom set (current repository)
local-atoms = "::"
# Sets with mirrors
public-atoms = ["https://registry-a.com/atoms", "https://registry-b.com/atoms"]

Atom Dependencies

[deps.from.company-atoms]
auth-service = "^1.5"
database = "^2.0"

[deps.from.local-atoms]
shared-utils = "^0.1"

Direct Nix Dependencies

[deps.direct.nix]
# URL fetch (direct download)
nix-installer.url = "https://nixos.org/nix/install"

# Git fetch with static ref (inline table syntax)
nixpkgs = { git = "https://github.com/NixOS/nixpkgs", ref = "nixos-unstable" }

# Git fetch with version constraint
other-repo = { git = "https://github.com/other/repo", version = "^1.2" }

# Alternative dotted syntax for simple cases
# nixpkgs.git = "https://github.com/NixOS/nixpkgs"
# nixpkgs.ref = "nixos-unstable"

# Tarball fetch with version interpolation
docs = { tar = "https://docs.company.com/api/__VERSION__/docs.tar.gz", version = "from.company-atoms.auth-service" }

# Build-time source (FOD)
source-archive = { build = "https://dist.company.com/my-atom/__VERSION__/source.tar.gz", version = "from.local-atoms.my-atom" }

Lockfile Format

The lockfile captures resolved dependencies with cryptographic hashes:

version = 1

[sets.<root-hash>]
tag = "company-atoms"
mirrors = ["git@github.com:our-company/atoms"]

[[deps]]
type = "atom"
label = "auth-service"
version = "1.5.2"
set = "<root-hash>"
rev = "<commit-hash>"
id = "<blake3-hash>"

[[deps]]
type = "nix+git"
name = "nixpkgs"
url = "https://github.com/NixOS/nixpkgs"
rev = "<commit-hash>"

Validation

All dependency types use #[serde(deny_unknown_fields)] to ensure strict validation and prevent typos in manifest files. Optional fields are properly handled with skip_serializing_if to keep the TOML output clean.

Structs

AtomReq

Represents a locked atom dependency, referencing a verifiable repository slice.

AtomWriter 🔒

Dependency

The dependencies specified in the manifest

DirectDeps 🔒

Represents different possible types of direct dependencies, i.e. those in the atom format

ManifestWriter

A writer for atom.toml manifests that ensures the atom.lock file is kept in sync.

NixFetch

Represents a nix fetch, either direct or tarball.

NixGit

Represents a nix eval-time git fetch.

NixSrc

Represents a dependency which is fetched at build time as an FOD.

TypedDocument 🔒

A newtype wrapper to tie a DocumentMut to a specific serializable type T.

Enums

DocError

Errors that can occur when working with a TypedDocument.

GitSpec

Represents the manner in which we resolve a rev for this git fetch

NixReq

Represents the underlying type of Nix dependency

Traits

WriteDeps 🔒

A trait for writing dependencies to a mutable TOML document representing an Atom manifest.

Functions

deserialize_url 🔒

Deserializes a gix::url::Url from a string.

not 🔒

A helper function for serde(skip_serializing_if) to omit false boolean values.

serialize_url 🔒

Serializes a gix::url::Url to a string.

Type Aliases

AtomFrom 🔒