nip/docs/build-troubleshooting.md

# NIP Build System - Troubleshooting Guide

## Common Issues and Solutions

### Build Failures

#### Issue: Build fails with "command not found"

**Symptoms:**
```
Error: nix-build: command not found
```

**Cause:** Source system not installed or not in PATH

**Solution:**
1. Check if source is installed:
   ```bash
   nip sources
   ```

2. Install the missing source system:
   - **Nix:** https://nixos.org/download.html
   - **PKGSRC:** https://www.pkgsrc.org/
   - **Gentoo:** https://www.gentoo.org/

3. Or use a different source:
   ```bash
   nip build <package> --source=<available-source>
   ```

#### Issue: Build times out

**Symptoms:**
```
Error: Build timed out after 2 hours
```

**Cause:** Large package or slow system

**Solution:**
1. Increase timeout in config (`~/.config/nip/build.kdl`):
   ```kdl
   build {
       timeout "4h"
   }
   ```

2. Or check if binary packages are available (Nix, Gentoo)

#### Issue: Build fails with compilation errors

**Symptoms:**
```
Error: compilation failed
gcc: error: ...
```

**Cause:** Missing dependencies, incompatible variants, or upstream issues

**Solution:**
1. Try without variants first:
   ```bash
   nip build <package>
   ```

2. Use verbose mode to see full error:
   ```bash
   nip build <package> --verbose
   ```

3. Try a different source system:
   ```bash
   nip build <package> --source=nix
   ```

4. Check if package is available:
   ```bash
   nip sources <package>
   ```

### Variant Issues

#### Issue: Variant not working

**Symptoms:**
```
⚠️  Warning: Unmapped variant: +myfeature
```

**Cause:** No mapping exists for this variant

**Solution:**
1. Check available variants in documentation

2. Create custom mapping in `~/.config/nip/variant-mappings.json`:
   ```json
   {
     "mypackage": {
       "feature": {
         "enabled": {
           "nix": "enableFeature = true",
           "pkgsrc": "feature",
           "gentoo": "feature",
           "description": "Enable feature"
         }
       }
     }
   }
   ```

3. Use verbose mode to see how variants are translated:
   ```bash
   nip build <package> +myfeature --verbose
   ```

#### Issue: Conflicting variants

**Symptoms:**
```
Error: Cannot enable both +wayland and +X
```

**Cause:** Some variants are mutually exclusive

**Solution:**
Choose one variant:
```bash
nip build firefox +wayland  # OR
nip build firefox +X
```

### Cache Issues

#### Issue: Cache not working

**Symptoms:**
- Rebuilds every time
- Cache stats show 0 builds

**Cause:** Cache directory not writable or corrupted

**Solution:**
1. Check cache directory permissions:
   ```bash
   ls -la ~/.cache/nip
   ```

2. Clear and rebuild cache:
   ```bash
   nip cache clear
   nip build <package>
   ```

3. Check disk space:
   ```bash
   df -h ~/.cache
   ```

#### Issue: Cache taking too much space

**Symptoms:**
- Large cache directory
- Low disk space

**Solution:**
1. Check cache size:
   ```bash
   nip cache stats
   ```

2. Clean old builds:
   ```bash
   nip cache clean
   ```

3. Clear all cache:
   ```bash
   nip cache clear
   ```

### Package Discovery Issues

#### Issue: Package not found

**Symptoms:**
```
Error: Package 'mypackage' not found in any source
```

**Cause:** Package name incorrect or not available

**Solution:**
1. Search across all sources:
   ```bash
   nip sources mypackage
   ```

2. Check package name spelling

3. Try alternative names:
   ```bash
   nip sources firefox
   nip sources firefox-esr
   ```

4. Check if source is installed:
   ```bash
   nip sources
   ```

#### Issue: Source system not detected

**Symptoms:**
```
⚠️  No source systems detected
```

**Cause:** No source systems installed

**Solution:**
1. Install at least one source system:
   - **Nix:** Easiest to install, largest package collection
   - **PKGSRC:** Good for BSD systems
   - **Gentoo:** For Gentoo Linux

2. Verify installation:
   ```bash
   # Nix
   ls /nix

   # PKGSRC
   ls /usr/pkgsrc

   # Gentoo
   which emerge
   ```

### Installation Issues

#### Issue: Permission denied during installation

**Symptoms:**
```
Error: Permission denied: /Programs/...
```

**Cause:** Insufficient permissions to write to `/Programs`

**Solution:**
1. Run with appropriate privileges (if needed)

2. Or build without installing:
   ```bash
   nip build <package> --no-install
   ```

#### Issue: Symlinks not created

**Symptoms:**
- Package installed but not in PATH
- Executables not found

**Cause:** Symlink creation failed

**Solution:**
1. Check `/System/Links/Executables`:
   ```bash
   ls -la /System/Links/Executables
   ```

2. Manually create symlinks if needed

3. Check permissions on `/System/Links`

### Configuration Issues

#### Issue: Configuration not loaded

**Symptoms:**
- Custom settings ignored
- Using default values

**Cause:** Configuration file not found or invalid

**Solution:**
1. Check configuration file location:
   ```bash
   cat ~/.config/nip/build.kdl
   ```

