nip/docs/arch-linux-guide.md

# NIP on Arch Linux - Complete Guide

## Overview

This guide shows how to use NIP as your primary package manager on Arch Linux, combining the best of both worlds:

- **Graft Arch packages** - Use existing binary packages from Arch repos
- **Build from Gentoo** - Compile with custom USE flags for optimization
- **Podman containers** - Secure, rootless containerized builds

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    NIP Package Manager                       │
└────────────────┬────────────────────────────────────────────┘
                 │
        ┌────────┼────────┬──────────────┐
        │        │        │              │
        ▼        ▼        ▼              ▼
    ┌──────┐ ┌──────┐ ┌──────┐    ┌──────────┐
    │ Arch │ │ Nix  │ │Gentoo│    │ Podman   │
    │Graft │ │Build │ │Build │    │Container │
    └──────┘ └──────┘ └──────┘    └──────────┘
```

## Quick Start

### 1. Install NIP

```bash
# Clone repository
git clone https://git.maiwald.work/Nexus/NexusToolKit.git
cd NexusToolKit/nip

# Build NIP
nim c src/nip.nim

# Install (optional)
sudo cp src/nip /usr/local/bin/
```

### 2. Install Podman (Recommended)

```bash
# On Arch Linux
sudo pacman -S podman

# Configure for rootless
podman system migrate
```

### 3. Bootstrap Gentoo Tools

```bash
# Option 1: Install minimal Gentoo tools
nip bootstrap install gentoo

# Option 2: Use Podman container (fallback)
# NIP will automatically use Podman if tools aren't available
```

## Usage Patterns

### Pattern 1: Graft Arch Packages (Fast)

Use this for standard packages where you don't need customization:

```bash
# Install Firefox from Arch repos
nip install firefox

# This grafts the Arch package into NIP's CAS
# Fast, uses existing binaries
```

**When to use:**
- Standard desktop applications
- System utilities
- Development tools
- Anything where defaults are fine

### Pattern 2: Build from Gentoo (Customized)

Use this when you need specific optimizations or features:

```bash
# Build Firefox with Wayland support
nip build firefox +wayland+lto --source=gentoo

# Build with custom USE flags
nip build vim +python+ruby-lua --source=gentoo

# Build optimized for your CPU
nip build ffmpeg +cpu-native+lto --source=gentoo
```

**When to use:**
- Need specific features (Wayland, PipeWire, etc.)
- Want CPU-specific optimizations
- Need to disable unwanted features
- Building for performance

### Pattern 3: Container Builds (Secure Fallback)

If Gentoo tools aren't installed, NIP automatically uses Podman:

```bash
# NIP detects no Gentoo tools, uses Podman automatically
nip build firefox +wayland --source=gentoo

# Output:
# ⚠️  Gentoo not found
# 🐳 Using Podman container for build
# 📦 Pulling gentoo/stage3:latest...
# 🔨 Building firefox with USE="wayland"...
```

**Advantages:**
- No need to install Gentoo tools
- Isolated builds (security)
- Reproducible
- Clean system

## Practical Examples

### Example 1: Daily Driver Setup

```bash
# Install common apps from Arch (fast)
nip install \
    firefox \
    chromium \
    vscode \
    discord \
    spotify

# Build optimized tools from Gentoo
nip build vim +python+ruby --source=gentoo
nip build tmux +cpu-native --source=gentoo
nip build ffmpeg +vaapi+vdpau+cpu-native --source=gentoo
```

### Example 2: Development Environment

```bash
# Graft standard tools
nip install \
    git \
    docker \
    kubectl \
    terraform

# Build optimized compilers
nip build gcc +lto+pgo --source=gentoo
nip build rust +lto --source=gentoo
```

### Example 3: Multimedia Workstation

```bash
# Graft standard apps
nip install \
    gimp \
    inkscape \
    blender

