2.5 KiB

Raw Blame History

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

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

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

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

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

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

2.5 KiB Raw Blame History