nip/README.md

# 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](docs/getting-started.md) for a complete walkthrough.

### Installation

```bash
# Build from source
./build.sh

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

# Verify installation
nip --version
```

### Basic Usage

```bash
# 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

```bash
$ 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:

```bash
# 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`

```bash
# 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!**

```bash
# 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](docs/arch-linux-guide.md) for complete workflow**

### Gentoo: Access to Nix Packages

**Perfect for Gentoo users who want quick binary installations!**

```bash
# 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](docs/gentoo-nix-guide.md) for complete workflow**

### Debian/Ubuntu: Access to Latest Packages

```bash
# 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

```bash
# 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:

```bash
sudo nip graft nix:hello
```

### Check System Health

```bash
nip doctor
```

### View Logs

```bash
nip logs 50
```

## Development

```bash
# 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](docs/README.md)** - Browse all documentation

### Getting Started
- **[Getting Started Guide](docs/getting-started.md)** - Start here! Complete introduction to NIP
- **[Quick Reference](docs/quick-reference.md)** - Command cheat sheet

### User Guides
- [Dependency Resolution](docs/DEPENDENCY_RESOLUTION.md) - How NIP resolves package dependencies
- [Bootstrap Overview](docs/bootstrap-overview.md) - Understanding the bootstrap system
- [Bootstrap Guide](docs/bootstrap-guide.md) - Installing build tools
- [Bootstrap Detection Flow](docs/bootstrap-detection-flow.md) - How automatic detection works
- [Source Build Guide](docs/source-build-guide.md) - Building from source
- [Arch Linux Guide](docs/arch-linux-guide.md) - Using NIP on Arch Linux
- [Gentoo + Nix Guide](docs/gentoo-nix-guide.md) - Using Nix packages on Gentoo

### Developer Guides
- [Bootstrap API](docs/bootstrap-api.md) - Bootstrap system API
- [Recipe Authoring](recipes/AUTHORING-GUIDE.md) - Creating recipes
- [Build Binaries](recipes/BUILD-BINARIES.md) - 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