95 lines
2.5 KiB
Markdown
95 lines
2.5 KiB
Markdown
# 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`.
|