ocelot-project / nix-modeline

Emacs minor mode that displays background Nix instantiations; useful as a UI for lorri and nix-direnv

nix-modeline - live Nix builder status in your Emacs modeline

nix-modeline is an Emacs minor mode that displays how many Nix instantiations are in progress on your modeline. It’s very useful for lorri and nix-direnv users as a UI for which projects are building in the background, and fills in for both Nix and lorri’s lack of a stable event notification API. For CPU and power efficency, nix-modeline relies on Emacs’ built-in filenotify library to monitor Nix, which lets it sleep until the instant a Nix operation begins or ends.

Compatibility

nix-modeline is compatible with any Linux system running Nix including NixOS, as well as macOS. It may work under Windows Subsystem for Linux, but your mileage will vary. The nix-modeline-process-counter variable is worth looking at when running on an unsupported operating system.

Installation

Declarative Install

• Modify your Nix configuration to pull in the nix-modeline overlay (for better expression caching, replace master in the URL with the latest commit in this repo, and add a valid sha256 attribute under that):

nixpkgs.overlays = [
  (import (builtins.fetchTarball {
    url = "https://github.com/ocelot-project/nix-modeline/archive/master.tar.gz";
  }))
];

• After that, override your emacs derivation with one that pulls in the nix-modeline package. For example, in /etc/nixos/configuration.nix on a NixOS system:

environment.systemPackages = [
  # Replace any existing emacs derivation with:
  (pkgs.emacsPackagesGen pkgs.emacs).emacsWithPackages (epkgs: [
    pkgs.nix-modeline
  ])
];

Imperative Install

From MELPA

nix-modeline is available on MELPA. If MELPA is part of your configured package-archives, installing should be as simple as choosing nix-modeline in the list-packages interface. Note that Emacs distributions like Doom, Spacemacs, and Prelude will be configured to use MELPA, but generally have their own way of configuring packages. See your distro’s manual for information.

From Github

• First, clone nix-modeline:

git clone https://github.com/ocelot-project/nix-modeline.git

• Then add the directory containing nix-modeline to your Emacs load-path:

(push "/path/to/nix-modeline" load-path)

• Note that Emacs distros like Doom, Spacemacs, and Prelude have their own way to install packages. See your distro’s manual for information.

Usage

• For plain Emacs, just (require 'nix-modeline) and execute (nix-modeline-mode) to enable the minor mode.
• Doom, Spacemacs, Prelude, and other Emacs distros have more efficient ways to pull in nix-modeline. See your distro’s manual on how to configure packages.

Configuration

nix-modeline has a lot of configuration options. See the `defcustom` expressions in `nix-modeline.el` for a complete list. Some of the most important options are:

Option	Description
nix-modeline-*-text	Change the modeline text for a given Nix state
nix-modeline-*-face	Change the modeline text color for a given Nix state

FAQ

How can I hide nix-modeline when Nix is idle?

Set nix-modeline-idle-text to ~”“~, and Emacs won’t render nix-modeline when Nix isn’t doing anything.

I’m not seeing builds for other users or nixos-rebuild switch

By default, nix-modeline only shows your Nix processes. To change that, set nix-modeline-users to either ~’self-and-root~ (which will include nixos-rebuild switch and other root-owned Nix processes) or ~’all~.

Can I tap into nix-modeline’s event stream?

You can! Use nix-modeline-hook, which runs whenever a Nix operation begins or ends. Note that this hook only works when nix-modeline is enabled.

Is there any way to monitor specific projects, or know what’s building?

Unfortunately not. Nix, lorri, and direnv all lack a stable event stream I can tap into, as well as any usable standardized operation logs. If there’s enough popular demand for the feature, getting an event stream implemented in Nix isn’t out of the realm of possibility.

The text that nix-modeline displays looks weird.

The default text that nix-modeline displays uses Unicode characters that your Emacs font might not support. The variables used to control this text look like nix-modeline-*-text; change their value to a string that doesn’t contain Unicode chraracters, and toggle nix-modeline off and on again.

I like this idea, but I don’t use Emacs.

That’s a shame. Previous iterations of nix-modeline utilized a shell scripting oriented approach, based around ~entr~:

while [ true ]; do
    echo /nix/var/nix/db/db.sqlite | entr -dns "sleep 0.025; pgrep -U $(id -u)";
done

This should be portable to other editors like vim and vscode, or to tools that support displaying the output of a shell script as a widget.