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

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

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

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

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

```bash
# 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](arch-linux-guide.md) for the complete workflow.

### Debian/Ubuntu: Access Latest Packages

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

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

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

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

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

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

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

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

```bash
sudo nip install firefox
```

### Check System Health

```bash
nip doctor
```

### View Logs

```bash
nip logs 50
```

## Next Steps

### Learn More

- **[Bootstrap Guide](bootstrap-guide.md)** - Deep dive into build tool management
- **[Bootstrap Detection Flow](bootstrap-detection-flow.md)** - How automatic detection works
- **[Source Build Guide](source-build-guide.md)** - Advanced source building
- **[Arch Linux Guide](arch-linux-guide.md)** - Arch-specific workflows
- **[Bootstrap API](bootstrap-api.md)** - 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

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

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