# NIP Dependency Resolution System

**Version:** 1.0  
**Status:** Production Ready  
**Last Updated:** November 26, 2025

---

## Overview

NIP includes a production-ready dependency resolution system that automatically determines which packages to install and in what order, handling complex dependency relationships, version constraints, and package variants.

### Key Features

- **Automatic Resolution**: Solves complex dependency graphs automatically
- **Conflict Detection**: Identifies and reports incompatible packages
- **Variant Support**: Choose between different package configurations
- **Performance**: Optimized for speed with intelligent caching
- **NipCell Fallback**: Isolate conflicting packages in separate environments

---

## Quick Start

### Installing a Single Package

```bash
# Install a package with automatic dependency resolution
nip install nginx

# NIP will:
# 1. Find nginx in available repositories
# 2. Resolve all dependencies (openssl, pcre, zlib, etc.)
# 3. Check for conflicts
# 4. Create installation plan
# 5. Install in correct order
```

### Installing Multiple Packages

```bash
# Install multiple packages at once
nip install nginx postgresql redis

# NIP will resolve all dependencies and check for conflicts
# between the three packages
```

### Resolving Dependencies Without Installing

```bash
# Resolve dependencies to see what would be installed
nip resolve nginx

# Output shows:
# ✅ Resolution successful!
# 
# 📦 Packages: 12
# ⏱️  Time: 47.3ms
# 💾 Cache: HIT
# 
# 📋 Installation order:
#   1. zlib 1.2.13
#   2. pcre 8.45
#   3. openssl 3.0.8
#   4. nginx 1.24.0
```

### Viewing the Installation Plan

```bash
# See what will be installed without actually installing
nip install --dry-run nginx

# Output shows:
# - Packages to install
# - Installation order
# - Dependency relationships
# - Any warnings or conflicts
```

---

## Understanding Dependencies

### Dependency Types

**Required Dependencies**
```
nginx depends on:
  - openssl (required for HTTPS)
  - pcre (required for regex support)
  - zlib (required for compression)
```

**Optional Dependencies**
```
nginx can optionally use:
  - geoip (for geographic IP filtering)
  - lua (for scripting support)
```

### Version Constraints

NIP supports version constraints:

```bash
# Exact version
nip install nginx=1.24.0

# Minimum version
nip install nginx>=1.20.0

# Version range
nip install nginx>=1.20.0,<2.0.0

# Latest compatible
nip install nginx~1.24  # Allows 1.24.x but not 1.25.x
```

---

## CLI Commands

### nip resolve

Resolve dependencies without installing:

```bash
# Basic resolution
nip resolve nginx

# With version constraint
nip resolve nginx ">=1.24.0"

# With USE flags
nip resolve nginx --use-flags=ssl,http2

# With specific libc and allocator
nip resolve nginx --libc=musl --allocator=jemalloc

# JSON output for scripting
nip resolve nginx --json

# Verbose output
nip resolve nginx --verbose
```

**Output:**
```
🔍 Resolving dependencies...
   Package: nginx
   Constraint: *
   Variant flags:
     features: ssl, http2

✅ Resolution successful!

📦 Packages: 12
⏱️  Time: 47.3ms
💾 Cache: HIT

📋 Installation order:
  1. zlib 1.2.13
  2. pcre 8.45
  3. openssl 3.0.8
  4. nginx 1.24.0
```

### nip explain

Explain resolution decisions:

```bash
# Explain why a package was resolved the way it was
nip explain nginx

# With USE flags
nip explain nginx --use-flags=ssl,http2

# JSON output
nip explain nginx --json

# Verbose output
nip explain nginx --verbose
```

**Output:**
```
📖 Explaining resolution for: nginx

Resolution explanation:
  • Package source: Official repository
  • Version selected: 1.24.0 (latest stable)
  • Variant: ssl+http2
  • Dependencies: 12 packages
  • Build hash: xxh3-abc123def456...

Dependency chain:
  nginx → openssl → zlib
       → pcre

Variant decisions:
  • features: ssl, http2 (requested)
  • libc: musl (default)
  • allocator: jemalloc (default)
```

### nip conflicts

Check for dependency conflicts:

```bash
# Check for conflicts in installed packages
nip conflicts

# Verbose output
nip conflicts --verbose

# JSON output
nip conflicts --json
```

**Output (no conflicts):**
```
🔍 Checking for dependency conflicts...

✅ No conflicts detected!

All installed packages are compatible.
```

