nip/docs/getting-started.md

Getting Started with NIP

What is NIP?

NIP is a universal package manager that lets you:

• Install packages from multiple sources (Nix, PKGSRC, Pacman)
• Build from source with custom optimizations
• Use a clean GoboLinux-style directory structure
• Build in containers for isolation and security

The best part? NIP handles all the complexity automatically.

Installation

# Clone and build
git clone https://git.maiwald.work/Nexus/NexusToolKit
cd NexusToolKit/nip
./build.sh

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

# Verify
nip --version

Your First Package

Let's install Firefox:

nip install firefox

That's it! NIP automatically:

• Finds the best source (Nix, PKGSRC, or Pacman)
• Downloads and verifies the package
• Installs to /Programs/Firefox/<version>/
• Creates symlinks in /System/Links/

Building from Source

Want to customize a package? Build from source:

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

What Happens Automatically

First time building? NIP detects you need build tools and offers options:

⚠️  Gentoo not found

NIP can help you set up Gentoo builds:

1. 🚀 Install minimal tools via NIP (recommended)
   • ~50MB download, ~100MB installed
   • Isolated in ~/.nip/bootstrap/

2. 📦 Use containerized environment
   • Requires Podman/Docker
   • Completely isolated builds

3. 🔧 Install full Gentoo manually

4. 🔄 Try a different source

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

Choose option 1 for the easiest experience. NIP will:

1. Download a minimal standalone build tool
2. Verify with cryptographic checksums
3. Install to ~/.nip/bootstrap/
4. Start your build

No system pollution. No manual setup. Just works.

Container Builds (Recommended for Arch Linux)

Have Podman or Docker? Even easier:

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

# Build in a container automatically
nip build firefox +wayland --source=gentoo

NIP automatically uses containers when:

• Build tools aren't installed
• You prefer isolated builds
• You explicitly request: nip build --container <package>

Benefits:

• ✅ No build tools needed on your system
• ✅ Secure, isolated builds
• ✅ Rootless with Podman
• ✅ Clean host system

Common Workflows

Arch Linux: Best of Both Worlds

# Fast: Use Arch packages for standard software
nip install firefox chromium vscode

# Custom: Build with optimizations for performance-critical apps
nip build ffmpeg +vaapi+lto+cpu-native --source=gentoo
nip build obs-studio +pipewire --source=gentoo

# Everything coexists perfectly!

See the Arch Linux Guide for the complete workflow.

Debian/Ubuntu: Access Latest Packages

# Get latest Firefox (not Debian's old version)
nip install firefox --source=nix

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

BSD: Unified Management

# Use native PKGSRC
nip install vim

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

Understanding the Bootstrap System

NIP's bootstrap system is intelligent and automatic:

Detection Hierarchy

When you need build tools, NIP checks in order:

1. Native Package Manager - Use system packages if available
2. Existing Bootstrap - Already installed via NIP
3. Recipe-Based Install - Automatic download and setup
4. Container Build - Use Podman/Docker
5. Manual Guide - Clear instructions if all else fails

No User Intervention Needed

In most cases, you just run your build command and NIP handles everything:

# First time
nip build vim +python --source=gentoo
# → NIP offers to install tools
# → Choose option 1
# → Build proceeds automatically

# Second time
nip build emacs +gtk --source=gentoo
# → Tools already installed
# → Build starts immediately

Managing Bootstrap Tools

# List installed tools
nip bootstrap list

# Get info about a tool
nip bootstrap info gentoo

# Remove if you don't need it anymore
nip bootstrap remove gentoo

# Update recipes
nip bootstrap update-recipes

Variant Flags

Customize builds with variant flags:

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

# Optimization flags
nip build ffmpeg +lto+cpu-native+vaapi

# Disable features
nip build vim -gui

# Combine
nip build firefox +wayland-x11+lto

Common flags:

• +python, +ruby, +lua - Language bindings
• +lto - Link-time optimization
• +cpu-native - CPU-specific optimizations
• +wayland, +x11 - Display servers
• +pipewire, +pulseaudio - Audio systems

Package Management

# List installed packages
nip list

# Show package details
nip info firefox

# Search for packages
nip search browser

# Remove a package
sudo nip remove firefox

# Check system health
nip doctor

Configuration

# Initialize user config
nip config init

# View current config
nip config show

Config file: ~/.nip/config

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

# Container runtime preference
container-runtime = "podman"

# Bootstrap auto-install
bootstrap-auto-install = true

Directory Structure

NIP uses a clean, organized structure:

/Programs/                    # Installed packages
  ├── Firefox/120.0/
  │   ├── bin/firefox
  │   ├── lib/
  │   └── share/
  └── Vim/9.0/
      ├── bin/vim
      └── share/

/System/Links/                # Unified symlinks (in PATH)
  ├── Executables/
  │   ├── firefox -> /Programs/Firefox/120.0/bin/firefox
  │   └── vim -> /Programs/Vim/9.0/bin/vim
  ├── Libraries/
  └── Headers/

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

Troubleshooting

Build Tools Not Found

# Check what's installed
nip bootstrap list

# Install manually
nip bootstrap install gentoo

# Or use containers
nip build --container <package>

Permission Denied

Most operations need root:

sudo nip install firefox

Check System Health

nip doctor

View Logs

nip logs 50

Next Steps

Learn More

• Bootstrap Guide - Deep dive into build tool management
• Bootstrap Detection Flow - How automatic detection works
• Source Build Guide - Advanced source building
• Arch Linux Guide - Arch-specific workflows
• Bootstrap API - Developer reference

Advanced Topics

• Container Builds - Isolated, reproducible builds
• Binary Caching - Speed up repeated builds
• Custom Recipes - Create your own bootstrap recipes
• Remote Repositories - Share packages with your team

Quick Reference

Essential Commands

# Package Management
nip install <package>              # Install from any source
nip build <pkg> +flags             # Build from source
nip remove <package>               # Remove package
nip list                           # List installed
nip info <package>                 # Show details

# Bootstrap Management
nip bootstrap list                 # List build tools
nip bootstrap install <tool>       # Install tool
nip bootstrap info <tool>          # Tool details

# System
nip status                         # System status
nip doctor                         # Health check
nip config show                    # View config

Common Build Examples

# Basic build
nip build vim --source=gentoo

# With features
nip build vim +python+ruby

# With optimizations
nip build ffmpeg +lto+cpu-native

# In container
nip build firefox --container

# Specific source
nip build emacs --source=nix

Philosophy

NIP is designed around three principles:

1. Automatic - Handle complexity behind the scenes
2. Flexible - Support multiple sources and workflows
3. Clean - Organized structure, no system pollution

You shouldn't need to read documentation to use NIP. But when you want to dig deeper, it's all here.

Getting Help

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

Summary

NIP makes package management simple:

1. Install packages: nip install firefox
2. Build from source: nip build vim +python
3. Let NIP handle the rest: Automatic tool installation, container builds, everything

Start with the basics, explore advanced features when you need them. Welcome to NIP!