469 lines
8.2 KiB
Markdown
469 lines
8.2 KiB
Markdown
# 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`
|