nip/docs/build-system-help.md

# NIP Build System - Help Documentation

## Overview

The NIP build system allows you to build packages from source using multiple package managers (Nix, PKGSRC, Gentoo) with full variant support, intelligent caching, and automatic system integration.

## Commands

### `nip build <package> [options]`

Build a package from source with optional variant flags.

**Usage:**
```bash
nip build <package> [+variant...] [options]
```

**Options:**
- `--source=<name>` - Specify source system (nix, pkgsrc, gentoo). Default: auto-detect
- `--rebuild` - Force rebuild, skip cache
- `--no-install` - Build but don't install
- `--verbose` - Show detailed build output
- `--keep-work` - Keep intermediate build files

**Variant Flags:**
Variants are specified with `+domain=value` syntax:
- `+wayland` - Enable Wayland support (graphics domain)
- `+lto` - Enable link-time optimization (optimization domain)
- `+pipewire` - Enable PipeWire audio (audio domain)
- `+pie` - Enable position-independent executable (security domain)

**Examples:**
```bash
# Build Firefox with Wayland and LTO
nip build firefox +wayland +lto

# Build from specific source
nip build nginx --source=pkgsrc

# Build with verbose output
nip build bash +lto --verbose

# Force rebuild (skip cache)
nip build firefox +wayland --rebuild

# Build but don't install
nip build test-package --no-install
```

### `nip sources [package]`

List available source systems and optionally search for a package.

**Usage:**
```bash
nip sources [package]
```

**Examples:**
```bash
# List all available sources
nip sources

# Search for bash in all sources
nip sources bash

# Check if firefox is available
nip sources firefox
```

### `nip cache stats`

Show build cache statistics.

**Usage:**
```bash
nip cache stats
```

**Output:**
- Number of cached builds
- Total cache size
- Cache directory location

### `nip cache clean`

Remove old cached builds (older than 30 days).

**Usage:**
```bash
nip cache clean
```

### `nip cache clear`

Clear all cached builds.

**Usage:**
```bash
nip cache clear
```

## Variant System

### Variant Domains

The variant system organizes build options into semantic domains:

**Graphics Domain:**
- `wayland` - Wayland display server support
- `X` - X11 display server support
- `vulkan` - Vulkan graphics API

**Audio Domain:**
- `pipewire` - PipeWire audio server
- `pulseaudio` - PulseAudio sound server
- `alsa` - ALSA audio support

**Optimization Domain:**
- `lto` - Link-time optimization
- `pgo` - Profile-guided optimization

**Security Domain:**
- `pie` - Position-independent executable
- `hardened` - Full hardening

### Variant Syntax

Variants are specified with the `+` prefix:
```bash
nip build <package> +domain=value
```

Multiple variants can be combined:
```bash
nip build firefox +wayland +lto +pipewire
```

### Variant Mapping

NIP automatically translates variant flags to source-specific configuration:

**Nix:** Variant → Nix override attribute
```
+wayland → waylandSupport = true
+lto → enableLTO = true
```

**PKGSRC:** Variant → PKG_OPTIONS flag
```
+wayland → wayland
+pulseaudio → pulseaudio
```

**Gentoo:** Variant → USE flag
```
+wayland → wayland
+lto → lto
```

### Custom Mappings

You can define custom variant mappings in `~/.config/nip/variant-mappings.json`:

```json
{
  "firefox": {
    "graphics": {
      "wayland": {
        "nix": "waylandSupport = true",
        "pkgsrc": "wayland",
        "gentoo": "wayland",
        "description": "Wayland support"
      }
    }
  }
}
```

## Source Systems

### Nix

**Detection:** Checks for `/nix` directory
**Packages:** ~100,000+
**Build Method:** From source with overrides
**Configuration:** Nix expressions with override attributes

**Example:**
```bash
nip build firefox +wayland --source=nix
```

### PKGSRC

**Detection:** Checks for `/usr/pkgsrc` directory
**Packages:** ~27,000+
**Build Method:** Always from source with PKG_OPTIONS
**Configuration:** mk.conf with PKG_OPTIONS settings

