• Working with Nixpkgs Locally: Benefits and Best Practices
• I. Why Work with Nixpkgs Locally?
  • A. Faster Development Cycle
  • B. Enhanced Version Control
  • C. Flexible Debugging Capabilities
  • D. Streamlined Contribution Workflow
  • E. Up-to-Date Documentation Source
  • F. Optimized Storage and Performance
• II. Flake vs. Non-Flake Syntax for Local Nixpkgs
  • A. Flake Syntax (nix build .#<package>)
  • B. Non-Flake Syntax (nix-build -f . <package> or nix build -f . <package>)
  • III. Setting Up a Local Nixpkgs Repository Efficiently
  • A.a Initial Clone: Shallow Cloning
  • A.b A few Examples exploring Nixpkgs
  • A.1 Full Fork and Clone of Nixpkgs
  • B. Managing Branches with Worktrees
• IV. Debugging Missing Dependencies: A Practical Example
  • A. Online Search with search.nixos.org
  • B. Local Source Code Search with rg (ripgrep)
• V. Local Derivation Search with nix-locate
• VI. Key Benefits of Working with Nixpkgs Locally (Recap)
• VII. Best Practices and Tips from the Community

• Cloning Nixpkgs requires careful consideration due to its size.

A.a Initial Clone: Shallow Cloning

It is common to place your local clone in the /src directory:

mkdir src && cd src

❗ Warning, A shallow clone (--depth 1) is not recommended for general development or contributing changes back to Nixpkgs via pull requests. It's primarily suitable for:

• Quick checks or builds: If you only need to verify a package's current state or build a specific version without needing historical context.
• CI/CD environments: Where disk space and clone time are critical, and only the latest commit is needed for automated tests or builds.

With that said, to avoid downloading the entire history, perform a shallow clone:

git clone [https://github.com/NixOS/nixpkgs](https://github.com/NixOS/nixpkgs) --depth 1
cd nixpkgs

A.b A few Examples exploring Nixpkgs

While in the nixpkgs directory, you can check the version of a package:

nix-instantiate --eval -A openssl.version
"3.4.1"

Or to directly edit the file you can use nix edit:

nix edit nixpkgs#openssl

It uses the nix registry and openssl.meta.position to locate the file.

man nix3 registry

The above command will open the openssl/default.nix in your $EDITOR.

A.1 Full Fork and Clone of Nixpkgs

If you want to contribute to Nixpkgs, you need to set up a local version following the Contributing guide

You'll need to, this is directly from the Contributing.md:

1. Fork the Nixpkgs repository

2. Clone the forked repo into a local nixpkgs directory.

3. Configure the upstream Nixpkgs repo

B. Managing Branches with Worktrees

• Use Git worktrees to manage different branches efficiently:

  git fetch --all --prune --depth=1
  git worktree add -b nixos-unstable nixos-unstable # For just unstable
  

• Explanation of git worktree: Allows multiple working directories attached to the same .git directory, sharing history and objects but with separate checked-out files.

• git worktree add: Creates a new working directory for the specified branch (nixos-unstable in this case).

• Let's say you're trying to build icat locally and encounter a missing dependency error:

nix-build -A icat
# ... (Error log showing "fatal error: X11/Xlib.h: No such file or directory")

• The error fatal error: X11/Xlib.h: No such file or directory indicates a missing X11 dependency.

A. Online Search with search.nixos.org

• The Nixpkgs package search website (https://search.nixos.org/packages) is a valuable first step.
• However, broad terms like "x11" can yield many irrelevant results.
• Tip: Utilize the left sidebar to filter by package sets (e.g., "xorg").

B. Local Source Code Search with rg (ripgrep)

• Familiarity with searching the Nixpkgs source code is crucial for finding dependencies.

• Navigate to your local nixpkgs/ directory and use rg:

  rg "x11 =" pkgs # Case-sensitive search
  

  Output:

  pkgs/tools/X11/primus/default.nix
  21:  primus = if useNvidia then primusLib_ else primusLib_.override { nvidia_x11 = null; };
  22:  primus_i686 = if useNvidia then primusLib_i686_ else primusLib_i686_.override { nvidia_x11 = null; };
  
  pkgs/applications/graphics/imv/default.nix
  38:    x11 = [ libGLU xorg.libxcb xorg.libX11 ];
  

• Refining the search (case-insensitive):

  rg -i "libx11 =" pkgs
  

  Output:

  # ... (Output showing "xorg.libX11")
  

• The key result is xorg.libX11, which is likely the missing dependency.

• nix-locate (from the nix-index package) allows searching for derivations on the command line.

  Note: Install nix-index and run nix-index to create the initial index.

  nix-locate libx11
  # ... (Output showing paths related to libx11)
  

• Combining online and local search tools (search.nixos.org, rg, nix-locate) provides a comprehensive approach to finding dependencies.

• Rebasing over Merging: Never merge upstream changes into your local branch. Always rebase your branch onto the upstream (e.g., master or nixos-unstable) to avoid accidental large-scale pings in pull requests (Tip from soulsssx3 on Reddit).

• Tip from ElvishJErrico: Avoid using Nixpkgs directly as a flake for local development due to slow copying to /nix/store and performance issues with garbage collection on large numbers of small files. Use nix build -f . <package> instead of nix build .#<package>.

• Edge Cases for Flake Syntax: Flake syntax might be necessary in specific scenarios, such as NixOS installer tests where copying the Git history should be avoided.

• Base Changes on nixos-unstable: For better binary cache hits, base your changes on the nixos-unstable branch instead of master. Consider the merge-base for staging branches as well.

• Consider jujutsu: Explore jj-vcs, a Git-compatible alternative that can offer a more intuitive workflow, especially for large monorepos like Nixpkgs. While it has a learning curve, it can significantly improve parallel work and branch management.

• Intro-To-Jujutsu