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

```bash
# 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

```bash
# 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

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

```bash
$ 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

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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

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

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

### Mixing Sources

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# List all installed packages
nip list

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

# Show package details
nip info firefox
```

### Removing Packages

```bash
# Remove a package
sudo nip remove firefox

# Remove multiple packages
sudo nip remove firefox chromium vscode
```

### Updating Packages

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

# Update all packages
nip update --all
```

## Integration with Portage

### Coexistence

NIP and Portage work together seamlessly:

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

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

### Checking Sources

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Check if Nix is installed
nip bootstrap list

# Install Nix
nip bootstrap install nix

# Verify installation
nip bootstrap info nix
```

### Package Not Found

```bash
# 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

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

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

### Conflicts with Portage

```bash
# 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

```bash
# 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

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

### Enable Caching

```bash
# 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

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

## Security Considerations

### Verification

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

# Check package integrity
nip verify firefox
```

### Isolation

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

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

### Updates

```bash
# 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

```bash
# 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

```bash
# 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

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

### 2. Use Nix for User Applications

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

### 3. Use Gentoo Builds for Optimization

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

### 4. Keep Both Updated

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

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

## Examples

### Development Environment

```bash
# 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

```bash
# 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

```bash
# Core services from Portage
emerge --ask nginx postgresql

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

## Getting Help

### Documentation

- [NIP Documentation](../README.md)
- [Bootstrap Guide](bootstrap-guide.md)
- [Nix Manual](https://nixos.org/manual/nix/stable/)

### Commands

```bash
# 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:**
```bash
nip install firefox --source=nix
```

That's it! NIP handles everything else automatically.