cnix

nixscroll

Summary

nixscroll generates declarative configuration for cscroll, a close downstream of the scroll compositor with a scrolling PaperWM-style tiling layout, and supplies the packaging and system wiring scroll needs because it is not in nixpkgs. Four outputs cooperate: a built package, a home-manager config generator, a NixOS system module, and an Arch plane through the distro reconciler.

The split is load-bearing: the config module installs nothing and only writes the config file, while the system and packaging outputs place the binary and session entries.

What it is

  • Packaging (packages.<system>.scroll): the non-flake cscroll source input built through the maintained scroll-flake Sway and wlroots recipe, with two narrow runtime provisions for Mesa drivers and the IPC helper interpreter.
  • Config generation (homeManagerModules.scroll, namespace programs.scroll): renders the scroll config file from structured options (see home/scroll.nix).
  • System install (nixosModules.scroll, same namespace): installs the package and registers a wayland-sessions entry (see modules/nixos.nix).
  • Arch plane (modules/system-manager.nix): registers cscroll with the compositor launcher and materializes the runtime-component manifest.
  • Supporting library (lib/compositor-descriptor.nix), IPC compatibility module (home/ipc-compat.nix), and eleven declared checks in checks/.

It is not a compositor fork itself; the runtime product is the pinned cscroll source.

How it works

The flake pins one public cscroll revision in flake.lock. Both of scroll-flake’s source inputs follow cscroll, so the recipe cannot reach around to another upstream. Only the scroll executable exports the EGL-vendor file, driver, and GBM backend paths needed when the Nix-built compositor runs on Arch; the IPC helper’s interpreter path is patched at build time without adding tools to the runtime PATH.

The home-manager module translates options such as layout, decoration, animations, and color settings into the compositor’s config syntax. When composed with the desktop substrate, the same complete launch descriptor is registered for display managers and the Arch reconciler, derived from lib/compositor-descriptor.nix and the runtime-component manifest parsed from cscroll’s runtime-components.toml.

How to configure it

Most consumers want the config generator plus one install path. Under the observed programs.scroll surface in home/scroll.nix:

  • programs.scroll.enable — write the config file.
  • Layout, decoration, animation, and color settings — structured equivalents of the compositor’s config stanzas.
  • Desktop-substrate session options — session and device allowlists when composed with the launcher.

Install the binary via nixosModules.scroll on NixOS or through the system-manager plane on Arch; the home module alone changes no installed packages. Review the eleven files in checks/ (config acceptance, IPC compatibility, layout outputs, VM and TTY runtime legs, wrapper and startup contracts) before treating a revision as verified.

Tutorial

This example uses invented values against the real option interface from the referenced revision. The interface shape below was evaluated with the actual module at the pinned revision using synthetic values only; no compositor session was started.

# Synthetic example: invented layout and decoration choices.
{
  imports = [ inputs.nixscroll.homeManagerModules.scroll ];
 
  programs.scroll = {
    enable = true;
    animations.enable = true;
    decoration.borderRadius = 8;
  };
}

System installation is a separate explicit step:

# Synthetic example: public placeholder only.
nix run github:example-org/nixscroll-demo#scroll -- --help

Treat the config module as text generation: confirm a real scroll binary is on PATH before expecting a session to start.

Evidence and limits

This page is bound to public revision 4202896f6b57bbf7820959893da5e07ca0656a32. That tree contains the flake outputs, home/scroll.nix, home/ipc-compat.nix, lib/compositor-descriptor.nix, modules/nixos.nix, modules/system-manager.nix, the checks/ suite, and the pinned cscroll and scroll-flake inputs discussed above.

CNIX has not independently established a successful evaluation, build, config render, or compositor session for that revision. The tutorial interface above was evaluated against the real module at that revision with synthetic values: enable, animation, and decoration settings pass type checking with no residual assertions. Packaging behavior, VM runtime legs, and Arch reconciliation are described from source structure, not from reproduced runs.

nixscroll owns scroll configuration, packaging selection, and session registration only. Compositor-agnostic desktop startup, remote forwarding of composited apps, audio fabric, and shell tooling are sibling concerns with their own revision-addressed concepts. Its relationship to other Corbet Nix projects is currently a shared design direction, not evidence of runtime integration.