# Build optimized multimedia stack
nip build ffmpeg +vaapi+nvenc+cpu-native+lto --source=gentoo
nip build mpv +wayland+pipewire --source=gentoo
nip build obs-studio +pipewire+vaapi --source=gentoo
```

## Configuration

### Configure NIP for Arch

Create `~/.config/nip/config`:

```kdl
config {
    // Prefer Arch for standard packages
    default-source "arch"

    // Use Gentoo for builds
    build-source "gentoo"

    // Enable Podman fallback
    container-runtime "podman"
    container-fallback true

    // Arch-specific settings
    arch {
        mirror "https://mirror.archlinux.org"
        use-pacman-cache true
    }

    // Gentoo build settings
    gentoo {
        use-flags "+wayland +pipewire +lto"
        makeopts "-j$(nproc)"
        cpu-flags "native"
    }

    // Container settings
    container {
        runtime "podman"
        image "gentoo/stage3:latest"
        cache-builds true
    }
}
```

### Variant Profiles

Create custom profiles for common configurations:

`~/.config/nip/profiles/desktop.kdl`:
```kdl
profile "desktop" {
    description "Desktop workstation profile"

    domains {
        graphics {
            wayland true
            x11 false
        }

        audio {
            pipewire true
            pulseaudio false
        }

        optimization {
            lto true
            pgo false
            cpu-native true
        }
    }
}
```

Use with:
```bash
nip build firefox --profile=desktop
```

## Hybrid Workflow

### Typical Day

```bash
# Morning: Install new app (use Arch)
nip install slack

# Afternoon: Need custom build (use Gentoo)
nip build obs-studio +pipewire+vaapi --source=gentoo

# Evening: Update everything
nip update  # Updates both Arch and built packages
```

### When to Use What

| Scenario | Use | Command |
|----------|-----|---------|
| Standard app | Arch graft | `nip install <pkg>` |
| Need feature | Gentoo build | `nip build <pkg> +feature --source=gentoo` |
| Optimization | Gentoo build | `nip build <pkg> +lto+cpu-native --source=gentoo` |
| No Gentoo tools | Container | Automatic fallback to Podman |
| Testing | Container | build <pkg> --container` |

## Container Strategy

### Why Podman?

1. **Rootless** - Runs without root privileges
2. **Secure** - Better isolation than Docker
3. **Compatible** - Drop-in Docker replacement
4. **No daemon** - Simpler architecture

### Container Build Flow

```
1. NIP detects no Gentoo tools
   ↓
2. Check for Podman/Docker
   ↓
3. Pull gentoo/stage3 image
   ↓
4. Mount source directory
   ↓
5. Run emerge in container
   ↓
6. Extract built package
   ↓
7. Install to NIP CAS
```

### Container Images

NIP supports multiple container images:

```bash
# Gentoo (default)
nip build vim --source=gentoo --container

# Gentoo with specific profile
nip build vim --source=gentoo --container-image=gentoo/stage3:desktop

# Custom image
nip build vim --source=gentoo --container-image=myregistry/gentoo:custom
```

## Advanced Usage

### Building Gentoo Tools Natively

If you want to build Gentoo tools natively on Arch:

```bash
# Install dependencies
sudo pacman -S python python-setuptools

# Bootstrap Gentoo Portage
nip bootstrap install gentoo

# This installs:
# - Minimal Portage
# - emerge wrapper
# - Portage snapshot
# Location: ~/.local/share/nip/build-tools/gentoo/
```

### Using Arch Package Cache

NIP can use Arch's package cache to avoid re-downloading:

```bash
# Configure in ~/.config/nip/config
arch {
    use-pacman-cache true
    pacman-cache-dir "/var/cache/pacman/pkg"
}
```

### Mixing Sources

```bash
# Install base from Arch
nip install firefox

# Build plugin from Gentoo
nip build firefox-wayland-plugin --source=gentoo

# Both coexist in NIP's CAS
```

## Performance Comparison

### Graft (Arch) vs Build (Gentoo)

