nip/docs/build-examples.md

# NIP Build System - Examples

## Basic Examples

### Simple Build

Build a package with default settings:

```bash
nip build bash
```

### Build with Single Variant

```bash
nip build firefox +wayland
```

### Build with Multiple Variants

```bash
nip build firefox +wayland +lto +pipewire
```

## Source Selection Examples

### Auto-Detect Source (Default)

```bash
nip build nginx
```

NIP automatically selects the best available source (priority: Nix > PKGSRC > Gentoo).

### Specify Source System

```bash
# Use Nix
nip build firefox --source=nix

# Use PKGSRC
nip build nginx --source=pkgsrc

# Use Gentoo
nip build vim --source=gentoo
```

## Variant Examples

### Graphics Variants

```bash
# Wayland support
nip build firefox +wayland

# X11 support
nip build firefox +X

# Vulkan graphics
nip build mesa +vulkan

# Multiple graphics options
nip build firefox +wayland +vulkan
```

### Audio Variants

```bash
# PipeWire audio
nip build firefox +pipewire

# PulseAudio
nip build firefox +pulseaudio

# ALSA
nip build mpd +alsa

# Multiple audio options
nip build firefox +pipewire +alsa
```

### Optimization Variants

```bash
# Link-time optimization
nip build firefox +lto

# Profile-guided optimization
nip build gcc +pgo

# Both optimizations
nip build firefox +lto +pgo
```

### Security Variants

```bash
# Position-independent executable
nip build nginx +pie

# Full hardening
nip build openssh +hardened

# Multiple security options
nip build nginx +pie +hardened
```

### Combined Variants

```bash
# Modern desktop application
nip build firefox +wayland +vulkan +pipewire +lto +pie

# Optimized server
nip build nginx +lto +pie +hardened

# Development tools
nip build gcc +lto +pgo
```

## Advanced Options

### Verbose Mode

See detailed build output:

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

### Force Rebuild

Skip cache and rebuild from scratch:

```bash
nip build firefox +wayland --rebuild
```

### Build Without Installing

Build but don't install (useful for testing):

```bash
nip build test-package --no-install
```

### Keep Work Files

Keep intermediate build files for debugging:

```bash
nip build firefox --keep-work
```

### Parallel Jobs

Specify number of parallel build jobs:

```bash
nip build firefox --jobs=8
```

### Combined Advanced Options

```bash
nip build firefox +wayland +lto --verbose --rebuild --jobs=8
```

## Package Discovery Examples

### List All Sources

```bash
nip sources
```

Output:
```
📚 Available Package Sources (by priority):

1. 🔵 Nix (nixpkgs)
   Status: ✅ Available
   Packages: ~100,000+

2. 🟢 PKGSRC (NetBSD)
   Status: ❌ Not installed
   Install: https://www.pkgsrc.org/

3. 🟣 Gentoo Portage
   Status: ❌ Not installed
   Install: https://www.gentoo.org/
```

### Search for Package

```bash
# Search for bash
nip sources bash

# Search for firefox
nip sources firefox

# Search for nginx
nip sources nginx
```

## Cache Management Examples

### View Cache Statistics

```bash
nip cache stats
```

Output:
```
📊 Build Cache Statistics

Cached Builds: 15
Total Size: 2.3 MB
Cache Directory: /home/user/.cache/nip/builds

Retention Policy: 30 days
```

### Clean Old Builds

Remove builds older than 30 days:

```bash
nip cache clean
```

### Clear All Cache

Remove all cached builds:

```bash
nip cache clear
```

## Real-World Scenarios

### Scenario 1: Modern Desktop Browser

Build Firefox with modern desktop features:

```bash
nip build firefox +wayland +vulkan +pipewire +lto
```

This enables:
- Wayland display server (native Wayland, no XWayland)
- Vulkan graphics acceleration
- PipeWire audio (modern audio server)
- Link-time optimization (better performance)

### Scenario 2: Optimized Web Server

Build NGINX with security and performance:

```bash
nip build nginx +lto +pie +hardened --source=nix
```

This enables:
- Link-time optimization (better performance)
- Position-independent executable (security)
- Full hardening (additional security measures)
- Uses Nix for reproducible builds

### Scenario 3: Development Environment

Build GCC with optimizations:

```bash
nip build gcc +lto +pgo
```

This enables:
- Link-time optimization
- Profile-guided optimization (best performance)

### Scenario 4: Multimedia Workstation

Build media applications with full codec support:

```bash
# Video player with hardware acceleration
nip build mpv +wayland +vulkan +pipewire

# Audio workstation
nip build ardour +pipewire +lto

# Image editor
nip build gimp +wayland
```

### Scenario 5: Server Infrastructure

Build server components with security focus:

```bash
# Web server
nip build nginx +pie +hardened +lto

# Database
nip build postgresql +pie +hardened

# SSH server
nip build openssh +hardened
```

### Scenario 6: Testing Different Configurations

Test a package with different variants:

```bash
# Test with Wayland
nip build firefox +wayland --no-install

# Test with X11
nip build firefox +X --no-install

# Choose the one that works best
nip build firefox +wayland
```

### Scenario 7: Cross-Source Comparison

Try the same package from different sources:

```bash
# Build from Nix
nip build vim --source=nix

# Build from PKGSRC
nip build vim --source=pkgsrc

# Build from Gentoo
nip build vim --source=gentoo
```

### Scenario 8: Debugging Build Issues

