# 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 `, 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 ``` **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 ``` ### 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)