# NIP Bootstrap Guide

## Overview

NIP can automatically install minimal build environments (Nix, PKGSRC, Gentoo) without requiring manual system setup. This guide explains how to use the bootstrap system.

## Quick Start

### Check Available Tools

```bash
# List installed build tools
nip bootstrap list

# List available recipes
nip bootstrap recipes

# Show detailed information about a tool
nip bootstrap info nix
```

### Install a Build Tool

```bash
# Install Nix (recommended for most users)
nip bootstrap install nix

# Install PKGSRC (portable, works on many systems)
nip bootstrap install pkgsrc

# Install Gentoo Portage (for Gentoo-style builds)
nip bootstrap install gentoo
```

### Build from Source

Once a build tool is installed, you can build packages from source:

```bash
# Build Firefox from Nix
nip build firefox --source=nix

# Build with variant flags
nip build firefox +wayland+lto --source=nix

# Auto-detect best source
nip build vim
```

## Commands

### `nip bootstrap list`

List all installed build tools and their status.

**Example:**
```bash
$ nip bootstrap list

📦 Installed Build Tools:

  ✅ nix
     Location: /home/user/.local/share/nip/build-tools/nix

  System tools:
  ✅ gentoo (system)
```

### `nip bootstrap install <tool>`

Install a specific build tool. Available tools: `nix`, `pkgsrc`, `gentoo`.

**Example:**
```bash
$ nip bootstrap install nix

⚠️  nix not found

NIP can help you set up nix builds:

1. 🚀 Install minimal tools via NIP (recommended)
   • Minimal Nix installation
   • Single-user mode
   • ~100MB download, ~200MB installed

2. 📦 Use containerized environment
   • Requires Docker/Podman (not detected)
   • Install Docker or Podman first

3. 🔧 Install full nix manually
   • Follow: https://nixos.org/download.html

4. 🔄 Try a different source
   • nip build <package> --source=pkgsrc
   • nip build <package> --source=gentoo

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

📦 Installing minimal Nix...
   📥 Fetching recipes...
   📋 Recipe: minimal-nix v2.18.1
   ⬇️  Downloading components...
   📦 Extracting archives...
   🔧 Installing binaries...
   ⚙️  Running installation script...
   ✓ Verifying installation...
✅ Nix tools installed successfully
```

### `nip bootstrap remove <tool>`

Remove an installed build tool.

**Example:**
```bash
$ nip bootstrap remove gentoo

🗑️  Removing gentoo from /home/user/.local/share/nip/build-tools/gentoo...
✅ gentoo removed successfully
```

### `nip bootstrap info <tool>`

Show detailed information about a build tool, including its recipe, dependencies, and installation status.

**Example:**
```bash
$ nip bootstrap info nix

📦 minimal-nix v2.18.1
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Description: Minimal Nix installation for NIP source builds
Tool Type:   nix

Metadata:
  Author:   NexusOS Team
  License:  MIT
  Updated:  2025-11-14
  Homepage: https://git.maiwald.work/Nexus/NexusToolKit

Platforms:
  • x86_64/linux
    Binaries:
      - nix-build (5120 KB)
    Archives:
      - nix-store (100 MB) → store
  • aarch64/linux
    Binaries:
      - nix-build (5120 KB)

Dependencies:
  • curl (required)
  • tar (required)
  • xz (required)
  • bash >=4.0 (required)

Installation:
  Script:       scripts/install.sh
  Verification: scripts/verify.sh
  Post-install: scripts/configure.sh

Status: ⚠️  Not installed
        Install with: nip bootstrap install nix
```

### `nip bootstrap recipes`

List all available bootstrap recipes.

**Example:**
```bash
$ nip bootstrap recipes

📋 Available bootstrap recipes:

  nix      - Minimal Nix installation for NIP source builds
           Version: 2.18.1
           Platforms: 2
  pkgsrc   - Minimal PKGSRC installation for NIP source builds
           Version: 2024Q3
           Platforms: 1
  gentoo   - Minimal Gentoo Portage installation for NIP source builds
           Version: latest
           Platforms: 1
```

### `nip bootstrap update-recipes`

Update recipes from the Git repository.

**Example:**
```bash
$ nip bootstrap update-recipes

📥 Updating bootstrap recipes...
Updating recipes from repository...
✅ Recipes updated successfully
   Updated 3 recipe(s)
```

### `nip bootstrap validate <tool>`

