nexus
/
nip
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
nip/docs/build-examples.md

10 KiB
Raw Permalink Blame History

NIP Build System - Examples

Basic Examples

Simple Build

Build a package with default settings:

nip build bash

Build with Single Variant

nip build firefox +wayland

Build with Multiple Variants

nip build firefox +wayland +lto +pipewire

Source Selection Examples

Auto-Detect Source (Default)

nip build nginx

NIP automatically selects the best available source (priority: Nix > PKGSRC > Gentoo).

Specify Source System

# Use Nix
nip build firefox --source=nix

# Use PKGSRC
nip build nginx --source=pkgsrc

# Use Gentoo
nip build vim --source=gentoo

Variant Examples

Graphics Variants

# Wayland support
nip build firefox +wayland

# X11 support
nip build firefox +X

# Vulkan graphics
nip build mesa +vulkan

# Multiple graphics options
nip build firefox +wayland +vulkan

Audio Variants

# PipeWire audio
nip build firefox +pipewire

# PulseAudio
nip build firefox +pulseaudio

# ALSA
nip build mpd +alsa

# Multiple audio options
nip build firefox +pipewire +alsa

Optimization Variants

# Link-time optimization
nip build firefox +lto

# Profile-guided optimization
nip build gcc +pgo

# Both optimizations
nip build firefox +lto +pgo

Security Variants

# Position-independent executable
nip build nginx +pie

# Full hardening
nip build openssh +hardened

# Multiple security options
nip build nginx +pie +hardened

Combined Variants

# Modern desktop application
nip build firefox +wayland +vulkan +pipewire +lto +pie

# Optimized server
nip build nginx +lto +pie +hardened

# Development tools
nip build gcc +lto +pgo

Advanced Options

Verbose Mode

See detailed build output:

nip build firefox +wayland --verbose

Force Rebuild

Skip cache and rebuild from scratch:

nip build firefox +wayland --rebuild

Build Without Installing

Build but don't install (useful for testing):

nip build test-package --no-install

Keep Work Files

Keep intermediate build files for debugging:

nip build firefox --keep-work

Parallel Jobs

Specify number of parallel build jobs:

nip build firefox --jobs=8

Combined Advanced Options

nip build firefox +wayland +lto --verbose --rebuild --jobs=8

Package Discovery Examples

List All Sources

nip sources

Output:

📚 Available Package Sources (by priority):

1. 🔵 Nix (nixpkgs)
   Status: ✅ Available
   Packages: ~100,000+

2. 🟢 PKGSRC (NetBSD)
   Status: ❌ Not installed
   Install: https://www.pkgsrc.org/

3. 🟣 Gentoo Portage
   Status: ❌ Not installed
   Install: https://www.gentoo.org/

Search for Package

# Search for bash
nip sources bash

# Search for firefox
nip sources firefox

# Search for nginx
nip sources nginx

Cache Management Examples

View Cache Statistics

nip cache stats

Output:

📊 Build Cache Statistics

Cached Builds: 15
Total Size: 2.3 MB
Cache Directory: /home/user/.cache/nip/builds

Retention Policy: 30 days

Clean Old Builds

Remove builds older than 30 days:

nip cache clean

Clear All Cache

Remove all cached builds:

nip cache clear

Real-World Scenarios

Scenario 1: Modern Desktop Browser

Build Firefox with modern desktop features:

nip build firefox +wayland +vulkan +pipewire +lto

This enables:

  • Wayland display server (native Wayland, no XWayland)
  • Vulkan graphics acceleration
  • PipeWire audio (modern audio server)
  • Link-time optimization (better performance)

Scenario 2: Optimized Web Server

Build NGINX with security and performance:

nip build nginx +lto +pie +hardened --source=nix

This enables:

  • Link-time optimization (better performance)
  • Position-independent executable (security)
  • Full hardening (additional security measures)
  • Uses Nix for reproducible builds

Scenario 3: Development Environment

Build GCC with optimizations:

nip build gcc +lto +pgo

This enables:

  • Link-time optimization
  • Profile-guided optimization (best performance)

Scenario 4: Multimedia Workstation

Build media applications with full codec support:

# Video player with hardware acceleration
nip build mpv +wayland +vulkan +pipewire

# Audio workstation
nip build ardour +pipewire +lto

# Image editor
nip build gimp +wayland

Scenario 5: Server Infrastructure

Build server components with security focus:

# Web server
nip build nginx +pie +hardened +lto

# Database
nip build postgresql +pie +hardened

# SSH server
nip build openssh +hardened

Scenario 6: Testing Different Configurations

Test a package with different variants:

# Test with Wayland
nip build firefox +wayland --no-install

# Test with X11
nip build firefox +X --no-install

# Choose the one that works best
nip build firefox +wayland

Scenario 7: Cross-Source Comparison

Try the same package from different sources:

# Build from Nix
nip build vim --source=nix

# Build from PKGSRC
nip build vim --source=pkgsrc

# Build from Gentoo
nip build vim --source=gentoo

Scenario 8: Debugging Build Issues

