nip/docs/bootstrap-overview.md

# Bootstrap System Overview

## What is the Bootstrap System?

The NIP bootstrap system automatically manages build tools (Nix, PKGSRC, Gentoo) so you can build packages from source without manual setup.

**Key Feature:** When you run `nip build <package>`, NIP automatically detects if you need build tools and offers to install them for you.

## Quick Example

```bash
# First time building from Gentoo
$ nip build vim +python --source=gentoo

⚠️  Gentoo not found

NIP can help you set up Gentoo builds:

1. 🚀 Install minimal tools via NIP (recommended)
2. 📦 Use containerized environment
3. 🔧 Install full Gentoo manually
4. 🔄 Try a different source

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

📦 Installing minimal Gentoo tools...
✅ Gentoo tools installed successfully
🔨 Building vim...
```

**That's it!** No manual configuration, no system pollution, just automatic setup.

## How It Works

### Automatic Detection

When you build from source, NIP automatically:

1. **Checks** if build tools are installed
2. **Detects** your platform and available options
3. **Offers** the best installation method
4. **Installs** tools if you choose
5. **Proceeds** with your build

See [Bootstrap Detection Flow](bootstrap-detection-flow.md) for complete details.

### Installation Methods

NIP supports multiple installation methods, automatically choosing the best one:

#### 1. Recipe-Based Installation (Recommended)

- Downloads minimal standalone build tools
- Installs to `~/.nip/bootstrap/`
- ~50-100MB per tool
- No system modifications
- Cryptographically verified

**Best for:** Most users, especially on Arch Linux

#### 2. Container Builds

- Uses Podman or Docker
- Completely isolated builds
- No build tools on host system
- Rootless with Podman

**Best for:** Users who want maximum isolation

#### 3. Native Package Manager

- Uses system package manager (pacman, apt, etc.)
- Official packages with updates
- System-wide installation

**Best for:** Users who prefer system packages

#### 4. Manual Installation

- Full control over installation
- Follow official documentation
- Custom configurations

**Best for:** Advanced users with specific needs

## Supported Build Tools

### Gentoo (Portage)

**Use for:** Maximum customization with USE flags

```bash
nip build vim +python+ruby --source=gentoo
nip build ffmpeg +vaapi+lto --source=gentoo
```

**Installation:**
- Minimal: Standalone emerge + portage snapshot (~100MB)
- Container: Gentoo stage3 image (~200MB)
- Full: Complete Gentoo installation

### Nix

**Use for:** Reproducible builds, large package selection

```bash
nip build firefox --source=nix
nip build emacs +gtk --source=nix
```

**Installation:**
- Minimal: Standalone nix-build (~50MB)
- Full: Complete Nix installation

### PKGSRC

**Use for:** BSD compatibility, portable builds

```bash
nip build vim --source=pkgsrc
nip build nginx --source=pkgsrc
```

**Installation:**
- Minimal: Standalone bmake + pkgsrc snapshot (~80MB)
- Full: Complete PKGSRC installation

## Managing Bootstrap Tools

### List Installed Tools

```bash
nip bootstrap list
```

Output:
```
Installed Bootstrap Tools:

✓ Gentoo (Portage)
  Location: /home/user/.nip/bootstrap/gentoo
  Version: 3.0.54
  Status: Ready

✓ Nix
  Location: /home/user/.nip/bootstrap/nix
  Version: 2.18.1
  Status: Ready
```

### Install a Tool

```bash
# Install specific tool
nip bootstrap install gentoo
nip bootstrap install nix
nip bootstrap install pkgsrc

# Install with container preference
nip bootstrap install gentoo --container
```

### Get Tool Information

```bash
nip bootstrap info gentoo
```

Output:
```
Gentoo (Portage) Bootstrap

Status: Installed
Location: /home/user/.nip/bootstrap/gentoo
Version: 3.0.54
Installed: 2024-01-15

Capabilities:
  ✓ Source builds with USE flags
  ✓ Custom CFLAGS/LDFLAGS
  ✓ Package variants

Disk Usage: 98.5 MB

Commands:
  emerge    - Package manager
  ebuild    - Build packages
  equery    - Query packages
```

### Remove a Tool

```bash
nip bootstrap remove gentoo
```

### Update Recipes

```bash
# Update recipe repository
nip bootstrap update-recipes

# List available recipes
nip bootstrap recipes
```

## Configuration

### User Configuration

Edit `~/.nip/config`:

```
# Bootstrap preferences
bootstrap-auto-install = true
bootstrap-preferred-method = "recipe"  # recipe, container, system, manual

# Container preferences
container-runtime = "podman"  # podman, docker, containerd

# Installation directory
bootstrap-install-dir = "~/.nip/bootstrap"
```

### Command-Line Overrides

```bash
# Force specific bootstrap method
nip build vim --bootstrap=nix
nip build vim --bootstrap=container

# Skip bootstrap (use system tools)
nip build vim --no-bootstrap

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

## Platform-Specific Recommendations

### Arch Linux

**Recommended:** Recipe-based or container builds

```bash
# Option 1: Install minimal tools
nip bootstrap install gentoo

