nip/docs/quick-reference.md

NIP Quick Reference

Essential Commands

Package Management

nip install <package>              # Install from any source
nip build <pkg> +flags             # Build from source with features
nip remove <package>               # Remove package
nip list                           # List installed packages
nip info <package>                 # Show package details
nip search <query>                 # Search for packages

Source Building

nip build <pkg> --source=gentoo    # Build from Gentoo
nip build <pkg> --source=nix       # Build from Nix
nip build <pkg> --source=pkgsrc    # Build from PKGSRC
nip build <pkg> +python+ruby       # Build with features
nip build <pkg> --container        # Build in container

Bootstrap Management

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

System

nip status                         # Show system status
nip doctor                         # Check system health
nip config show                    # View configuration
nip config init                    # Initialize user config
nip logs [lines]                   # Show recent logs

Common Variant Flags

Language Support

• +python / -python - Python bindings
• +ruby / -ruby - Ruby bindings
• +lua / -lua - Lua support
• +perl / -perl - Perl support

Display Servers

• +wayland / -wayland - Wayland support
• +x11 / -x11 - X11 support
• +gtk / -gtk - GTK toolkit
• +qt / -qt - Qt toolkit

Optimizations

• +lto - Link-time optimization
• +cpu-native - CPU-specific optimizations
• +pgo - Profile-guided optimization

Audio/Video

• +pipewire / -pipewire - PipeWire support
• +pulseaudio / -pulseaudio - PulseAudio support
• +vaapi - VA-API hardware acceleration
• +vdpau - VDPAU hardware acceleration

Features

• +ssl / -ssl - SSL/TLS support
• +ipv6 / -ipv6 - IPv6 support
• +systemd / -systemd - systemd integration
• +doc / -doc - Documentation

Build Examples

Basic Builds

# Simple build
nip build vim --source=gentoo

# With features
nip build vim +python+ruby+lua

# Specific source
nip build firefox --source=nix

Optimized Builds

# Maximum performance
nip build ffmpeg +lto+cpu-native+vaapi

# Custom features
nip build obs-studio +pipewire+vaapi+qt

# Minimal build
nip build vim -gui-perl-ruby

Container Builds

# Auto-detect container
nip build firefox --container

# Force container
nip build vim --container --source=gentoo

# With features in container
nip build emacs +gtk --container

Bootstrap Workflows

First Time Setup

# Option 1: Let NIP handle it automatically
nip build vim +python --source=gentoo
# → Choose option 1 when prompted

# Option 2: Install manually first
nip bootstrap install gentoo
nip build vim +python --source=gentoo

Container Setup (Arch Linux)

# Install Podman
sudo pacman -S podman

# Build in container (no tools needed)
nip build firefox +wayland --source=gentoo

Managing Tools

# Check what's installed
nip bootstrap list

# Get details
nip bootstrap info gentoo

# Remove if not needed
nip bootstrap remove gentoo

# Update recipes
nip bootstrap update-recipes

Configuration

User Config (~/.nip/config)

# Default source for builds
default-source = "gentoo"

# Bootstrap preferences
bootstrap-auto-install = true
bootstrap-preferred-method = "recipe"

# Container preferences
container-runtime = "podman"

# Directories
programs-dir = "/Programs"
links-dir = "/System/Links"

Command-Line Overrides

# Force specific bootstrap
nip build vim --bootstrap=nix

# Skip bootstrap
nip build vim --no-bootstrap

# Force re-bootstrap
nip build vim --force-bootstrap

# Use specific container runtime
nip build vim --container-runtime=podman

Directory Structure

/Programs/                    # Installed packages
  └── <Name>/<Version>/       # Package files

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

~/.nip/                       # User data
  ├── bootstrap/              # Build tools
  │   ├── gentoo/
  │   ├── nix/
  │   └── pkgsrc/
  ├── cache/                  # Download cache
  └── config                  # User config

/var/nip/                     # System data
  ├── cas/                    # Content-addressable storage
  └── db/                     # Package database

Troubleshooting

Build Tools Not Found

nip bootstrap list             # Check installed
nip bootstrap install gentoo   # Install manually
nip build --container <pkg>    # Use container instead

Permission Denied

sudo nip install <package>     # Most operations need root

Build Failures

nip doctor                     # Check system health
nip logs 50                    # View recent logs
nip bootstrap info gentoo      # Verify tool installation

Container Issues

# Check container runtime
podman --version
docker --version

# Install Podman
sudo pacman -S podman          # Arch
sudo apt install podman        # Debian/Ubuntu

Platform-Specific Tips

Arch Linux

# Fast: Use Arch packages
nip install firefox chromium

# Custom: Build with optimizations
nip build vim +python+lto --source=gentoo

# Clean: Use containers
sudo pacman -S podman
nip build --container <package>

Debian/Ubuntu

# Get latest packages
nip install firefox --source=nix

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

Gentoo

# Use native Portage (auto-detected)
nip build vim +python

BSD

# Use native PKGSRC
nip install vim --source=pkgsrc

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

Common Workflows

Install Standard Package

nip install firefox

Build with Custom Features

nip build vim +python+ruby+lua --source=gentoo

Build with Optimizations

nip build ffmpeg +lto+cpu-native+vaapi --source=gentoo

Build in Container

nip build firefox +wayland --container

Check Installation

nip list
nip info firefox

Remove Package

sudo nip remove firefox

Getting Help

Documentation

• Getting Started - Complete introduction
• Bootstrap Overview - Bootstrap system
• Source Build Guide - Building from source
• Complete Docs - All documentation

Commands

nip --help                     # General help
nip build --help               # Build command help
nip bootstrap --help           # Bootstrap help

Support

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

Quick Start Checklist

• Install NIP: ./build.sh && sudo ./install.sh
• Verify: nip --version
• Install a package: nip install firefox
• Try a build: nip build vim +python --source=gentoo
• Check status: nip status
• Read docs: Getting Started Guide

Summary

Install packages: nip install <package> Build from source: nip build <pkg> +flags Manage tools: nip bootstrap list|install|remove Get help: nip --help or read docs

That's it! NIP handles the complexity, you focus on using your software.