nip/docs/gentoo-nix-guide.md

Using Nix Packages on Gentoo

Overview

This guide shows Gentoo users how to use NIP to access Nix's vast package repository while keeping their Gentoo system intact. This is perfect for:

• Accessing packages not in Portage
• Getting newer versions of software
• Testing packages before creating ebuilds
• Using binary packages for faster installation

Why Use Nix on Gentoo?

Advantages:

• ✅ Access to 80,000+ packages from Nixpkgs
• ✅ Binary packages (no compilation needed)
• ✅ Isolated installation (no conflicts with Portage)
• ✅ Multiple versions of the same package
• ✅ Reproducible builds
• ✅ Easy rollback

NIP Integration:

• ✅ Automatic Nix installation
• ✅ Clean GoboLinux-style organization
• ✅ Unified /System/Links/ for all packages
• ✅ Works alongside Portage seamlessly

Quick Start

1. Install NIP

# Clone repository
git clone https://git.maiwald.work/Nexus/NexusToolKit
cd NexusToolKit/nip

# Build and install
./build.sh
sudo ./install.sh

2. Install Your First Nix Package

# NIP will automatically offer to install Nix if needed
nip install firefox --source=nix

# Or explicitly install Nix first
nip bootstrap install nix

3. Verify Installation

# Check Nix is installed
nip bootstrap list

# Check Firefox is installed
nip list
which firefox

Automatic Nix Installation

When you try to install a Nix package, NIP automatically detects if Nix is missing and offers installation options:

$ nip install firefox --source=nix

⚠️  Nix not found

NIP can help you set up Nix:

1. 🚀 Install minimal Nix via NIP (recommended)
   • Lightweight standalone nix-build binary
   • Minimal Nix store
   • ~50MB download, ~100MB installed
   • Isolated in ~/.nip/bootstrap/nix/

2. 📦 Use containerized environment
   • Requires Podman/Docker
   • Completely isolated builds
   • ~200MB download

3. 🔧 Install full Nix manually
   • Follow: https://nixos.org/download.html

4. 🔄 Try a different source
   • nip install firefox --source=gentoo

Choose option (1-4) or 'q' to quit: 1

📦 Installing minimal Nix...
✅ Nix installed successfully

📦 Installing firefox from Nix...
✅ firefox installed to /Programs/Firefox/120.0/

Installation Methods

Method 1: Minimal Nix (Recommended)

Best for: Most Gentoo users

nip bootstrap install nix

What you get:

• Standalone nix-build binary
• Minimal Nix store
• Installed to ~/.nip/bootstrap/nix/
• No system modifications
• ~100MB total

Advantages:

• ✅ Quick installation
• ✅ No conflicts with Portage
• ✅ Easy to remove
• ✅ Sufficient for most packages

Method 2: Container-Based

Best for: Maximum isolation

# Install Podman
emerge --ask app-containers/podman

# Use container for Nix packages
nip install firefox --source=nix --container

Advantages:

• ✅ Complete isolation
• ✅ No Nix installation needed
• ✅ Rootless with Podman
• ✅ Clean host system

Method 3: Full Nix Installation

Best for: Heavy Nix users

# Install Nix manually
curl -L https://nixos.org/nix/install | sh

# Use with NIP
nip install firefox --source=nix

Advantages:

• ✅ Full Nix functionality
• ✅ Access to all Nix features
• ✅ Can use nix-shell, nix-env, etc.

Common Workflows

Installing Binary Packages

# Install from Nix (binary, fast)
nip install firefox --source=nix
nip install vscode --source=nix
nip install chromium --source=nix

# List installed packages
nip list

Building from Source

# Build from Gentoo (source, customizable)
nip build vim +python+ruby --source=gentoo

# Build from Nix (source, reproducible)
nip build vim --source=nix

Mixing Sources

# System packages from Portage
emerge --ask dev-lang/python

# Development tools from Nix
nip install nodejs --source=nix
nip install rust --source=nix

# Custom builds from Gentoo
nip build ffmpeg +vaapi+lto --source=gentoo

