718 lines
14 KiB
Markdown
718 lines
14 KiB
Markdown
# 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.**
|