NIP - Universal Package Manager

Version: 1.0.0-mvp
Status: MVP Achieved ✅
Repository: https://git.maiwald.work/Nexus/NexusToolKit

NIP is a universal package manager that grafts packages from Nix, PKGSRC, and Pacman into a unified GoboLinux-style structure with content-addressable storage. Build from source with custom optimizations using Gentoo, Nix, or PKGSRC.

NIP's core value: Bringing together the best of multiple package ecosystems in a clean, unified way. We do things the right way—correctness over speed.

Features

• 🌱 Multi-Source Grafting - Install packages from Nix, PKGSRC, or Pacman
• 🔨 Source Builds - Build from Gentoo/Nix/PKGSRC with custom USE flags
• 🐳 Container Builds - Secure, isolated builds with Podman/Docker
• 🚀 Auto-Bootstrap - Automatically installs build tools when needed
• 📦 GoboLinux Structure - Clean /Programs/<Name>/<Version>/ organization
• 🔗 Unified Symlinks - All packages accessible via /System/Links/
• 🔐 Content-Addressable Storage - Blake2b/Blake3 hashing for integrity
• 🎯 Variant System - Fine-grained feature control with domain flags
• 🐧 Linux & BSD - Works on Arch, Debian, FreeBSD, NetBSD, and more
• ⚡ Simple & Fast - Efficient database, smart caching

Quick Start

New to NIP? Start with the Getting Started Guide for a complete walkthrough.

Installation

# Build from source
./build.sh

# Install (requires root)
sudo ./install.sh

# Verify installation
nip --version

Basic Usage

# Install a package (grafts from available sources)
nip install firefox

# Build from source with custom features
nip build vim +python+ruby --source=gentoo

# Build with optimizations
nip build ffmpeg +vaapi+lto+cpu-native --source=gentoo

# Auto-detect and bootstrap if needed
nip build firefox +wayland --source=gentoo
# → NIP will automatically offer to install Gentoo tools or use containers

# List installed packages
nip list

# Show package info
nip info firefox

# Remove a package
sudo nip remove hello

# Check system status
nip status

# Check system health
nip doctor

Commands

Package Management

Command	Description
nip install <package>	Install a package (auto-detect source)
nip build <pkg> +flags	Build from source with custom features
nip remove <package>	Remove an installed package
nip list	List all installed packages
nip info <package>	Show detailed package information
nip search <query>	Search for packages

Source Building

Command	Description
nip build <pkg> --source=gentoo	Build from Gentoo with USE flags
nip build <pkg> --source=nix	Build from Nix
nip build <pkg> --source=pkgsrc	Build from PKGSRC
nip build <pkg> +wayland+lto	Build with variant flags
nip sources	List available build sources

Bootstrap Management

Command	Description
nip bootstrap list	List installed build tools
nip bootstrap install <tool>	Install build tools (nix/pkgsrc/gentoo)
nip bootstrap remove <tool>	Remove build tools
nip bootstrap info <tool>	Show tool information
nip bootstrap recipes	List available recipes
nip bootstrap update-recipes	Update recipes from repository

System

Command	Description
nip status	Show system status
nip doctor	Check system health
nip config [show|init]	Show or initialize configuration
nip logs [lines]	Show recent log entries

Automatic Bootstrap

NIP automatically detects and installs build tools when needed!

When you try to build from source, NIP will:

1. Check if build tools are installed
2. Detect available container runtimes (Podman/Docker)
3. Offer installation options:
   • Install minimal tools via NIP
   • Use containerized builds (Podman/Docker)
   • Manual installation instructions
   • Try different source

Example: First Build

$ nip build vim +python --source=gentoo

⚠️  Gentoo not found

NIP can help you set up Gentoo builds:

1. 🚀 Install minimal tools via NIP (recommended)
   • Lightweight standalone emerge binary
   • Minimal portage snapshot
   • ~50MB download, ~100MB installed

2. 📦 Use containerized environment
   • Requires Docker/Podman
   • Isolated builds
   • ~200MB download

3. 🔧 Install full Gentoo manually
   • Follow: https://wiki.gentoo.org/wiki/Portage

4. 🔄 Try a different source
   • nip build vim --source=nix

Choose option (1-4) or 'q' to quit: 1

📦 Installing minimal Gentoo tools...
✅ Gentoo tools installed successfully

🔨 Building vim with Gentoo...
✅ Build successful!

Container Builds (Recommended for Arch Linux)