2. Validate KDL syntax

3. Use verbose mode to see loaded config:
   ```bash
   nip build <package> --verbose
   ```

#### Issue: Variant mappings not working

**Symptoms:**
- Custom mappings ignored
- Unmapped variant warnings

**Cause:** JSON syntax error or wrong location

**Solution:**
1. Check file location:
   ```bash
   cat ~/.config/nip/variant-mappings.json
   ```

2. Validate JSON syntax:
   ```bash
   python3 -m json.tool ~/.config/nip/variant-mappings.json
   ```

3. Check for typos in package/domain/value names

## Source-Specific Issues

### Nix Issues

#### Issue: Nix expression generation fails

**Symptoms:**
```
Error: Failed to generate Nix expression
```

**Solution:**
1. Check package name is valid
2. Use verbose mode to see expression
3. Try without overrides first

#### Issue: nix-build fails

**Symptoms:**
```
Error: nix-build failed
```

**Solution:**
1. Check Nix installation:
   ```bash
   nix-env --version
   ```

2. Update nixpkgs:
   ```bash
   nix-channel --update
   ```

3. Try with verbose mode

### PKGSRC Issues

#### Issue: Package not found in /usr/pkgsrc

**Symptoms:**
```
Error: Package not found in PKGSRC tree
```

**Solution:**
1. Update PKGSRC tree:
   ```bash
   cd /usr/pkgsrc
   cvs update -dP
   ```

2. Check package category:
   ```bash
   find /usr/pkgsrc -name <package>
   ```

#### Issue: bmake fails

**Symptoms:**
```
Error: bmake failed
```

**Solution:**
1. Check mk.conf syntax
2. Try without PKG_OPTIONS
3. Check PKGSRC documentation

### Gentoo Issues

#### Issue: emerge fails

**Symptoms:**
```
Error: emerge failed
```

**Solution:**
1. Sync Portage tree:
   ```bash
   emerge --sync
   ```

2. Check USE flags:
   ```bash
   emerge -pv <package>
   ```

3. Try without USE flags first

#### Issue: Root privileges required

**Symptoms:**
```
Error: emerge requires root privileges
```

**Solution:**
1. Run with sudo (if appropriate)
2. Or use --no-install to build only

## Performance Issues

### Issue: Builds are slow

**Symptoms:**
- Builds take very long
- System is slow during builds

**Solution:**
1. Increase parallel jobs:
   ```bash
   nip build <package> --jobs=8
   ```

2. Or in config:
   ```kdl
   build {
       jobs 8
   }
   ```

3. Use binary packages when available (Nix, Gentoo)

4. Check system resources:
   ```bash
   top
   df -h
   ```

### Issue: High memory usage

**Symptoms:**
- System runs out of memory
- Build killed by OOM

**Solution:**
1. Reduce parallel jobs:
   ```bash
   nip build <package> --jobs=2
   ```

2. Close other applications

3. Add swap space

## Debugging Tips

### Enable Verbose Mode

Always use verbose mode when troubleshooting:
```bash
nip build <package> --verbose
```

This shows:
- Source detection
- Variant translation
- Build commands
- Full build output
- Grafting steps

### Check Build Logs

Build logs are stored in cache directory:
```bash
ls ~/.cache/nip/logs/
```

View recent log:
```bash
cat ~/.cache/nip/logs/nix/firefox-*.log
```

### Test Without Installing

Build without installing to test:
```bash
nip build <package> --no-install
```

### Force Rebuild

Skip cache to ensure fresh build:
```bash
nip build <package> --rebuild
```

### Keep Work Files

Keep intermediate files for inspection:
```bash
nip build <package> --keep-work
```

## Getting More Help

### Check Documentation

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

### Check Source System Documentation

- **Nix:** https://nixos.org/manual/nix/stable/
- **PKGSRC:** https://www.pkgsrc.org/docs/
- **Gentoo:** https://wiki.gentoo.org/

### Report Issues

If you encounter a bug:
1. Use verbose mode to capture details
2. Check if issue is reproducible
3. Report with full error message and steps to reproduce

## Quick Reference

### Diagnostic Commands

```bash
# Check available sources
nip sources

# Search for package
nip sources <package>

# Check cache
nip cache stats

# Build with verbose output
nip build <package> --verbose

# Force rebuild
nip build <package> --rebuild

# Build without installing
nip build <package> --no-install
```

### Common Fixes

```bash
# Clear cache
nip cache clear

# Clean old builds
nip cache clean

# Try different source
nip build <package> --source=nix

# Build without variants
nip build <package>

# Increase timeout
# Edit ~/.config/nip/build.kdl
```

## Prevention

### Best Practices

1. **Start simple:** Build without variants first
2. **Use cache:** Don't use --rebuild unnecessarily
3. **Check sources:** Use `nip sources` before building
4. **Keep updated:** Update source systems regularly
5. **Monitor space:** Clean cache periodically
6. **Use verbose:** When in doubt, use --verbose

### Regular Maintenance

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

# Monthly: Check cache size
nip cache stats

# As needed: Clear cache
nip cache clear
```

Happy building! 🚀