# Option 2: Use containers (requires Podman)
sudo pacman -S podman
nip build --container <package>
```

**Why:** Keeps Arch system clean, no conflicts with pacman

See [Arch Linux Guide](arch-linux-guide.md) for complete workflow.

### Debian/Ubuntu

**Recommended:** Recipe-based installation

```bash
nip bootstrap install nix
nip bootstrap install gentoo
```

**Why:** Access to latest packages and custom builds

### Gentoo

**Recommended:** Use native Portage

```bash
# NIP automatically detects system Portage
nip build vim +python
```

**Why:** Already have the tools!

### NixOS

**Recommended:** Use native Nix

```bash
# NIP automatically detects system Nix
nip build firefox
```

**Why:** Already have the tools!

### BSD (FreeBSD, NetBSD, etc.)

**Recommended:** PKGSRC (native) or Nix

```bash
nip bootstrap install pkgsrc
nip bootstrap install nix
```

**Why:** PKGSRC is native to BSD, Nix has good BSD support

## Troubleshooting

### Build Tools Not Detected

```bash
# Check what's installed
nip bootstrap list

# Verify installation
nip bootstrap info gentoo

# Reinstall if needed
nip bootstrap remove gentoo
nip bootstrap install gentoo
```

### Download Failures

```bash
# Update recipes
nip bootstrap update-recipes

# Try different mirror (future feature)
nip bootstrap install gentoo --mirror=alternate

# Use container instead
nip build --container <package>
```

### Verification Failures

```bash
# Check logs
nip logs 50

# Remove and reinstall
nip bootstrap remove gentoo
nip bootstrap install gentoo

# Report issue if persistent
```

### Container Runtime Not Found

```bash
# Install Podman (recommended)
# Arch Linux:
sudo pacman -S podman

# Debian/Ubuntu:
sudo apt install podman

# Or Docker:
sudo apt install docker.io
```

## Security

### Checksum Verification

All downloaded binaries are verified with Blake2b-512 checksums:

- Checksums stored in recipes
- Automatic verification before installation
- Rejection of mismatched files

### Isolation

- Bootstrap tools installed in user directory (`~/.nip/bootstrap/`)
- No system-wide modifications
- Container builds provide additional isolation

### Updates

```bash
# Update recipes (includes new checksums)
nip bootstrap update-recipes

# Reinstall tools with latest versions
nip bootstrap remove gentoo
nip bootstrap install gentoo
```

## Advanced Topics

### Creating Custom Recipes

See [Recipe Authoring Guide](../recipes/AUTHORING-GUIDE.md)

### Building Standalone Binaries

See [Build Binaries Guide](../recipes/BUILD-BINARIES.md)

### API Reference

See [Bootstrap API Documentation](bootstrap-api.md)

## Documentation Index

### User Documentation

1. **[Getting Started](getting-started.md)** - Complete introduction to NIP
2. **[Bootstrap Overview](bootstrap-overview.md)** - This document
3. **[Bootstrap Guide](bootstrap-guide.md)** - Detailed bootstrap usage
4. **[Bootstrap Detection Flow](bootstrap-detection-flow.md)** - How detection works
5. **[Source Build Guide](source-build-guide.md)** - Building from source
6. **[Arch Linux Guide](arch-linux-guide.md)** - Arch-specific workflows

### Developer Documentation

1. **[Bootstrap API](bootstrap-api.md)** - API reference
2. **[Recipe Authoring](../recipes/AUTHORING-GUIDE.md)** - Creating recipes
3. **[Build Binaries](../recipes/BUILD-BINARIES.md)** - Building standalone tools

## Quick Reference

### Common Commands

```bash
# List tools
nip bootstrap list

# Install tool
nip bootstrap install gentoo

# Get info
nip bootstrap info gentoo

# Remove tool
nip bootstrap remove gentoo

# Update recipes
nip bootstrap update-recipes

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

# Build in container
nip build vim --container
```

### Installation Methods

| Method | Size | Isolation | Speed | Best For |
|--------|------|-----------|-------|----------|
| Recipe | ~50-100MB | User dir | Fast | Most users |
| Container | ~200MB | Complete | Medium | Arch Linux |
| System | Varies | System-wide | Fast | System integration |
| Manual | Varies | Custom | Varies | Advanced users |

## Summary

The NIP bootstrap system makes source building accessible:

1. **Automatic** - Detects and offers installation
2. **Flexible** - Multiple installation methods
3. **Clean** - No system pollution
4. **Secure** - Cryptographic verification
5. **Simple** - Just run your build command

You don't need to understand the bootstrap system to use it. But when you want more control, all the options are here.

**Next Steps:**
- New users: Read [Getting Started Guide](getting-started.md)
- Want details: Read [Bootstrap Guide](bootstrap-guide.md)
- Curious how it works: Read [Detection Flow](bootstrap-detection-flow.md)
- Building packages: Read [Source Build Guide](source-build-guide.md)