If you have Podman or Docker installed, NIP can build in containers:

# Install Podman (Arch Linux)
sudo pacman -S podman

# NIP automatically uses containers if tools aren't installed
nip build firefox +wayland --source=gentoo

# Or explicitly use containers
nip build firefox --container

Benefits:

• ✅ No need to install build tools
• ✅ Secure, isolated builds
• ✅ Rootless with Podman
• ✅ Clean system

Configuration

NIP uses a simple key-value configuration format:

Global: /etc/nip/nip.conf User: ~/.nip/config

# Initialize user config
nip config init

# View current config
nip config show

Example configuration:

# Directory Configuration
programs-dir = "/Programs"
links-dir = "/System/Links"

# Adapter Priorities (lower = tried first)
nix-priority = 10
pkgsrc-priority = 20
pacman-priority = 30

Directory Structure

/Programs/                    # Package installation
  ├── Firefox/120.0/
  └── Vim/9.0/

/System/Links/                # Unified symlink tree
  ├── Executables/            # Binaries (in PATH)
  ├── Libraries/              # Shared libraries
  ├── Headers/                # Include files
  └── Shared/                 # Share data

/var/nip/                     # NIP data
  ├── cas/                    # Content-addressable storage
  ├── cache/                  # Download cache
  └── db/packages.json        # Package database

Requirements

• Nim compiler (for building from source)
• One or more package sources:
  • Nix (recommended for all platforms)
  • PKGSRC (native on BSD)
  • Pacman (Arch Linux)

Platform Support

• ✅ Linux (Arch, Debian, Ubuntu, etc.)
• ✅ FreeBSD
• ✅ NetBSD
• ✅ DragonflyBSD
• ✅ OpenBSD

Use Cases

Arch Linux: Hybrid Package Management

Perfect for Arch users who want customization!

# Fast: Install standard packages from Arch repos
nip install firefox chromium vscode

# Custom: Build from Gentoo with optimizations
nip build vim +python+ruby+lto --source=gentoo
nip build ffmpeg +vaapi+cpu-native --source=gentoo

# Secure: Use Podman containers (no Gentoo installation needed)
sudo pacman -S podman
nip build obs-studio +pipewire --source=gentoo
# → Automatically builds in container

See Arch Linux Guide for complete workflow

Gentoo: Access to Nix Packages

Perfect for Gentoo users who want quick binary installations!

# System packages from Portage (source, customizable)
emerge --ask firefox

# Quick binary installs from Nix (fast, no compilation)
nip install vscode chromium --source=nix

# Custom optimized builds from Gentoo
nip build ffmpeg +vaapi+lto+cpu-native --source=gentoo

# Best of both worlds!

See Gentoo + Nix Guide for complete workflow

Debian/Ubuntu: Access to Latest Packages

# Get latest packages from Nix
nip install firefox  # Latest version, not Debian's old version

# Build with custom features
nip build vim +python --source=gentoo

BSD: Unified Package Management

# Use native PKGSRC
nip install vim

# Or use Nix for more packages
nip install firefox --source=nix

Troubleshooting

Permission Denied

Most NIP operations require root:

sudo nip graft nix:hello

Check System Health

nip doctor

View Logs

nip logs 50

Development

# Build for development
nim c nip_mvp.nim

# Build for release
./build.sh

# Run tests
nim c -r tests/test_all.nim

License

See LICENSE file in the repository.

Contributing

See CONTRIBUTING.md for guidelines.

Documentation

📚 Complete Documentation Index - Browse all documentation

Getting Started

• Getting Started Guide - Start here! Complete introduction to NIP
• Quick Reference - Command cheat sheet

User Guides

• Dependency Resolution - How NIP resolves package dependencies
• Bootstrap Overview - Understanding the bootstrap system
• Bootstrap Guide - Installing build tools
• Bootstrap Detection Flow - How automatic detection works
• Source Build Guide - Building from source
• Arch Linux Guide - Using NIP on Arch Linux
• Gentoo + Nix Guide - Using Nix packages on Gentoo

Developer Guides

• Bootstrap API - Bootstrap system API
• Recipe Authoring - Creating recipes
• Build Binaries - Building standalone binaries

More Information

• Repository: https://git.maiwald.work/Nexus/NexusToolKit
• Issues: https://git.maiwald.work/Nexus/NexusToolKit/issues
• Wiki: https://git.maiwald.work/Nexus/NexusToolKit/wiki