**Output (with conflicts):**
```
🔍 Checking for dependency conflicts...

❌ Found 2 conflict(s)!

Conflict 1: VersionConflict
  Package 1: firefox 120.0
  Package 2: chromium 119.0
  Reason: Both require libssl but with incompatible versions
  Suggestions:
    • Install in separate NipCells
    • Update firefox to use compatible libssl version
    • Update chromium to use compatible libssl version

Conflict 2: VariantConflict
  Package 1: nginx (ssl+http2)
  Package 2: apache (ssl+http3)
  Reason: Conflicting SSL module versions
  Suggestions:
    • Use consistent SSL module versions
    • Install in separate NipCells
```

### nip variants

Show available variants:

```bash
# Show all available variants
nip variants nginx

# Show only installed variants
nip variants nginx --installed

# JSON output
nip variants nginx --json

# Verbose output
nip variants nginx --verbose
```

**Output:**
```
🎨 Available variants for: nginx

USE flags:
  • ssl - Enable SSL/TLS support
  • http2 - Enable HTTP/2 support
  • brotli - Enable Brotli compression
  • gzip - Enable gzip compression

libc options:
  • musl (default) - Lightweight C library
  • glibc - GNU C library

Allocator options:
  • jemalloc (default) - High-performance allocator
  • tcmalloc - Google's thread-caching allocator
  • default - System default allocator

Example usage:
  nip resolve nginx --use-flags=ssl,http2 --libc=musl
  nip resolve nginx --use-flags=wayland --allocator=jemalloc
```

---

## Resolving Conflicts

### Understanding Conflicts

A conflict occurs when:
- Two packages require incompatible versions of the same dependency
- Two packages have mutually exclusive features
- A package requires a feature that conflicts with another package

### Example Conflict

```bash
$ nip install firefox chromium

❌ Conflict detected:
   firefox requires: libssl >= 3.0
   chromium requires: libssl < 3.0
   
💡 Suggestions:
   • Install firefox and chromium in separate NipCells
   • Use firefox with libssl 3.0 (chromium not available)
   • Use chromium with libssl 2.8 (firefox not available)
```

### Resolving with NipCells

When conflicts are unresolvable, use NipCells for isolation:

```bash
# Create separate environments
nip cell create browser-firefox
nip cell create browser-chromium

# Install in separate cells
nip install --cell=browser-firefox firefox
nip install --cell=browser-chromium chromium

# Switch between cells
nip cell activate browser-firefox
# Now firefox is available

nip cell activate browser-chromium
# Now chromium is available
```

---

## Using Variants

### What Are Variants?

Variants are different configurations of the same package. For example, nginx can be built with:
- Different SSL libraries (OpenSSL, LibreSSL, BoringSSL)
- Different compression (gzip, brotli, zstd)
- Different modules (HTTP/2, HTTP/3, WebSocket)

### Viewing Available Variants

```bash
# See all available variants of a package
nip variants nginx

# Output:
# 🎨 Available variants for: nginx
# 
# USE flags:
#   • ssl - Enable SSL/TLS support
#   • http2 - Enable HTTP/2 support
#   • brotli - Enable Brotli compression
#   • gzip - Enable gzip compression
# 
# libc options:
#   • musl (default) - Lightweight C library
#   • glibc - GNU C library
# 
# Allocator options:
#   • jemalloc (default) - High-performance allocator
#   • tcmalloc - Google's thread-caching allocator
#   • default - System default allocator
```

### Resolving with Specific Variants

```bash
# Resolve with specific USE flags
nip resolve nginx --use-flags=ssl,http2

# Resolve with specific libc
nip resolve nginx --libc=musl

# Resolve with custom allocator
nip resolve nginx --allocator=jemalloc

# Combine multiple options
nip resolve nginx --use-flags=ssl,http2,brotli --libc=musl --allocator=jemalloc
```

### Installing Specific Variants

```bash
# Install with specific variant
nip install nginx:openssl-brotli

# Build custom variant
nip install nginx --build-from-source --with-http3 --with-brotli

# Use variant with specific libc
nip install nginx:musl-openssl-brotli
```

---

## NipCell Isolation

### When to Use NipCells

Use NipCells when:
- Packages have unresolvable conflicts
- You need multiple versions of the same package
- You want isolated development environments
- You need to test package combinations

### Creating and Using Cells

```bash
# Create a new cell
nip cell create dev-environment

# Install packages in the cell
nip install --cell=dev-environment gcc cmake ninja

# Activate the cell
nip cell activate dev-environment

# Now gcc, cmake, ninja are available
# Other packages from the main system are also available

# Deactivate (return to main system)
nip cell deactivate
```

### Managing Cells

```bash
# List all cells
nip cell list

# Show cell contents
nip cell show myenv

# Remove a cell
nip cell remove myenv

# Clone a cell
nip cell clone myenv myenv-backup

# Export cell for sharing
nip cell export myenv myenv.tar.gz
```

