SUNix (Software Updates for Nix)

A small GTK4 layer-shell popup for Wayland compositors that support wlr-layer-shell. It shows the expected changes before a NixOS or Home Manager switch is applied, using dix under the hood. Build plans are also supported (nix build --dry-run) to avoid full builds.

sunix.mp4

Install

Add the corresponding input to your Nix flake (recommended).

{
  inputs.sunix.url = "github:gvolpe/sunix";
}

And either use the provided Home Manager module:

modules = [ inputs.sunix.homeModules.default ];

{
  programs.sunix = {
    enable = true;
    settings = {
      dixBinary = "${pkgs.dix}/bin/dix";
      flakeDir = "$HOME/workspace/sxm-flake";
      homeFlake = "niri";
      nixosFlake = "aorus";
      styleCss = null;
      showDemo = false;
      enableBuildPlans = true;
    };
  };
}

Or use the package directly:

environment.systemPackages = [ inputs.sunix.packages.${system}.default ];

Alternatively, it can also be installed via cargo install sunix (if that's preferable for some reason).

Usage

SUNix can be fully used via the following keyboard shortcuts:

• M: build or show the Home Manager report.
• N: build or show the NixOS report.
• Shift+M / Shift+N: preview the Home Manager / NixOS build plan when enable_build_plans=true.
• D: show the bundled Demo report when show_demo=true.
• Up / K: scroll up in the active report or error output.
• Down / J: scroll down in the active report or error output.
• E: open the report export menu when a non-empty report is visible.
  • Alt+P / Alt+M: export the visible report as PDF or Markdown from the export menu.
• Left or H: go back from a report or error screen.
• Esc: close the popup.

Reports are cached during the same SUNix session, so reports aren't re-evaluated unless the program is restarted.

Build plans are disabled by default. Set enable_build_plans=true in sunix.toml, or programs.sunix.settings.enableBuildPlans = true in Home Manager, to reveal a Build plan button under each configuration and enable the plan shortcuts. This UI-only preview runs nix build --dry-run with the same nixpkgs override as the full report, showing derivations to build, paths to download, and download/unpacked size estimates. It includes build dependencies and omits paths already available locally; it is a quick option to avoid full builds. Plans are evaluated on each opening and can be refreshed. Use Full report to build the generation and view its package changes (or reopen its cached report).

Exports

SUNix reports can be exported as a PDF file or Markdown file. The latter is particularly useful to share on Pull Requests, e.g. gvolpe/nix-config#334.

The SUNix cli can also format dix --output=json into markdown directly from stdin:

dix --output=json /path1 /path2 \
  | sunix --markdown-report "NixOS .#flake"

PDF reports are also supported by the cli:

dix --output=json /path1 /path2 \
  | sunix --pdf-report "NixOS .#flake" > sunix-report.pdf

Configuration

The configuration file lives under $XDG_CONFIG_HOME/sunix/sunix.toml, with the following fields being required:

flake_dir=$HOME/workspace/nix-config
home_flake=niri-hdmi
nixos_flake=aorus

By default, both Home Manager and NixOS builds run from flake_dir. If those configurations live in different flakes, override either directory with these optional fields:

home_flake_dir=$HOME/workspace/home-config
nixos_flake_dir=$HOME/workspace/nixos-config

Nix Build

The Home Manager configuration is built via:

nix build --print-out-paths --no-link \
  --override-input nixpkgs "https://channels.nixos.org/nixos-unstable/nixexprs.tar.zst" \
  --refresh \
  .#homeConfigurations.<home_flake>.activationPackage

Whereas the NixOS configuration is built via:

nix build --print-out-paths --no-link \
  --override-input nixpkgs "https://channels.nixos.org/nixos-unstable/nixexprs.tar.zst" \
  --refresh \
  .#nixosConfigurations.<nixos_flake>.config.system.build.toplevel

Both builds refresh fetched inputs and override the configured nixpkgs input. These optional fields set the input name and replacement flake reference (shown with their defaults):

nixpkgs_input=nixpkgs
nixpkgs_url=https://channels.nixos.org/nixos-unstable/nixexprs.tar.zst

Unset or empty values use the defaults. In the Home Manager module, configure these as programs.sunix.settings.nixpkgsInput and programs.sunix.settings.nixpkgsUrl.

Diff

The diff with the current system state is computed via dix. If it's not installed in your system, you can set the dix_binary option in the configuration file directly, e.g.

dix_binary=/nix/store/6ziw66nh8a4b6nwrqmj0n80nsdxz5m61-dix-2.1.0/bin/dix

So that the dix binary is only available to SUNix.

Demo

Set show_demo=true to reveal a "Demo" button that renders the bundled sample.json report. Alternatively, you can also run sunix --demo which will ignore the configuration value.

Style

SUNix uses the bundled assets/style.css by default. If you'd like to use a custom CSS file, set the following option:

style_css=/path/to/custom-style.css

NOTE: this should be a full replacement, so a good starting point would be to copy assets/style.css and make your own adjustments.

Develop

The provided Nix devshell contains the necessary software to build this project.

nix develop
cargo run
cargo fmt
cargo test
cargo clippy --all-targets --all-features

Additionally, it can be run directly via nix run.

Waybar

SUNix can be easily integrated with Waybar, e.g.

"custom/sunix": {
  "format": " SUNix",
  "on-click": "pgrep -io 'sunix' | xargs kill || sunix",
  "tooltip-format": "Software Updates for Nix"
}

Design Idea

This project started by following my curiosity after I've replaced nvd --diff by dix, then I thought I could automate this idea of "Software Updates" as it's common in other Linux distros.

You can achieve the same functionality directly in your terminal with these one-liners.

NixOS

nix build --print-out-paths --no-link \
  .#nixosConfigurations.<nixos_flake>.config.system.build.toplevel \
  | xargs dix /run/current-system/

The SUNix cli can also be used to get a Markdown report for Pull Requests:

nix build --print-out-paths --no-link --refresh \
  --override-input nixpkgs "https://channels.nixos.org/nixos-unstable/nixexprs.tar.zst" \
  .#nixosConfigurations.<nixos_flake>.config.system.build.toplevel \
  | xargs dix --output json /run/current-system/ \
  | sunix --markdown-report "NixOS .#<nixos_flake>"

Home Manager

nix build --print-out-paths --no-link --refresh \
  --override-input nixpkgs "https://channels.nixos.org/nixos-unstable/nixexprs.tar.zst" \
  .#homeConfigurations.<home_flake>.activationPackage \
  | xargs -r dix --output json (readlink -f "$XDG_STATE_HOME/nix/profiles/home-manager")
  | sunix --markdown-report "Home Manager .#<home_flake>"

DISCLAIMER

This project was assisted by AI tools, especially for all the UI stuff I suck at, but the actual logic was designed and reviewed by myself. This documentation has been written by hand as well, as I enjoy doing so.