14 KiB

Raw Permalink Blame History

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

# 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

# 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

# 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

# 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:

# 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:

# 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:

# 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:

# 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:

# 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

$ 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:

# 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

# 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

# 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

# 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

# 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

# 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"

$ 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:

# Update package lists
nip update

# Search for similar packages
nip search package-name

# Check enabled repositories
nip repo list

Issue: "Dependency conflict"

$ 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:

# 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"

$ 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:

# 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

# 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:

Trust Level: Trusted sources preferred
Repository Priority: Higher priority repos preferred
Version: Latest compatible version preferred
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.

# 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:

# 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:

# 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

# 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:

# 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"):

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

# Compare variant configurations
nip variants nginx --compare

Cache Management

# Show cache stats
nip cache stats

# Clear cache
nip cache clear

# Verify cache integrity
nip cache verify

# Rebuild cache
nip cache rebuild

14 KiB Raw Permalink Blame History

NIP Dependency Resolution System

Overview

Key Features

Quick Start

Installing a Single Package

Installing Multiple Packages

Resolving Dependencies Without Installing

Viewing the Installation Plan

Understanding Dependencies

Dependency Types

Version Constraints

CLI Commands

nip resolve

nip explain

nip conflicts

nip variants

Resolving Conflicts

Understanding Conflicts

Example Conflict

Resolving with NipCells

Using Variants

What Are Variants?

Viewing Available Variants

Resolving with Specific Variants

Installing Specific Variants

NipCell Isolation

When to Use NipCells

Creating and Using Cells

Managing Cells

Troubleshooting

Common Issues

Issue: "Package not found"

Issue: "Dependency conflict"

Issue: "Build failure"

Getting Help

FAQ

Q: How does NIP choose between multiple package sources?

Q: Can I use packages from multiple repositories?

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

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

Performance

Resolution Speed

Optimization Tips

Advanced Topics

Build Hash Calculation

Variant Profiles

Cache Management

See Also

14 KiB

Raw Permalink Blame History