solvecraft/docs/nix.md

SolidCraft with Nix

The flake supports x86_64-linux, aarch64-linux and aarch64-darwin. Enable Nix's nix-command and flakes experimental features. The committed flake.lock pins nixpkgs and its Rust toolchain; package evaluation checks that compiler against the Rust floor in Cargo.toml.

Run, build or install

Run the current app without installing it:

nix run github:bherbruck/solidcraft#solidcraft -- --sample

Inside a checkout, nix run . and nix run .#solidcraft launch the desktop app. nix run .#cli -- --version launches the CLI. The legacy .#solidcraft app name also works. These commands use the flake's exact wrapped binary, rather than an older executable already on your shell's PATH.

Build without installing:

nix build github:bherbruck/solidcraft#solidcraft
./result/bin/solidcraft --version
./result/bin/solidcraft --sample

The result contains solidcraft, solidcraft-cli and the deprecated old-name CLI alias (see compatibility.md). Building does not install a desktop-menu entry. For a user profile installation, run:

nix profile install github:bherbruck/solidcraft#solidcraft
solidcraft --sample

On Linux, this installs the SolidCraft desktop entry, MIME definition and generated icon sizes alongside the commands. On macOS the package contains the binaries only; for a bundled SolidCraft.app, use the release .dmg. NixOS/Home Manager can instead put the flake's packages.${system}.solidcraft in environment.systemPackages/home.packages. If a non-NixOS desktop does not discover profile-installed launchers, ensure that its session includes ~/.nix-profile/share in XDG_DATA_DIRS, then log out and back in. The desktop/application ID is unchanged (see compatibility.md).

Check which executable a plain terminal command would run:

type -a solidcraft
readlink -f "$(command -v solidcraft)"
solidcraft --version
nix run github:bherbruck/solidcraft#solidcraft -- --version

An unrelated old executable on PATH is not updated by nix build. Use the flake app or ./result/bin/solidcraft to verify the package you just built.

Graphics and file dialogs

The app wrapper includes Wayland, X11, xkbcommon, EGL, Vulkan-loader and D-Bus libraries. It exposes /run/opengl-driver/lib and /run/opengl-driver/share so NixOS's graphics drivers and Vulkan manifests are discoverable. Enable hardware.graphics.enable = true on NixOS and keep the system's driver stack consistent with the compositor. File pickers also need a working session D-Bus and the desktop's xdg-desktop-portal service.

On macOS (aarch64-darwin), none of this applies: winit talks to AppKit, wgpu renders through Metal, and the GPU drivers ship with the operating system, so the darwin package carries no library wrapper and no extra search paths.

On another distribution, graphics drivers outside the Nix store may need a matching nixGL wrapper. Follow its GPU-specific instructions; a wrapper for a different driver is not a substitute. For Intel/Mesa, after building:

nix run github:nix-community/nixGL#nixGLIntel -- ./result/bin/solidcraft --sample

If a window is black, first verify that you launched the newly wrapped package and that your system exposes a functioning GPU driver. WGPU_BACKEND=vulkan selects Vulkan for diagnosis; a loader without a usable driver still cannot render. OpenGL rendering uses 1x anti-aliasing to avoid the multisampled black-frame failure. Vulkan and other backends keep the requested sample count; saved preferences are preserved. For older builds, including 0.3.0, set Anti-aliasing to 1x and restart when using OpenGL. If that window cannot show the settings dialog, edit only the msaa field to 1 in ~/.local/share/solidcraft/graphics.json; preserve any other settings.

Wayland, XWayland and niri

On Linux the app runs through XWayland whenever an X display is available, because winit only supports dragging files from a file manager into the window on X11. On niri (detected from XDG_CURRENT_DESKTOP with a Wayland socket present) it stays on native Wayland instead, since window management such as maximize/restore misbehaves under niri's XWayland. The trade-off: on native Wayland, dropping files onto the window does not work; use File > Open or pass the file on the command line. This applies to every build, not only the Nix package.

Choose it in Preferences › Graphics › Window system (Automatic, Wayland or X11; it applies at the next start). The pane says which one is running and, on native Wayland, links to winit's issue about dropping files there. Native Wayland is the better choice with display scaling whenever the compositor doesn't let X11 apps scale themselves: XWayland windows are then drawn at 100 % and stretched, so the interface looks soft and small. That's the case with fractional scaling (a monitor at 125 % or 140 %), and on GNOME 47 (RHEL and Rocky Linux 10) at any scale, 200 % included; see the troubleshooting page.

The environment overrides the preference: SOLIDCRAFT_WAYLAND=1 (always native Wayland) or SOLIDCRAFT_WAYLAND=0 (XWayland whenever an X display is available).

Development shells

nix develop supplies runtime libraries and uses the Rust/C toolchain already on your PATH. nix develop .#rust supplies the pinned toolchain, C linker and target/nix build directory. Both retain the GUI and CLI's existing Cargo package names (solidcraft, solidcraft-cli).