| Metric | Arch Graft | Gentoo Build | Gentoo Container |
|--------|------------|--------------|------------------|
| Speed | ~5 seconds | ~30 minutes | ~35 minutes |
| Disk | Binary size | Binary size | Binary + image |
| CPU | Minimal | High | High |
| Customization | None | Full | Full |
| Security | Arch trust | Build trust | Container isolation |

### When Speed Matters

```bash
# Fast: Graft from Arch
nip install firefox  # 5 seconds

# Slow but optimized: Build from Gentoo
nip build firefox +lto+cpu-native --source=gentoo  # 30 minutes

# Compromise: Use binary cache
nip build firefox --source=gentoo --use-cache  # 5 seconds if cached
```

## Troubleshooting

### Podman Not Found

```bash
# Install Podman
sudo pacman -S podman

# Configure rootless
podman system migrate

# Test
podman run --rm hello-world
```

### Gentoo Build Fails

```bash
# Check container logs
nip build vim --source=gentoo --verbose

# Try with fresh container
nip build vim --source=gentoo --no-cache

# Use specific Portage snapshot
nip build vim --source=gentoo --portage-snapshot=20251115
```

### Arch Package Not Found

```bash
# Update package database
nip update

# Search for package
nip search vim

# Try different source
nip build vim --source=gentoo
```

## Best Practices

### 1. Use Arch for Most Things

```bash
# Default to Arch for speed
nip install <package>
```

### 2. Build from Gentoo When Needed

```bash
# Only build when you need customization
nip build <package> +feature --source=gentoo
```

### 3. Use Containers for Testing

```bash
# Test builds in containers first
nip build <package> --source=gentoo --container --dry-run
```

### 4. Cache Builds

```bash
# Enable binary cache
nip config set cache.enabled true

# Share cache with team
nip config set cache.server "https://cache.example.com"
```

### 5. Profile Your System

```bash
# Create system profile
nip profile create mysystem

# Use for all builds
nip build <package> --profile=mysystem
```

## Integration with Arch

### Coexistence with Pacman

NIP and Pacman can coexist:

```bash
# Pacman for system packages
sudo pacman -S linux linux-firmware

# NIP for user packages
nip install firefox vim tmux

# No conflicts - NIP uses its own CAS
```

### Migration from Pacman

```bash
# List Pacman packages
pacman -Qq > packages.txt

# Install with NIP
cat packages.txt | xargs nip install

# Optional: Remove Pacman packages
# (Keep system essentials!)
```

## Real-World Workflow

### My Daily Setup (Example)

```bash
# System packages (Pacman)
sudo pacman -S linux base base-devel

# Desktop environment (NIP + Arch)
nip install \
    sway \
    waybar \
    alacritty \
    rofi

# Optimized tools (NIP + Gentoo)
nip build vim +python+ruby+lto --source=gentoo
nip build tmux +cpu-native --source=gentoo
nip build ffmpeg +vaapi+cpu-native+lto --source=gentoo

# Development tools (NIP + Arch)
nip install \
    git \
    docker \
    vscode

# Result: Fast installs + optimized tools where it matters
```

## Future Enhancements

### Planned Features

1. **Automatic source selection** - NIP chooses best source
2. **Binary cache** - Share built packages
3. **Build farm** - Distributed builds
4. **Profile templates** - Pre-made configurations
5. **Arch integration** - Better Pacman interop

## Support

For help with NIP on Arch Linux:
- GitHub Issues: https://git.maiwald.work/Nexus/NexusToolKit/issues
- Documentation: https://git.maiwald.work/Nexus/NexusToolKit/wiki
- Community: #nexusos on IRC

## Conclusion

NIP on Arch Linux gives you the best of both worlds:
- **Speed** of binary packages (Arch)
- **Flexibility** of source builds (Gentoo)
- **Security** of containerized builds (Podman)

Start with Arch grafts for speed, build from Gentoo when you need customization, and use containers as a secure fallback. This hybrid approach is practical, efficient, and powerful.

**Welcome to the future of package management!** 🚀