372 lines
8.8 KiB
Markdown
372 lines
8.8 KiB
Markdown
# 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
|