9.7 KiB

Raw Blame History

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:

Check if source is installed:
```
nip sources
```
Install the missing source system:
- Nix: https://nixos.org/download.html
- PKGSRC: https://www.pkgsrc.org/
- Gentoo: https://www.gentoo.org/

Or use a different source:

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:

Increase timeout in config (~/.config/nip/build.kdl):
```
build {
    timeout "4h"
}
```
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:

Try without variants first:
```
nip build <package>
```
Use verbose mode to see full error:
```
nip build <package> --verbose
```
Try a different source system:
```
nip build <package> --source=nix
```
Check if package is available:
```
nip sources <package>
```

Variant Issues

Issue: Variant not working

Symptoms:

⚠️  Warning: Unmapped variant: +myfeature

Cause: No mapping exists for this variant

Solution:

Check available variants in documentation

Create custom mapping in ~/.config/nip/variant-mappings.json:

{
  "mypackage": {
    "feature": {
      "enabled": {
        "nix": "enableFeature = true",
        "pkgsrc": "feature",
        "gentoo": "feature",
        "description": "Enable feature"
      }
    }
  }
}

Use verbose mode to see how variants are translated:
```
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:

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:

Check cache directory permissions:
```
ls -la ~/.cache/nip
```
Clear and rebuild cache:
```
nip cache clear
nip build <package>
```
Check disk space:
```
df -h ~/.cache
```

Issue: Cache taking too much space

Symptoms:

Large cache directory
Low disk space

Solution:

Check cache size:
```
nip cache stats
```
Clean old builds:
```
nip cache clean
```
Clear all cache:
```
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:

Search across all sources:
```
nip sources mypackage
```
Check package name spelling

Try alternative names:

nip sources firefox
nip sources firefox-esr

Check if source is installed:
```
nip sources
```

Issue: Source system not detected

Symptoms:

⚠️  No source systems detected

Cause: No source systems installed

Solution:

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

Verify installation:

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

Run with appropriate privileges (if needed)
Or build without installing:
```
nip build <package> --no-install
```

Issue: Symlinks not created

Symptoms:

Package installed but not in PATH
Executables not found

Cause: Symlink creation failed

Solution:

Check /System/Links/Executables:
```
ls -la /System/Links/Executables
```
Manually create symlinks if needed
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:

Check configuration file location:
```
cat ~/.config/nip/build.kdl
```
Validate KDL syntax
Use verbose mode to see loaded config:
```
nip build <package> --verbose
```

Issue: Variant mappings not working

Symptoms:

Custom mappings ignored
Unmapped variant warnings

Cause: JSON syntax error or wrong location

Solution:

Check file location:

cat ~/.config/nip/variant-mappings.json

Validate JSON syntax:

python3 -m json.tool ~/.config/nip/variant-mappings.json

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:

Check package name is valid
Use verbose mode to see expression
Try without overrides first

Issue: nix-build fails

Symptoms:

Error: nix-build failed

Solution:

Check Nix installation:
```
nix-env --version
```
Update nixpkgs:
```
nix-channel --update
```
Try with verbose mode

PKGSRC Issues

Issue: Package not found in /usr/pkgsrc

Symptoms:

Error: Package not found in PKGSRC tree

Solution:

Update PKGSRC tree:
```
cd /usr/pkgsrc
cvs update -dP
```
Check package category:
```
find /usr/pkgsrc -name <package>
```

Issue: bmake fails

Symptoms:

Error: bmake failed

Solution:

Check mk.conf syntax
Try without PKG_OPTIONS
Check PKGSRC documentation

Gentoo Issues

Issue: emerge fails

Symptoms:

Error: emerge failed

Solution:

Sync Portage tree:
```
emerge --sync
```
Check USE flags:
```
emerge -pv <package>
```
Try without USE flags first

Issue: Root privileges required

Symptoms:

Error: emerge requires root privileges

Solution:

Run with sudo (if appropriate)
Or use --no-install to build only

Performance Issues

Issue: Builds are slow

Symptoms:

Builds take very long
System is slow during builds

Solution:

Increase parallel jobs:
```
nip build <package> --jobs=8
```
Or in config:
```
build {
    jobs 8
}
```
Use binary packages when available (Nix, Gentoo)
Check system resources:
```
top
df -h
```

Issue: High memory usage

Symptoms:

System runs out of memory
Build killed by OOM

Solution:

Reduce parallel jobs:
```
nip build <package> --jobs=2
```
Close other applications
Add swap space

Debugging Tips

Enable Verbose Mode

Always use verbose mode when troubleshooting:

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:

ls ~/.cache/nip/logs/

View recent log:

cat ~/.cache/nip/logs/nix/firefox-*.log

Test Without Installing

Build without installing to test:

nip build <package> --no-install

Force Rebuild

Skip cache to ensure fresh build:

nip build <package> --rebuild

Keep Work Files

Keep intermediate files for inspection:

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:

Use verbose mode to capture details
Check if issue is reproducible
Report with full error message and steps to reproduce

Quick Reference

Diagnostic Commands

# 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

# 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

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

Regular Maintenance

# Weekly: Clean old builds
nip cache clean

# Monthly: Check cache size
nip cache stats

# As needed: Clear cache
nip cache clear

Happy building! 🚀

9.7 KiB Raw Blame History

NIP Build System - Troubleshooting Guide

Common Issues and Solutions

Build Failures

Issue: Build fails with "command not found"

Issue: Build times out

Issue: Build fails with compilation errors

Variant Issues

Issue: Variant not working

Issue: Conflicting variants

Cache Issues

Issue: Cache not working

Issue: Cache taking too much space

Package Discovery Issues

Issue: Package not found

Issue: Source system not detected

Installation Issues

Issue: Permission denied during installation

Issue: Symlinks not created

Configuration Issues

Issue: Configuration not loaded

Issue: Variant mappings not working

Source-Specific Issues

Nix Issues

Issue: Nix expression generation fails

Issue: nix-build fails

PKGSRC Issues

Issue: Package not found in /usr/pkgsrc

Issue: bmake fails

Gentoo Issues

Issue: emerge fails

Issue: Root privileges required

Performance Issues

Issue: Builds are slow

Issue: High memory usage

Debugging Tips

Enable Verbose Mode

Check Build Logs

Test Without Installing

Force Rebuild

Keep Work Files

Getting More Help

Check Documentation

Check Source System Documentation

Report Issues

Quick Reference

Diagnostic Commands

Common Fixes

Prevention

Best Practices

Regular Maintenance

9.7 KiB

Raw Blame History