nexus
/
nip
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
nip/docs/bootstrap-overview.md

9.5 KiB
Raw Blame History

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

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

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

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

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

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

# 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

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

nip bootstrap remove gentoo

Update Recipes

# 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

# 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

# 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 for complete workflow.

Debian/Ubuntu

Recommended: Recipe-based installation

nip bootstrap install nix
nip bootstrap install gentoo

Why: Access to latest packages and custom builds

Gentoo

Recommended: Use native Portage

# NIP automatically detects system Portage
nip build vim +python

Why: Already have the tools!

NixOS

Recommended: Use native Nix

# NIP automatically detects system Nix
nip build firefox

Why: Already have the tools!

BSD (FreeBSD, NetBSD, etc.)

Recommended: PKGSRC (native) or Nix

nip bootstrap install pkgsrc
nip bootstrap install nix

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

Troubleshooting

Build Tools Not Detected

# 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

# 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

# Check logs
nip logs 50

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

# Report issue if persistent

Container Runtime Not Found

# 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

# 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

Building Standalone Binaries

See Build Binaries Guide

API Reference

See Bootstrap API Documentation

Documentation Index

User Documentation

  1. Getting Started - Complete introduction to NIP
  2. Bootstrap Overview - This document
  3. Bootstrap Guide - Detailed bootstrap usage
  4. Bootstrap Detection Flow - How detection works
  5. Source Build Guide - Building from source
  6. Arch Linux Guide - Arch-specific workflows

Developer Documentation

  1. Bootstrap API - API reference
  2. Recipe Authoring - Creating recipes
  3. Build Binaries - Building standalone tools

Quick Reference

Common Commands

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