This document is intended both for maintainers of the nix code and for developers facing issues with their development environment or with the CI system. Use CTRL-F to look for relevant keywords.
In general when facing any problem related to the nix shell or cabal failing to build when it shouldn't, the first step is to make sure you are using the latest shell from master: first exit the nix shell, then git pull --rebase origin master, then re-enter the nix shell (i.e. run nix develop).
If that fails, you might be facing a caching issue. In that case, try this before exiting and re-entering the nix shell:
rm -r ~/.cabal/{store,packages} plutus-metatheory/_build dist dist-newstyle
This should never happen, it is a bug in nix, and has been observed in version 2.26.1.
Downgrade or upgrade your nix installation to fix this issue.
Sometimes cabal needs a cabal build all before it can successfully execute a cabal test all.
nix flake update haskell-nix updates haskell.nix.
This should be done infrequently as it is likely to break the nix code.
If you just want new packages from hackage or CHaP instead, you can independently run:
nix flake update hackage CHaP.
Then you can change the index-state in cabal.project: you pick an arbitrary date, and if it's too new, cabal will error out and suggest the latest known date which you can copy-paste.
Modify nested-ci-jobs = {..} in ./nix/outputs.nix.
Modify packages = {..} in ./nix/outputs.nix.
Look at static-haskell-packages = {..} in ./nix/outputs.nix.
Look at windows-hydra-jobs = {..} in ./nix/outputs.nix.
The nix builds can be overridden inside ./nix/project.nix. New cabal flags and configuration options can be defined there.