# 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:**
```kdl
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:**
```json
{
  "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:

```json
{
  "<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:**
```json
{
  "firefox": {
    "graphics": {
      "wayland": {
        "nix": "waylandSupport = true",
        "pkgsrc": "wayland",
        "gentoo": "wayland",
        "description": "Wayland support"
      }
    }
  }
}
```

**Multiple domains:**
```json
{
  "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:**
```json
{
  "firefox": {
    "graphics": {
      "wayland": { ... }
    }
  },
  "chromium": {
    "graphics": {
      "wayland": { ... }
    }
  }
}
```

## Environment Variables

### NIP_CACHE_DIR

Override cache directory:
```bash
export NIP_CACHE_DIR=/custom/cache
nip build firefox
```

### NIP_VERBOSE

Enable verbose mode:
```bash
export NIP_VERBOSE=1
nip build firefox
```

### NIX_PATH

Set Nix package path:
```bash
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:**
```bash
nip cache clean
```

**Manual cleanup:**
```bash
nip cache clear
```

### Cache Size

Check cache size:
```bash
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:
```nim
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:
```kdl
build {
    jobs 8
}
```

Or via command line:
```bash
nip build firefox --jobs=8
```

### Cache Retention

Adjust retention period (in build.kdl):
```kdl
build {
    cache-retention-days 60
}
```

### Build Timeout

Increase timeout for large packages:
```kdl
build {
    timeout "4h"
}
```

## Examples

### Minimal Configuration

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

### Development Configuration

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

### Production Configuration

```kdl
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`