**Example:**
```bash
nip build nginx --source=pkgsrc
```

### Gentoo Portage

**Detection:** Checks for `/usr/bin/emerge` executable
**Packages:** ~20,000+
**Build Method:** From source with USE flags
**Configuration:** package.use with USE flags

**Example:**
```bash
nip build vim --source=gentoo
```

## Build Caching

NIP intelligently caches builds based on variant fingerprints:

**Cache Hit:** If you build the same package with the same variants, NIP reuses the cached build instantly.

**Cache Miss:** If variants change, NIP performs a fresh build.

**Cache Management:**
```bash
# View cache statistics
nip cache stats

# Clean old builds (30+ days)
nip cache clean

# Clear all cached builds
nip cache clear
```

**Cache Location:** `~/.cache/nip/builds/` or `/var/nip/cache/builds/`

## Installation

Built packages are installed to `/Programs` with the following structure:

```
/Programs/
└── <package>/
    ├── <version>/
    │   └── <cas-hash>/
    │       └── <variant-fingerprint>/
    │           ├── bin/
    │           ├── lib/
    │           └── ...
    └── Current -> <version>/<cas-hash>/<variant-fingerprint>
```

**System Integration:**
- Executables are symlinked to `/System/Links/Executables/`
- Libraries are symlinked to `/System/Links/Libraries/`

## Troubleshooting

### Build Fails

1. **Check build log:** Build output is displayed during build
2. **Try verbose mode:** `nip build <package> --verbose`
3. **Force rebuild:** `nip build <package> --rebuild`
4. **Check source availability:** `nip sources`

### Package Not Found

1. **Search across sources:** `nip sources <package>`
2. **Try different source:** `nip build <package> --source=<name>`
3. **Check package name:** Ensure correct spelling

### Variant Not Working

1. **Check mapping:** Unmapped variants are displayed during build
2. **Add custom mapping:** Edit `~/.config/nip/variant-mappings.json`
3. **Use verbose mode:** See exact flags being used

### Cache Issues

1. **Clear cache:** `nip cache clear`
2. **Force rebuild:** `nip build <package> --rebuild`
3. **Check cache stats:** `nip cache stats`

## Configuration

### Build Configuration

Location: `~/.config/nip/build.kdl` or `/etc/nip/build.kdl`

```kdl
build {
    cache-dir "/var/nip/cache"
    keep-work false
    timeout "2h"
    jobs 4
}
```

### Variant Mappings

Location: `~/.config/nip/variant-mappings.json`

See "Custom Mappings" section above for format.

## Examples

### Basic Builds

```bash
# Simple build
nip build bash

# Build with single variant
nip build firefox +wayland

# Build with multiple variants
nip build firefox +wayland +lto +pipewire
```

### Source Selection

```bash
# Auto-detect source (default)
nip build nginx

# Use specific source
nip build nginx --source=nix
nip build nginx --source=pkgsrc
nip build nginx --source=gentoo
```

### Advanced Options

```bash
# Verbose build
nip build firefox +wayland --verbose

# Force rebuild
nip build firefox +wayland --rebuild

# Build without installing
nip build test-package --no-install

# Keep intermediate files
nip build firefox --keep-work
```

### Cache Management

```bash
# View cache statistics
nip cache stats

# Clean old builds
nip cache clean

# Clear all cache
nip cache clear
```

### Package Discovery

```bash
# List all sources
nip sources

# Search for package
nip sources bash
nip sources firefox
nip sources nginx
```

## Tips

1. **Use cache:** Let NIP cache builds for instant reuse
2. **Start simple:** Build without variants first, add variants as needed
3. **Check sources:** Use `nip sources <package>` to find packages
4. **Use verbose:** Add `--verbose` when troubleshooting
5. **Custom mappings:** Add package-specific mappings for better control

## See Also

- NIP Package Manager Documentation
- Variant System Documentation
- Configuration Guide
- Troubleshooting Guide