Validate a recipe file to ensure it's correctly formatted and complete.

**Example:**
```bash
$ nip bootstrap validate nix

🔍 Validating nix recipe...
✅ Recipe loaded: minimal-nix v2.18.1
✅ Recipe is valid

Recipe details:
  Name:        minimal-nix
  Version:     2.18.1
  Tool Type:   nix
  Description: Minimal Nix installation for NIP source builds
  Platforms:   2
    • x86_64/linux
      Binaries: 1
      Archives: 1
    • aarch64/linux
      Binaries: 1
      Archives: 0
  Dependencies:
    • curl (required)
    • tar (required)
    • xz (required)
    • bash (required)
```

## How It Works

### Recipe System

NIP uses a recipe-based system to install build tools. Recipes are stored in a Git repository and define:

- **Binaries:** Pre-built executables (e.g., `nix-build`, `bmake`, `emerge`)
- **Archives:** Compressed snapshots (e.g., Nix store, PKGSRC tree, Portage snapshot)
- **Scripts:** Installation, verification, and configuration scripts
- **Dependencies:** System requirements
- **Metadata:** Version, author, license, etc.

### Installation Process

1. **Fetch Recipe:** Download recipe from Git repository
2. **Parse Recipe:** Validate and parse the KDL recipe file
3. **Select Platform:** Choose appropriate binaries for your architecture
4. **Download:** Download binaries and archives with checksum verification
5. **Extract:** Extract archives to installation directory
6. **Install:** Run installation script to set up environment
7. **Verify:** Run verification script to ensure installation succeeded
8. **Configure:** Run post-install script for final configuration

### Installation Location

All tools are installed to:
```
~/.local/share/nip/build-tools/<tool>/
```

This keeps them isolated from system packages and allows easy removal.

### Security

- **HTTPS Only:** All downloads use HTTPS
- **Checksum Verification:** Blake2b-512 checksums verify file integrity
- **User Permissions:** No root access required
- **Sandboxed:** Tools run with user permissions only
- **Rollback:** Automatic backup and rollback on failure

## Troubleshooting

### Recipe Not Found

If you get "Recipe not found", update your recipes:

```bash
nip bootstrap update-recipes
```

### Download Failures

If downloads fail, the system will automatically retry with exponential backoff. If all retries fail:

1. Check your internet connection
2. Try again later (server might be temporarily unavailable)
3. Check if you can access the URL manually

### Installation Failures

If installation fails:

1. Check the error message for details
2. Ensure you have required dependencies (curl, tar, xz, bash)
3. Check disk space (need ~500MB for all three tools)
4. Try removing and reinstalling: `nip bootstrap remove <tool> && nip bootstrap install <tool>`

### Verification Failures

If verification fails but installation completed:

1. The tool might still work, but with warnings
2. Try reinstalling to ensure all files are correct
3. Check the verification script output for specific issues

## Advanced Usage

### Manual Installation

If you prefer to install build tools manually:

- **Nix:** https://nixos.org/download.html
- **PKGSRC:** https://www.pkgsrc.org/
- **Gentoo:** https://wiki.gentoo.org/wiki/Portage

NIP will automatically detect system-installed tools.

### Container Builds

Container support is planned for Phase 3. This will allow building in isolated Docker/Podman containers.

### Custom Recipes

To create custom recipes, see the recipe authoring guide (coming soon).

## Examples

### Build Firefox with Nix

```bash
# Install Nix if not already installed
nip bootstrap install nix

# Build Firefox with Wayland and LTO
nip build firefox +wayland+lto --source=nix

# The built package will be installed to your NIP programs directory
```

### Build Vim with PKGSRC

```bash
# Install PKGSRC
nip bootstrap install pkgsrc

# Build Vim
nip build vim --source=pkgsrc
```

### Build with Auto-Detection

```bash
# NIP will automatically choose the best available source
nip build nginx

# If multiple sources are available, Nix is preferred, then PKGSRC, then Gentoo
```

## See Also

- [Source Build Guide](source-build-guide.md) - Detailed guide on building from source
- [Variant System](../README.md#variant-system) - Using variant flags with builds
- [Recipe Format](../recipes/README.md) - Recipe file format specification

## Support

For issues or questions:
- GitHub Issues: https://git.maiwald.work/Nexus/NexusToolKit/issues
- Documentation: https://git.maiwald.work/Nexus/NexusToolKit/wiki