Package for Nix, NixOS, and Guix, and document installing from them

.envrc

@@ -0,0 +1,5 @@
+# SPDX-FileCopyrightText: 2026 Mohamed Hammad <Mohamed.Hammad@SpacecraftSoftware.org>
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# direnv: enter the flake's development shell on cd. Run `direnv allow` once.
+use flake

.github/workflows/ci.yml

@@ -31,6 +31,26 @@ jobs:
       - name: Test
         run: cargo test --workspace
 
+  nix:
+    name: nix flake check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: DeterminateSystems/nix-installer-action@main
+
+      # Builds packages.default (which runs the test suite in its check phase)
+      # and evaluates every devShell. This is also the gate on the flake staying
+      # in step with packaging/default.nix, since both come from one definition.
+      - name: Flake check
+        run: nix flake check --print-build-logs
+
+      - name: Smoke-test the built binary
+        run: |
+          nix build --print-build-logs
+          ./result/bin/vacuum --version
+          ./result/bin/vacuum list --json --category temp-files > /dev/null
+
   reuse:
     name: REUSE compliance
     runs-on: ubuntu-latest

.gitignore

@@ -13,6 +13,13 @@
 doc/*.info
 doc/*.html
 
+# Nix build symlinks (`nix build` writes ./result)
+/result
+/result-*
+
+# direnv's per-directory cache; .envrc itself is tracked
+/.direnv
+
 # Editor / OS noise
 .DS_Store
 *.swp

README.md

@@ -91,12 +91,81 @@ vacuum list --json           # machine-readable output for scripts/agents
 
 ## Install
 
-Requires Rust (edition 2024, MSRV 1.85+). From a clone:
+> Do **not** run `cargo install vacuum`. An unrelated crates.io crate holds that
+> name (a spaceflight CLI). Install from this repository, as below.
+
+### Nix and NixOS
+
+The flake needs no Rust toolchain on the host — it supplies one.
+
+```sh
+nix run github:Spacecraft-Software/Vacuum          # run it once, install nothing
+nix profile install github:Spacecraft-Software/Vacuum   # install for this user
+nix build github:Spacecraft-Software/Vacuum        # build only; ./result/bin/vacuum
+```
+
+To install it system-wide, add the flake as an input and enable the module:
+
+```nix
+{
+  inputs.vacuum.url = "github:Spacecraft-Software/Vacuum";
+
+  # in your NixOS configuration:
+  # imports = [ inputs.vacuum.nixosModules.default ];
+  # programs.vacuum.enable = true;
+}
+```
+
+Or drop the package straight into `environment.systemPackages`:
+
+```nix
+environment.systemPackages = [ inputs.vacuum.packages.${pkgs.system}.default ];
+```
+
+For hacking on Vacuum itself, `nix develop` gives you rustc, cargo, clippy,
+rustfmt, rust-analyzer, mold, reuse, and texinfo. `nix flake check` builds the
+package and runs the test suite.
+
+### GNU Guix System
+
+`manifest.scm` supplies the toolchain; nothing is installed on the host until you
+ask for it:
 
 ```sh
-cargo install --path crates/vacuum-cli
+git clone https://github.com/Spacecraft-Software/Vacuum
+cd Vacuum
+guix shell -m manifest.scm -- cargo install --path crates/vacuum-cli
 ```
 
+That puts `vacuum` in `~/.cargo/bin`. To work on the source instead:
+
+```sh
+guix shell -m manifest.scm            # toolchain only, host untouched
+guix shell --pure -m manifest.scm     # ignore the ambient environment
+```
+
+A package definition lives in `packaging/guix.scm`, but it is **not buildable
+yet**: `cargo-build-system` resolves dependencies through `#:cargo-inputs` rather
+than from `Cargo.lock`, and this workspace has 191 locked crates. That list is
+generated with `guix import crate -r vacuum` at release time. Until then, use the
+`guix shell` route above.
+
+### Arch Linux
+
+```sh
+cd packaging && makepkg -si
+```
+
+### From source
+
+Requires Rust (edition 2024, MSRV 1.85+):
+
+```sh
+cargo install --path crates/vacuum-cli --force
+```
+
+`--force` replaces any previous install of the `vacuum` binary.
+
 ## Project Posture
 
 Vacuum is a **Personal / Hobby** project (Steelbore Standard §5). Provided **AS IS**, with no

doc/vacuum.texi

@@ -56,6 +56,7 @@ under @file{LICENSES/}.
 
 @menu
 * Overview::             What Vacuum does.
+* Installation::         Nix, NixOS, GNU Guix System, Arch, and from source.
 * Invocation::           Commands and global options.
 * Interactive TUI::      Keys and the runtime directory picker.
 * Output Modes::         Human text, JSON envelope, JSONL, and field selection.
@@ -85,6 +86,96 @@ Vacuum is conservative by default: it never removes anything without an explicit
 @option{--apply}, it routes deletions to the trash unless you ask to purge, and
 it refuses to touch protected system paths. @xref{Safety Model}.
 
+@node Installation
+@chapter Installation
+
+@quotation Warning
+Do not run @samp{cargo install vacuum}. An unrelated crate on @uref{https://crates.io,
+crates.io} holds that name (a spaceflight command-line tool). Install from the
+Vacuum repository, as described below.
+@end quotation
+
+@section Nix and NixOS
+
+The flake supplies its own Rust toolchain, so nothing is needed on the host
+beyond Nix itself with flakes enabled.
+
+@example
+nix run github:Spacecraft-Software/Vacuum
+nix profile install github:Spacecraft-Software/Vacuum
+nix build github:Spacecraft-Software/Vacuum
+@end example
+
+For a system-wide install, add the flake as an input and enable the NixOS
+module it exports:
+
+@example
+@{
+  inputs.vacuum.url = "github:Spacecraft-Software/Vacuum";
+
+  # in your NixOS configuration:
+  # imports = [ inputs.vacuum.nixosModules.default ];
+  # programs.vacuum.enable = true;
+@}
+@end example
+
+Equivalently, place the package in @code{environment.systemPackages}
+directly:
+
+@example
+environment.systemPackages =
+  [ inputs.vacuum.packages.$@{pkgs.system@}.default ];
+@end example
+
+To work on Vacuum itself, @command{nix develop} provides rustc, cargo, clippy,
+rustfmt, rust-analyzer, mold, @command{reuse}, and Texinfo.
+@command{nix flake check} builds the package and runs the test suite.
+
+@section GNU Guix System
+
+The repository ships @file{manifest.scm}, which provides the toolchain without
+installing anything on the host.
+
+@example
+git clone https://github.com/Spacecraft-Software/Vacuum
+cd Vacuum
+guix shell -m manifest.scm -- cargo install --path crates/vacuum-cli
+@end example
+
+This installs the @command{vacuum} binary into @file{~/.cargo/bin}. To obtain
+only the development environment:
+
+@example
+guix shell -m manifest.scm
+guix shell --pure -m manifest.scm
+@end example
+
+A Guix package definition exists at @file{packaging/guix.scm}, but it is not
+yet buildable. Guix's @code{cargo-build-system} resolves dependencies through
+@code{#:cargo-inputs} rather than from @file{Cargo.lock}, and this workspace
+locks 191 crates; that list is generated with @samp{guix import crate -r
+vacuum} at release time. Until then, use the @command{guix shell} route above.
+
+@section Arch Linux
+
+A @file{PKGBUILD} is provided:
+
+@example
+cd packaging && makepkg -si
+@end example
+
+@section From source
+
+Vacuum requires Rust edition 2024 with a minimum supported Rust version of
+1.85.
+
+@example
+cargo install --path crates/vacuum-cli --force
+@end example
+
+The @option{--force} flag replaces any previously installed @command{vacuum}
+binary.
+
 @node Invocation
 @chapter Invocation