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

8.8 KiB
Raw Blame History

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

# 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

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

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

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

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

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

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

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

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

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

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:

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

# 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

# Install PKGSRC
nip bootstrap install pkgsrc

# Build Vim
nip build vim --source=pkgsrc

Build with Auto-Detection

# 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

Support

For issues or questions: