How to Check the Status of Package Builds in twist.nix

Use the depsCheck attribute in pkgs/emacs/default.nix to validate dependency constraints, which returns a derivation that either succeeds silently or fails with a JSON report detailing version mismatches.

The twist.nix repository provides a Nix-based Emacs Lisp package manager that enforces strict dependency versioning. When you declare packages in your configuration, the system must verify that all transitive dependencies satisfy version constraints before building. The build status check mechanism allows you to identify unsatisfied dependencies early in the evaluation process.

Understanding the Build Status Check in twist.nix

The core validation logic resides in two key files. In pkgs/emacs/default.nix, the depsCheck attribute defines a derivation that invokes the validation tool. This tool is implemented in pkgs/emacs/tools/check-versions.nix, which computes the dependency graph and compares declared versions against available versions.

The check produces binary outcomes:

• Success: The derivation builds an empty file, indicating all packages have satisfying dependencies.
• Failure: The derivation fails with a non-zero exit code and exposes a detailed status report via the passthru attribute, containing specific version constraint violations.

Checking Package Build Status Locally

Quick Validation with nix build

Run the dependency check directly to see if your configuration is valid:

nix build .#depsCheck

If the command completes without error, all dependency constraints are satisfied. If it fails, you will see a warning message listing packages with insufficient dependencies, such as:

Warning: The following packages have insufficient dependencies:
  - magit: requires >= 2.90.0, found 2.89.0

Detailed Inspection with nix eval

To programmatically inspect the status without triggering a build failure, evaluate the passthru attribute:

nix eval '(import ./test/twist.nix { pkgs = import <nixpkgs> {}; }).depsCheck.passthru' --json

This outputs a JSON object containing the full status report:

{
  "status": {
    "errors": {
      "magit": {
        "required": "2.90.0",
        "current": "2.89.0",
        "satisfied": false
      }
    },
    "summary": {
      "magit": "magit"
    },
    "packages": {}
  }
}

The status.errors field maps package names to their version conflicts, while status.summary provides a concise list of affected packages.

Automating Build Checks in CI

Integrate the dependency check into your continuous integration pipeline to catch version mismatches before deployment:

{ pkgs ? import <nixpkgs> {} }:

let
  cfg = import ./test/twist.nix { inherit pkgs; };
in
pkgs.runCommand "twist-deps-check" { } ''
  ${cfg.depsCheck} || {
    echo "Dependency check failed – see errors in passthru"
    exit 1
  }
  echo "All dependencies satisfied."
''

This derivation fails the CI job immediately when any package constraint is violated, printing the specific error details for debugging.

Summary

• The depsCheck attribute in pkgs/emacs/default.nix validates all package dependencies in your twist.nix configuration.
• Run nix build .#depsCheck for a quick pass/fail validation of your package set.
• Inspect detailed failure reports via the passthru attribute, which exposes status.errors and status.summary as JSON.
• The validation logic is implemented in pkgs/emacs/tools/check-versions.nix, which computes dependency satisfaction across the graph.
• Integrate the check into CI pipelines using nix eval or nix build to prevent deployments with unsatisfied dependencies.

Frequently Asked Questions

What is the depsCheck attribute in twist.nix?

The depsCheck attribute is a derivation defined in pkgs/emacs/default.nix that performs a static analysis of your Emacs Lisp package dependencies. It invokes the version checking tool to ensure that every package in your configuration has dependencies that satisfy their declared version constraints, returning either an empty file on success or a failure with detailed error data.

Where does twist.nix store the build status report?

The build status report is exposed through the derivation's passthru attribute, specifically under passthru.status. This JSON object contains three main fields: errors (detailed version mismatches), summary (a concise list of affected packages), and packages (full dependency graph information). You can access this data using nix eval without triggering a build failure.

How do I fix unsatisfied dependency errors in twist.nix?

When depsCheck reports unsatisfied dependencies, examine the status.errors field to identify which packages require different versions. You have three resolution paths: upgrade the offending package to a compatible version in your lock file, override the dependency constraint if the version is functionally compatible, or remove the package if it cannot satisfy the dependency graph. After making changes, re-run nix build .#depsCheck to verify the fix.

Can I check build status without building the packages?

Yes, the depsCheck validation is a static analysis that does not require building the actual Emacs Lisp packages. It only evaluates the dependency graph and version constraints defined in your Nix expressions. Use nix eval to inspect the passthru attribute or run nix build .#depsCheck to execute the check derivation, both of which operate purely at evaluation time without compiling package sources.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}