nip/docs/build-configuration.md

NIP Build System - Configuration Guide

Overview

This guide covers all configuration options for the NIP build system.

Configuration Files

Build Configuration

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

Format: KDL (KDL Document Language)

Example:

build {
    cache-dir "/var/nip/cache"
    build-logs-dir "/var/nip/cache/logs"
    keep-work false
    rebuild false
    no-install false
    timeout "2h"
    jobs 4
    verbose false

    nix {
        nixpkgs-path "<nixpkgs>"
        store-dir "/nix/store"
    }

    pkgsrc {
        root "/usr/pkgsrc"
        make-conf "/etc/mk.conf"
    }

    gentoo {
        portage-dir "/var/db/repos/gentoo"
        package-use "/etc/portage/package.use"
    }
}

Variant Mappings

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

Format: JSON

Example:

{
  "firefox": {
    "graphics": {
      "wayland": {
        "nix": "waylandSupport = true",
        "pkgsrc": "wayland",
        "gentoo": "wayland",
        "description": "Wayland display server support"
      }
    },
    "audio": {
      "pipewire": {
        "nix": "pipewireSupport = true",
        "pkgsrc": "pulseaudio",
        "gentoo": "pipewire",
        "description": "PipeWire audio support"
      }
    }
  },
  "nginx": {
    "network": {
      "ipv6": {
        "nix": "withIPv6 = true",
        "pkgsrc": "inet6",
        "gentoo": "ipv6",
        "description": "IPv6 support"
      }
    }
  }
}

Configuration Options

Build Options

cache-dir (string)

• Build cache directory
• Default: ~/.cache/nip or /var/nip/cache
• Stores build expressions, logs, and metadata

build-logs-dir (string)

• Build log directory
• Default: <cache-dir>/logs
• Stores detailed build logs

keep-work (boolean)

• Keep intermediate build files
• Default: false
• Useful for debugging build failures

rebuild (boolean)

• Force rebuild, skip cache
• Default: false
• Use when you need fresh builds

no-install (boolean)

• Build but don't install
• Default: false
• Useful for testing builds

timeout (duration)

• Build timeout
• Default: 2h
• Format: 1h, 30m, 2h30m

jobs (integer)

• Number of parallel build jobs
• Default: 4
• Passed to build systems as -j<N>

verbose (boolean)

• Show detailed output
• Default: false
• Can be overridden with --verbose flag

Nix Configuration

nixpkgs-path (string)

• Path to nixpkgs
• Default: <nixpkgs> (uses NIX_PATH)
• Can be absolute path or channel

store-dir (string)

• Nix store directory
• Default: /nix/store
• Usually doesn't need changing

PKGSRC Configuration

root (string)

• PKGSRC root directory
• Default: /usr/pkgsrc
• Location of PKGSRC tree

make-conf (string)

• System mk.conf location
• Default: /etc/mk.conf
• NIP generates per-package mk.conf in cache

Gentoo Configuration

portage-dir (string)

• Portage repository directory
• Default: /var/db/repos/gentoo
• Location of Portage tree

package-use (string)

• System package.use location
• Default: /etc/portage/package.use
• NIP generates per-package entries in cache

Variant Mapping Configuration

Structure

Variant mappings define how NIP variant flags translate to source-specific configuration:

{
  "<package>": {
    "<domain>": {
      "<value>": {
        "nix": "<nix-override>",
        "pkgsrc": "<pkg-option>",
        "gentoo": "<use-flag>",
        "description": "<description>"
      }
    }
  }
}

Generic vs. Package-Specific

Generic mappings work for all packages:

• Defined in NIP's built-in mappings
• Used when no package-specific mapping exists

Package-specific mappings override generic:

• Defined in your custom mappings file
• Take precedence over generic mappings

Mapping Precedence

1. Custom package-specific (highest priority)
2. Built-in package-specific
3. Custom generic
4. Built-in generic (lowest priority)

Examples

Simple mapping:

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

Multiple domains:

