nip/docs/quick-reference.md

# NIP Quick Reference

## Essential Commands

### Package Management

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

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

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

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

```bash
# Simple build
nip build vim --source=gentoo

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

# Specific source
nip build firefox --source=nix
```

### Optimized Builds

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

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

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

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

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

### Managing Tools

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

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

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

### Permission Denied

```bash
sudo nip install <package>     # Most operations need root
```

### Build Failures

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

### Container Issues

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

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

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

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

### Gentoo

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

### BSD

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

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

## Common Workflows

### Install Standard Package

```bash
nip install firefox
```

### Build with Custom Features

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

### Build with Optimizations

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

### Build in Container

```bash
nip build firefox +wayland --container
```

### Check Installation

```bash
nip list
nip info firefox
```

### Remove Package

```bash
sudo nip remove firefox
```

## Getting Help

### Documentation

- [Getting Started](getting-started.md) - Complete introduction
- [Bootstrap Overview](bootstrap-overview.md) - Bootstrap system
- [Source Build Guide](source-build-guide.md) - Building from source
- [Complete Docs](README.md) - All documentation

### Commands

```bash
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](getting-started.md)

## 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](README.md)

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