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

# 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)

# On Arch Linux
sudo pacman -S podman

# Configure for rootless
podman system migrate

3. Bootstrap Gentoo Tools

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

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

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

# 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

# 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

# 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

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

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:

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:

nip build firefox --profile=desktop

Hybrid Workflow

Typical Day

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

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

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

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

Mixing Sources

# 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

# 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

# Install Podman
sudo pacman -S podman

# Configure rootless
podman system migrate

# Test
podman run --rm hello-world

Gentoo Build Fails

# 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

# 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

# Default to Arch for speed
nip install <package>

2. Build from Gentoo When Needed

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

3. Use Containers for Testing

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

4. Cache Builds

# 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

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

# 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

# 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)

# 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! 🚀