Debug a failing build:

```bash
# First attempt
nip build problematic-package +feature

# If it fails, try verbose mode
nip build problematic-package +feature --verbose

# Try without variants
nip build problematic-package --verbose

# Try different source
nip build problematic-package --source=nix --verbose

# Keep work files for inspection
nip build problematic-package --keep-work --verbose
```

## Package-Specific Examples

### Web Browsers

```bash
# Firefox - Modern desktop
nip build firefox +wayland +vulkan +pipewire +lto

# Chromium - X11 with optimizations
nip build chromium +X +lto

# Brave - Wayland
nip build brave +wayland +pipewire
```

### Web Servers

```bash
# NGINX - Optimized and hardened
nip build nginx +lto +pie +hardened

# Apache - With SSL
nip build apache +ssl +lto

# Caddy - Modern web server
nip build caddy +lto
```

### Development Tools

```bash
# GCC - Optimized compiler
nip build gcc +lto +pgo

# LLVM/Clang - With all targets
nip build llvm +lto

# Rust - Optimized
nip build rust +lto
```

### Text Editors

```bash
# Vim - Full features
nip build vim +X +python +ruby +lto

# Emacs - Wayland native
nip build emacs +wayland +lto

# Neovim - Optimized
nip build neovim +lto
```

### Multimedia Applications

```bash
# VLC - Full codec support
nip build vlc +wayland +pipewire

# MPV - Hardware acceleration
nip build mpv +wayland +vulkan +pipewire

# Blender - Optimized
nip build blender +wayland +vulkan +lto
```

### System Utilities

```bash
# Bash - Optimized shell
nip build bash +lto

# Coreutils - Optimized
nip build coreutils +lto

# Git - With all features
nip build git +lto
```

## Workflow Examples

### Daily Development Workflow

```bash
# Morning: Update and build tools
nip sources
nip build gcc +lto +pgo
nip build rust +lto

# During development: Build dependencies
nip build libfoo +lto
nip build libbar +wayland

# Testing: Build without installing
nip build myproject --no-install

# Final: Build and install
nip build myproject +lto
```

### System Setup Workflow

```bash
# 1. Check available sources
nip sources

# 2. Build essential tools
nip build bash +lto
nip build coreutils +lto
nip build git +lto

# 3. Build desktop environment
nip build sway +wayland
nip build waybar +wayland

# 4. Build applications
nip build firefox +wayland +vulkan +pipewire +lto
nip build alacritty +wayland

# 5. Check cache
nip cache stats
```

### Maintenance Workflow

```bash
# Weekly: Clean old builds
nip cache clean

# Monthly: Review cache
nip cache stats

# As needed: Clear cache
nip cache clear

# Rebuild important packages
nip build firefox +wayland +lto --rebuild
```

## Tips and Tricks

### Tip 1: Use Cache Effectively

```bash
# First build (slow)
nip build firefox +wayland +lto

# Subsequent builds (instant)
nip build firefox +wayland +lto
```

### Tip 2: Test Before Installing

```bash
# Test configuration
nip build mypackage +experimental --no-install

# If successful, install
nip build mypackage +experimental
```

### Tip 3: Combine with Other NIP Commands

```bash
# Build and verify
nip build firefox +wayland
nip verify firefox

# Build and list
nip build bash +lto
nip list | grep bash
```

### Tip 4: Use Verbose for Learning

```bash
# See exactly what NIP does
nip build firefox +wayland --verbose
```

This shows:
- Source detection
- Variant translation
- Build commands
- Grafting process
- Symlink creation

### Tip 5: Parallel Builds for Speed

```bash
# Use all CPU cores
nip build firefox --jobs=$(nproc)

# Or specify number
nip build firefox --jobs=8
```

## Common Patterns

### Pattern 1: Build with Defaults, Add Variants Later

```bash
# Start simple
nip build firefox

# Add variants incrementally
nip build firefox +wayland
nip build firefox +wayland +lto
nip build firefox +wayland +lto +pipewire
```

### Pattern 2: Try Multiple Sources

```bash
# Try each source
for source in nix pkgsrc gentoo; do
    nip build mypackage --source=$source --no-install
done
```

### Pattern 3: Batch Build

```bash
# Build multiple packages
for pkg in bash vim git; do
    nip build $pkg +lto
done
```

### Pattern 4: Conditional Variants

```bash
# Desktop system
if [ "$DESKTOP" = "wayland" ]; then
    nip build firefox +wayland +vulkan +pipewire
else
    nip build firefox +X +pulseaudio
fi
```

## Quick Reference

### Most Common Commands

```bash
# Basic build
nip build <package>

# Build with variants
nip build <package> +variant1 +variant2

# Specify source
nip build <package> --source=nix

# Verbose mode
nip build <package> --verbose

# Force rebuild
nip build <package> --rebuild

# Search for package
nip sources <package>

# Cache management
nip cache stats
nip cache clean
nip cache clear
```

### Most Common Variants

```bash
+wayland    # Wayland display server
+X          # X11 display server
+vulkan     # Vulkan graphics
+pipewire   # PipeWire audio
+pulseaudio # PulseAudio
+lto        # Link-time optimization
+pie        # Position-independent executable
+hardened   # Full hardening
```

## See Also

- User Guide: `source-build-guide.md`
- Help Reference: `build-system-help.md`
- Configuration: `build-configuration.md`
- Troubleshooting: `build-troubleshooting.md`

Happy building! 🚀