Testing Packages

# Try a package from Nix before creating an ebuild
nip install some-new-tool --source=nix

# If you like it, keep it or create an ebuild
# If not, easily remove it
nip remove some-new-tool

Package Management

Installing Packages

# Install from Nix
nip install <package> --source=nix

# Install specific version (if available)
nip install firefox@120.0 --source=nix

# Install multiple packages
nip install firefox chromium vscode --source=nix

Listing Packages

# List all installed packages
nip list

# List only Nix packages
nip list --source=nix

# Show package details
nip info firefox

Removing Packages

# Remove a package
sudo nip remove firefox

# Remove multiple packages
sudo nip remove firefox chromium vscode

Updating Packages

# Update a package
nip update firefox --source=nix

# Update all packages
nip update --all

Integration with Portage

Coexistence

NIP and Portage work together seamlessly:

# Portage packages go to /usr
emerge --ask firefox

# NIP packages go to /Programs
nip install firefox --source=nix

# Both are accessible via PATH
which firefox  # Shows /System/Links/Executables/firefox

Priority

By default, NIP packages take priority in PATH:

PATH=/System/Links/Executables:/usr/bin:...

To prefer Portage packages, adjust your PATH in ~/.bashrc:

export PATH=/usr/bin:/System/Links/Executables:$PATH

Checking Sources

# See where a package comes from
nip info firefox

# List all sources
nip sources

Directory Structure

/Programs/                          # NIP packages
  ├── Firefox/120.0/                # From Nix
  ├── VSCode/1.85.0/                # From Nix
  └── Vim/9.0/                      # From Gentoo build

/System/Links/                      # Unified symlinks
  ├── Executables/
  │   ├── firefox -> /Programs/Firefox/120.0/bin/firefox
  │   ├── code -> /Programs/VSCode/1.85.0/bin/code
  │   └── vim -> /Programs/Vim/9.0/bin/vim
  ├── Libraries/
  └── Headers/

~/.nip/bootstrap/nix/               # Minimal Nix installation
  ├── bin/nix-build
  ├── store/
  └── config/

/var/nip/                           # NIP data
  ├── cas/                          # Content-addressable storage
  ├── cache/                        # Download cache
  └── db/packages.json              # Package database

Configuration

User Configuration

Edit ~/.nip/config:

# Prefer Nix for binary packages
default-source = "nix"

# Bootstrap preferences
bootstrap-auto-install = true
bootstrap-preferred-method = "recipe"

# Nix-specific settings
nix-binary-cache = true
nix-substituters = "https://cache.nixos.org"

System Configuration

Edit /etc/nip/nip.conf (requires root):

# System-wide settings
programs-dir = "/Programs"
links-dir = "/System/Links"

# Source priorities (lower = tried first)
nix-priority = 10
gentoo-priority = 20

Advanced Usage

Using Nix Channels

# Update Nix channel
nix-channel --update

# List available packages
nix-env -qaP | grep firefox

# Install via nix-env (alternative to NIP)
nix-env -iA nixpkgs.firefox

Nix Expressions

# Build from Nix expression
nip build --source=nix --expr '(import <nixpkgs> {}).firefox'

# Use custom Nix file
nip build --source=nix --file ./my-package.nix

Binary Caching

# Enable binary cache
nip config set nix-binary-cache true

# Use custom cache
nip config set nix-substituters "https://cache.nixos.org https://my-cache.example.com"

Troubleshooting

Nix Not Found

# Check if Nix is installed
nip bootstrap list

# Install Nix
nip bootstrap install nix

# Verify installation
nip bootstrap info nix

Package Not Found

# Update Nix channel
nix-channel --update

# Search for package
nix-env -qaP | grep <package>

# Try different package name
nip install <alternative-name> --source=nix

Permission Issues

# Most operations need root
sudo nip install firefox --source=nix

# Check permissions
ls -la /Programs
ls -la /System/Links

Conflicts with Portage

# Check which package is active
which firefox
nip info firefox

# Remove NIP version if needed
sudo nip remove firefox

