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:

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:

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

nip sources [package]

Examples:

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

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:

nip cache clean

nip cache clear

Clear all cached builds.

Usage:

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:

nip build <package> +domain=value

Multiple variants can be combined:

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:

{
  "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:

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:

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:

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:

# 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

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

# 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

# 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

# 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

# View cache statistics
nip cache stats

# Clean old builds
nip cache clean

# Clear all cache
nip cache clear

Package Discovery

# 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