{
  "nginx": {
    "network": {
      "ipv6": {
        "nix": "withIPv6 = true",
        "pkgsrc": "inet6",
        "gentoo": "ipv6",
        "description": "IPv6 support"
      }
    },
    "security": {
      "ssl": {
        "nix": "withSSL = true",
        "pkgsrc": "ssl",
        "gentoo": "ssl",
        "description": "SSL/TLS support"
      }
    }
  }
}

Multiple packages:

{
  "firefox": {
    "graphics": {
      "wayland": { ... }
    }
  },
  "chromium": {
    "graphics": {
      "wayland": { ... }
    }
  }
}

Environment Variables

NIP_CACHE_DIR

Override cache directory:

export NIP_CACHE_DIR=/custom/cache
nip build firefox

NIP_VERBOSE

Enable verbose mode:

export NIP_VERBOSE=1
nip build firefox

NIX_PATH

Set Nix package path:

export NIX_PATH=nixpkgs=/path/to/nixpkgs
nip build firefox --source=nix

Cache Management

Cache Structure

~/.cache/nip/
├── builds/              # Cached build metadata
│   ├── nix-firefox-blake2b-abc.json
│   └── pkgsrc-nginx-blake2b-def.json
├── nix/                 # Nix build files
│   ├── build-firefox.nix
│   └── build-result-firefox
├── pkgsrc/              # PKGSRC build files
│   └── mk.conf.nginx
├── gentoo/              # Gentoo build files
│   └── package.use.vim
└── logs/                # Build logs
    ├── nix/
    ├── pkgsrc/
    └── gentoo/

Cache Retention

Default: 30 days

Automatic cleanup:

nip cache clean

Manual cleanup:

nip cache clear

Cache Size

Check cache size:

nip cache stats

Typical cache sizes:

• Metadata: ~1 KB per build
• Expressions: ~1 KB per build
• Logs: ~10-100 KB per build

Troubleshooting Configuration

Build Configuration Not Found

NIP looks for configuration in:

1. ~/.config/nip/build.kdl
2. /etc/nip/build.kdl

If not found, uses defaults.

Variant Mappings Not Working

1. Check file location: ~/.config/nip/variant-mappings.json
2. Validate JSON syntax
3. Use --verbose to see if mappings are loaded
4. Check for typos in package/domain/value names

Cache Not Working

1. Check cache directory exists and is writable
2. Check disk space
3. Try nip cache clear and rebuild
4. Use --rebuild to force fresh build

Source System Not Detected

1. Check installation:

   • Nix: /nix directory exists
   • PKGSRC: /usr/pkgsrc directory exists
   • Gentoo: /usr/bin/emerge executable exists

2. Use nip sources to see detected systems

3. Manually specify source: --source=<name>

Security Considerations

Input Validation

All inputs are validated:

• Package names: ^[a-zA-Z0-9._-]+$ (max 255 chars)
• Override keys: ^[a-zA-Z0-9_-]+$ (max 100 chars)
• Paths: No .. or absolute paths allowed

Command Execution

All external commands use shell escaping:

execCmd("nix-build " & quoteShell(exprFile))

File Operations

All file writes are atomic:

1. Write to temporary file
2. Rename to final location
3. Clean up on error

Performance Tuning

Parallel Builds

Increase parallel jobs:

build {
    jobs 8
}

Or via command line:

nip build firefox --jobs=8

Cache Retention

Adjust retention period (in build.kdl):

build {
    cache-retention-days 60
}

Build Timeout

Increase timeout for large packages:

build {
    timeout "4h"
}

Examples

Minimal Configuration

build {
    cache-dir "~/.cache/nip"
    jobs 4
}

Development Configuration

build {
    cache-dir "~/.cache/nip"
    keep-work true
    verbose true
    jobs 8
}

Production Configuration

build {
    cache-dir "/var/nip/cache"
    build-logs-dir "/var/log/nip/builds"
    keep-work false
    timeout "4h"
    jobs 16

    nix {
        nixpkgs-path "/nix/var/nix/profiles/per-user/root/channels/nixpkgs"
    }
}

See Also

• User Guide: source-build-guide.md
• Help Reference: build-system-help.md
• Troubleshooting: troubleshooting.md