Eka: A Foundational Frontend for a Better Nix Experience

⚠️ Warning: Eka is in early experimental stages. Features are unstable and subject to change.

This repository currently contains eka, a next-generation frontend for the Ekala Project's Nix-based infrastructure. Unlike the vast majority of existing Nix tooling, eka is not a wrapper around the nix CLI. It is a fundamentally new, native tool designed to provide a more efficient, approachable, and decentralized development experience.

This work is centered on four core components, which will eventually be unified into a single monorepo:

• Eka: A user-facing CLI that provides a reasonable, statically-determinable interface for managing dependencies and builds.
• Atom-Nix: A Nix module system for evaluating atoms.
• Atom Format: A verifiable, versioned, and git-native format for publishing source code, designed for decentralized distribution and end-to-end integrity.
• Eos (Future): A planned distributed, content-addressed build scheduler that will eventually power Eka's evaluation backend.

Design Goals

• Disciplined: Eka focuses on its area of expertise: providing a fast, intuitive interface for managing dependencies with no external binary dependencies. It maintains a clean separation of concerns, delegating the heavy lifting of evaluation and building to a dedicated scheduler (Eos).
• Fast: The dependency management commands in eka are designed to be exceptionally fast, operating primarily on static metadata. Querying, resolving, and locking atoms are near-instantaneous operations.
• Conceptually High-Level: Developers care about packages, versions, security, and reproducibility, not the nitty-gritty of Nix derivations. Eka provides an interface that speaks to developers at their level of concern, while still providing a powerful gateway to the guarantees that Nix and the Atom Format provide.

Core Concepts

The Atom Format: Verifiable, Versioned Repository Slices

Atoms are the fundamental building block of the Ekala ecosystem. An atom is a cryptographically secure, content-addressed, and uniquely identifiable slice of a Git repository. This is achieved through a git-native publishing model that eliminates the need for a central registry.

Key Features:

• Repository Identity: Every repository of atoms has a unique identity derived from its root commit.
• Git-Native Publishing: Atoms are published as new, lightweight references to pre-existing Git objects, with no copying of source files.
• Temporal Conflict Resolution: The system enforces that no two atoms in the same commit can share the same atom.tag, guaranteeing a unique cryptographic ID.
• Efficient Version Discovery: Atom versions are published to a queryable, decentralized index of Git references.

The Atom URI: A User-Friendly Addressing Scheme

Atoms and other dependencies are addressed using a convenient URI format that supports aliases, scheme inference, and a special syntax for pinned dependencies. A critical design decision is that aliases are a user interface-only concern; they are fully expanded before being written to the manifest, ensuring that your project is always portable and reproducible.

Manifest and Lockfile

Eka uses a standard atom.toml manifest and atom.lock lockfile to manage dependencies, similar to Cargo or npm.

• atom.toml: A declarative manifest where you define your project's dependencies, including both atoms and pinned legacy dependencies.
• atom.lock: A fully resolved lockfile that captures the exact versions and cryptographic hashes of all dependencies, ensuring that your builds are completely reproducible.

Getting Started

eka publish: Publishing Atoms

The eka publish command implements the in-source publishing strategy for atoms. Before publishing to a new remote for the first time, you must initialize it.

# Initialize the repository on a remote (only needs to be done once per remote).
eka publish --init --remote origin

Then, you can publish atoms from your current HEAD or a specified revision:

# Publish an atom from the current directory
eka publish .

eka add: Adding and Locking Dependencies

The eka add command adds a new dependency to your atom.toml manifest and updates the atom.lock file.

# Add an atom dependency
eka add gh:owner/repo::my-atom@^1

# Add a pinned Git dependency
eka add gh:owner/repo^^some-branch

Development

For a detailed breakdown of the development plan, please see the full ROADMAP.md.

The architecture of Eka is guided by a series of Architectural Decision Records (ADRs). To learn more about the technical details, please refer to the ADRs. The atom's crate docs are also available at docs.eka.rs.