Debug a failing build:

# First attempt
nip build problematic-package +feature

# If it fails, try verbose mode
nip build problematic-package +feature --verbose

# Try without variants
nip build problematic-package --verbose

# Try different source
nip build problematic-package --source=nix --verbose

# Keep work files for inspection
nip build problematic-package --keep-work --verbose

Package-Specific Examples

Web Browsers

# Firefox - Modern desktop
nip build firefox +wayland +vulkan +pipewire +lto

# Chromium - X11 with optimizations
nip build chromium +X +lto

# Brave - Wayland
nip build brave +wayland +pipewire

Web Servers

# NGINX - Optimized and hardened
nip build nginx +lto +pie +hardened

# Apache - With SSL
nip build apache +ssl +lto

# Caddy - Modern web server
nip build caddy +lto

Development Tools

# GCC - Optimized compiler
nip build gcc +lto +pgo

# LLVM/Clang - With all targets
nip build llvm +lto

# Rust - Optimized
nip build rust +lto

Text Editors

# Vim - Full features
nip build vim +X +python +ruby +lto

# Emacs - Wayland native
nip build emacs +wayland +lto

# Neovim - Optimized
nip build neovim +lto

Multimedia Applications

# VLC - Full codec support
nip build vlc +wayland +pipewire

# MPV - Hardware acceleration
nip build mpv +wayland +vulkan +pipewire

# Blender - Optimized
nip build blender +wayland +vulkan +lto

System Utilities

# Bash - Optimized shell
nip build bash +lto

# Coreutils - Optimized
nip build coreutils +lto

# Git - With all features
nip build git +lto

Workflow Examples

Daily Development Workflow

# Morning: Update and build tools
nip sources
nip build gcc +lto +pgo
nip build rust +lto

# During development: Build dependencies
nip build libfoo +lto
nip build libbar +wayland

# Testing: Build without installing
nip build myproject --no-install

# Final: Build and install
nip build myproject +lto

System Setup Workflow

# 1. Check available sources
nip sources

# 2. Build essential tools
nip build bash +lto
nip build coreutils +lto
nip build git +lto

# 3. Build desktop environment
nip build sway +wayland
nip build waybar +wayland

# 4. Build applications
nip build firefox +wayland +vulkan +pipewire +lto
nip build alacritty +wayland

# 5. Check cache
nip cache stats

Maintenance Workflow

# Weekly: Clean old builds
nip cache clean

# Monthly: Review cache
nip cache stats

# As needed: Clear cache
nip cache clear

# Rebuild important packages
nip build firefox +wayland +lto --rebuild

Tips and Tricks

Tip 1: Use Cache Effectively

# First build (slow)
nip build firefox +wayland +lto

# Subsequent builds (instant)
nip build firefox +wayland +lto

Tip 2: Test Before Installing

# Test configuration
nip build mypackage +experimental --no-install

# If successful, install
nip build mypackage +experimental

Tip 3: Combine with Other NIP Commands

# Build and verify
nip build firefox +wayland
nip verify firefox

# Build and list
nip build bash +lto
nip list | grep bash

Tip 4: Use Verbose for Learning

# See exactly what NIP does
nip build firefox +wayland --verbose

This shows:

  • Source detection
  • Variant translation
  • Build commands
  • Grafting process
  • Symlink creation

Tip 5: Parallel Builds for Speed

# Use all CPU cores
nip build firefox --jobs=$(nproc)

# Or specify number
nip build firefox --jobs=8

Common Patterns

Pattern 1: Build with Defaults, Add Variants Later

# Start simple
nip build firefox

# Add variants incrementally
nip build firefox +wayland
nip build firefox +wayland +lto
nip build firefox +wayland +lto +pipewire

Pattern 2: Try Multiple Sources

# Try each source
for source in nix pkgsrc gentoo; do
    nip build mypackage --source=$source --no-install
done

Pattern 3: Batch Build

# Build multiple packages
for pkg in bash vim git; do
    nip build $pkg +lto
done

Pattern 4: Conditional Variants

# Desktop system
if [ "$DESKTOP" = "wayland" ]; then
    nip build firefox +wayland +vulkan +pipewire
else
    nip build firefox +X +pulseaudio
fi

Quick Reference

Most Common Commands

# Basic build
nip build <package>

# Build with variants
nip build <package> +variant1 +variant2

# Specify source
nip build <package> --source=nix

# Verbose mode
nip build <package> --verbose

# Force rebuild
nip build <package> --rebuild

# Search for package
nip sources <package>

# Cache management
nip cache stats
nip cache clean
nip cache clear

Most Common Variants

+wayland    # Wayland display server
+X          # X11 display server
+vulkan     # Vulkan graphics
+pipewire   # PipeWire audio
+pulseaudio # PulseAudio
+lto        # Link-time optimization
+pie        # Position-independent executable
+hardened   # Full hardening

See Also

  • User Guide: source-build-guide.md
  • Help Reference: build-system-help.md
  • Configuration: build-configuration.md
  • Troubleshooting: build-troubleshooting.md

Happy building! 🚀