---

## Troubleshooting

### Common Issues

#### Issue: "Package not found"

```bash
$ nip install nonexistent-package

❌ Error: Package 'nonexistent-package' not found

💡 Solutions:
   • Check package name spelling
   • Update package lists: nip update
   • Search for similar packages: nip search nonexistent
   • Check if package is in enabled repositories
```

**Solution:**
```bash
# Update package lists
nip update

# Search for similar packages
nip search package-name

# Check enabled repositories
nip repo list
```

#### Issue: "Dependency conflict"

```bash
$ nip install package-a package-b

❌ Conflict: package-a requires lib-x >= 2.0
            package-b requires lib-x < 2.0

💡 Solutions:
   • Install in separate NipCells
   • Choose different versions
   • Check if newer versions are compatible
```

**Solution:**
```bash
# Use NipCells for isolation
nip cell create cell-a
nip install --cell=cell-a package-a

nip cell create cell-b
nip install --cell=cell-b package-b
```

#### Issue: "Build failure"

```bash
$ nip install --build-from-source custom-package

❌ Build failed: compilation error in module X

💡 Solutions:
   • Check build requirements are installed
   • Try binary package if available
   • Check build logs for details
   • Report issue with build logs
```

**Solution:**
```bash
# Try binary package first
nip install custom-package

# If binary not available, check build requirements
nip info custom-package --show-build-requirements

# View detailed build logs
nip install --build-from-source custom-package --verbose
```

### Getting Help

```bash
# Show help for a command
nip install --help

# Resolve dependencies to see what would be installed
nip resolve package-name

# Explain why a package was resolved the way it was
nip explain package-name

# Check for dependency conflicts
nip conflicts

# Show available variants for a package
nip variants package-name

# Show detailed information about a package
nip info package-name

# Show package dependencies
nip deps package-name

# Show reverse dependencies (what depends on this package)
nip rdeps package-name

# Check system health
nip doctor
```

---

## FAQ

### Q: How does NIP choose between multiple package sources?

**A:** NIP uses a priority system:
1. **Trust Level**: Trusted sources preferred
2. **Repository Priority**: Higher priority repos preferred
3. **Version**: Latest compatible version preferred
4. **Source Type**: Binary preferred over source (configurable)

### Q: Can I use packages from multiple repositories?

**A:** Yes! NIP automatically searches all enabled repositories and resolves conflicts intelligently.

```bash
# Enable multiple repositories
nip repo enable arch-linux
nip repo enable nix-packages
nip repo enable gentoo-portage

# NIP will search all three when resolving dependencies
```

### Q: How do I know if a package is safe to install?

**A:** Check package information:

```bash
# View package details
nip info package-name

# Check package signatures
nip verify package-name

# View package dependencies
nip deps package-name

# Check package source
nip show package-name --source
```

### Q: Can I install the same package in multiple versions?

**A:** Yes, using NipCells:

```bash
# Create cells for different versions
nip cell create python3.10
nip cell create python3.11

# Install different versions
nip install --cell=python3.10 python=3.10
nip install --cell=python3.11 python=3.11

# Switch between versions
nip cell activate python3.10  # Use Python 3.10
nip cell activate python3.11  # Use Python 3.11
```

---

## Performance

### Resolution Speed

| Scenario | Time |
|----------|------|
| Typical packages (10-20 deps) | ~50ms |
| Complex packages (50-100 deps) | ~200ms |
| Massive packages (200+ deps) | ~800ms |

### Optimization Tips

```bash
# Use binary packages (faster)
nip install nginx

# Enable caching
nip cache enable

# Use local mirrors
nip repo set-mirror https://local-mirror.example.com

# Parallel downloads
nip config set parallel-downloads 8
```

---

## Advanced Topics

### Build Hash Calculation

NIP uses deterministic build hashes to ensure reproducible builds:

```bash
# View build hash for a package
nip info nginx --show-build-hash

# Verify build hash
nip verify nginx --check-build-hash
```

### Variant Profiles

Variants are organized by domains (e.g., "ssl", "compression", "modules"):

```bash
# View variant domains
nip variants nginx --show-domains

# Compare variant configurations
nip variants nginx --compare
```

### Cache Management

```bash
# Show cache stats
nip cache stats

# Clear cache
nip cache clear

# Verify cache integrity
nip cache verify

# Rebuild cache
nip cache rebuild
```

---

## See Also

- [NIP Quick Reference](QUICK_REFERENCE.md) - Command cheat sheet
- [NIP Getting Started](getting-started.md) - Complete introduction
- [NIP Bootstrap Guide](bootstrap-guide.md) - Build tool management

---

**For more information, see the complete documentation in the docs/ directory.**