# Or remove Portage version
sudo emerge --unmerge firefox

Nix Store Issues

# Check Nix store
nix-store --verify --check-contents

# Repair Nix store
nix-store --repair-path /nix/store/...

# Clean up old packages
nix-collect-garbage

Performance Tips

Use Binary Packages

# Nix provides pre-built binaries
nip install firefox --source=nix  # Fast, binary
nip build firefox --source=gentoo  # Slow, source

Enable Caching

# Enable NIP's binary cache
nip config set binary-cache true

# Enable Nix's binary cache
nip config set nix-binary-cache true

Parallel Operations

# Install multiple packages in parallel
nip install firefox chromium vscode --source=nix --parallel

Security Considerations

Verification

# NIP verifies all downloads with Blake2b checksums
# Nix verifies packages with cryptographic signatures

# Check package integrity
nip verify firefox

Isolation

# Minimal Nix installation is isolated
ls ~/.nip/bootstrap/nix/

# Container builds provide additional isolation
nip install firefox --source=nix --container

Updates

# Keep Nix updated
nip bootstrap update nix

# Update packages
nip update --all --source=nix

Comparison: Portage vs Nix

Feature	Portage	Nix (via NIP)
Package Count	~20,000	~80,000
Installation	Source	Binary
Speed	Slow	Fast
Customization	High (USE flags)	Medium
Reproducibility	Medium	High
Rollback	Limited	Easy
Isolation	System-wide	Per-package
Disk Usage	Lower	Higher

Best Practice: Use both!

• Portage for system packages and custom builds
• Nix for quick binary installations and testing

Migration Guide

From Pure Gentoo

# Keep using Portage for system packages
emerge --ask @world

# Add Nix for additional packages
nip install firefox vscode --source=nix

# Gradually migrate packages as needed

From NixOS

# Install NIP on Gentoo
./build.sh && sudo ./install.sh

# Import your Nix packages
nip import-nix-profile

# Continue using familiar Nix commands
nix-env -iA nixpkgs.firefox

Best Practices

1. Use Portage for System Packages

# System essentials via Portage
emerge --ask sys-kernel/gentoo-sources
emerge --ask sys-apps/systemd

2. Use Nix for User Applications

# User applications via Nix
nip install firefox chromium vscode --source=nix

3. Use Gentoo Builds for Optimization

# Performance-critical apps with custom flags
nip build ffmpeg +vaapi+lto+cpu-native --source=gentoo

4. Keep Both Updated

# Update Portage
emerge --sync
emerge --update --deep --newuse @world

# Update Nix
nip bootstrap update nix
nip update --all --source=nix

Examples

Development Environment

# System compiler from Portage
emerge --ask sys-devel/gcc

# Development tools from Nix
nip install nodejs rust python --source=nix

# IDE from Nix
nip install vscode --source=nix

Media Workstation

# Optimized media tools from Gentoo
nip build ffmpeg +vaapi+lto --source=gentoo
nip build obs-studio +pipewire --source=gentoo

# Additional tools from Nix
nip install gimp inkscape --source=nix

Server Setup

# Core services from Portage
emerge --ask nginx postgresql

# Additional services from Nix
nip install grafana prometheus --source=nix

Getting Help

Documentation

• NIP Documentation
• Bootstrap Guide
• Nix Manual

Commands

# NIP help
nip --help
nip bootstrap --help

# Nix help
nix-env --help
nix-build --help

Support

• Issues: https://git.maiwald.work/Nexus/NexusToolKit/issues
• Wiki: https://git.maiwald.work/Nexus/NexusToolKit/wiki

Summary

Using Nix on Gentoo via NIP gives you:

✅ Best of both worlds - Portage's customization + Nix's convenience ✅ 80,000+ packages - Access to Nixpkgs repository ✅ Fast installation - Binary packages, no compilation ✅ Clean integration - No conflicts with Portage ✅ Easy management - Simple NIP commands ✅ Automatic setup - NIP handles Nix installation

Get started:

nip install firefox --source=nix

That's it! NIP handles everything else automatically.