# NimPak Developer Guide

This guide is for developers who want to create packages, build tools, or contribute to NimPak.

## 🛠️ Creating Packages

NimPak uses a `manifest.kdl` file to define packages. KDL (Key-Document Language) is used for its readability and structure.

### Manifest Schema

```kdl
package {
    name "my-app"
    version "1.0.0"
    description "A sample application"
    license "MIT"
    
    architecture "x86_64"
    os "linux"
    
    dependencies {
        pkg "glibc" version=">=2.35"
        pkg "openssl" version="3.0"
    }
    
    # For NIP applications
    application {
        entry-point "bin/my-app"
        icon "share/icons/my-app.png"
        desktop-file "share/applications/my-app.desktop"
    }
}
```

### Building a Package

1. Create a directory with your files and `manifest.kdl`.
2. Use `nip pack` to create the package archive.

```bash
nip pack ./my-app-source my-app-1.0.0.nip
```

## 🏗️ Build System

NimPak integrates with the **Graft** build system.

- **Source Builds:** Can build from source using recipes.
- **Reproducibility:** Builds run in isolated containers.
- **Caching:** Binary artifacts are cached in the CAS.

## 🧠 CAS Internals

The Content-Addressable Storage (CAS) is the heart of NimPak.

### Object Storage
- **Location:** `~/.local/share/nexus/cas/objects`
- **Hashing:** XXH3 (64-bit/128-bit) for speed, BLAKE3 for security.
- **Structure:** Objects are stored in a 2-level directory structure based on hash prefix (e.g., `ab/cdef123...`).

### References
- **Location:** `~/.local/share/nexus/cas/refs`
- **Purpose:** Tracks which packages/apps are using which CAS objects.
- **GC:** Garbage collection removes objects with zero references.

## 📚 API Reference

NimPak provides a Nim API for integration.

### Core Modules

- `nimpak/cas`: CAS management (store, retrieve, pin).
- `nimpak/manifest`: Manifest parsing and validation.
- `nimpak/package`: Package installation and lifecycle.
- `nimpak/container`: Container management (Nexter).

### Example: Storing a File

```nim
import nimpak/cas

let cas = initCasManager("/path/to/cas")
let result = cas.storeFile("/path/to/file.txt")

if result.isOk:
  echo "Stored with hash: ", result.get().hash
```

## 📦 Best Practices

1. **Granularity:** Split large applications into smaller components if possible to maximize deduplication.
2. **Versioning:** Use Semantic Versioning (SemVer).
3. **Dependencies:** Explicitly declare all dependencies in the manifest.
4. **Security:** Sign your packages using `nip sign`.