Crate atom

Source
Expand description

§Atom Crate

The atom crate provides the core functionality for working with the Atom Format, a key component of the Ekala Project. This format enables the reproducible packaging of select sources from a larger history, making it ideal for dependency management and software distribution.

§Key Concepts

Atoms are self-contained, reproducible packages that capture a specific version of source code or configuration. They are designed to be:

  • Cheap to transfer over networks
  • Trivial to verify directly from source
  • Completely reproducible across different environments

Lockfiles capture the exact versions and revisions of all dependencies, ensuring that builds are deterministic and can be reproduced reliably.

§Architecture

The crate is organized into several key modules:

  • manifest - Atom manifest format and dependency specification
  • lock - Lockfile format for capturing resolved dependencies
  • id - Atom identification and hashing
  • uri - Atom URI parsing and resolution
  • store - Storage backends for atoms (Git, etc.)
  • publish - Publishing atoms to stores

§Git Storage Example

The current implementation uses Git as the primary storage backend. Atoms are stored as Git refs pointing to orphaned histories:

❯ git ls-remote
From https://github.com/ekala-project/eka
ceebaca6d44c4cda555db3fbf687c0604c4818eb        refs/eka/atoms/ひらがな/0.1.0
a87bff5ae43894a158dadf40938c775cb5b62d4b        refs/eka/meta/ひらがな/0.1.0/manifest
9f17c8c816bd1de6f8aa9c037d1b529212ab2a02        refs/eka/meta/ひらがな/0.1.0/origin
  • The ref under eka/atoms points to the complete atom contents
  • The manifest ref points to a minimal tree containing only the manifest
  • The origin ref points to the original source commit for verification

§Basic Usage

use atom::{Atom, AtomTag, Manifest};
use semver::Version;

// Create a new atom manifest
let manifest = Manifest::new(
    AtomTag::try_from("my-atom").unwrap(),
    Version::new(1, 0, 0),
    Some("A sample atom".to_string()),
);

§Features

  • Type-safe dependency management with compile-time validation
  • Multiple storage backends (Git, with extensibility for others)
  • Cross-platform compatibility with TOML-based serialization
  • Comprehensive error handling with detailed error types
  • Efficient caching for remote operations

Re-exports§

pub use id::AtomId;
pub use id::AtomTag;
pub use id::Compute;
pub use id::Origin;
pub use lock::Lockfile;
pub use lock::ResolutionMode;
pub use manifest::Manifest;
pub use manifest::deps::ManifestWriter;
pub use publish::ATOM_REFS;

Modules§

id
Atom Identification Constructs
lock
Atom Lockfile Format
log
logging stubs for consistent progress and task presentation
manifest
Atom Manifest
publish
Atom Publishing
store
Atom Store Interface
uri
Atom URI Format

Structs§

Atom
Represents the deserialized form of an Atom, directly constructed from the TOML manifest.

Statics§

LOCK_NAME
The filename used for Atom lock files.
MANIFEST_NAME
The filename used for Atom manifest files.