doc/haskell: begin bringing back haskell documentation to the nixpkgs manual

[sternenseemann]

Motivation for this change

Finally found some motivation to start working on this. I did not feel like it'd be a good idea to just translate the reStructured text 1:1 to nixpkgs, so I've taken the approach of rewriting the documentation from scratch while roughly following along the lines of what we have https://haskell4nix.readthedocs.io/nixpkgs-users-guide.html.

This is probably gonna cause a lot of unnecessary (work for me), but it is also more fun. Additionally it makes it easier to clean up stuff that is outdated by now (references to GHC 7.x, the haskell- pname-prefix that no longer exists etc.).

Also I'd like the general user guide to become more an overview and to move the how-tos in the FAQ section.

cc @cdepillabout @maralorn feedback appreciated and stop me if this is going in the wrong direction for you.

Things done

• Tested using sandboxing (nix.useSandbox on NixOS, or option sandbox in nix.conf on non-NixOS linux)
• Built on platform(s)
  • NixOS
  • macOS
  • other Linux distributions
• Tested via one or more NixOS test(s) if existing and applicable for the change (look inside nixos/tests)
• Tested compilation of all pkgs that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review wip"
• Tested execution of all binary files (usually in ./result/bin/)
• 21.11 Release Notes
  • (Package updates) Added a release notes entry if the change is major or breaking
  • (Module updates) Added a release notes entry if the change is significant
  • (Module addition) Added a release notes entry if adding a new NixOS module
• Fits CONTRIBUTING.md.

[maralorn]

I definitely like what you are writing. Although we can certainly argue about some details. (e.g. the implicit haskell.nix advertising.)

I am a bit uncertain about the whole structure of the thing. You are writing something very explanatory which was definitely missing in this form before.

But we also need the tutorial style explanations for how to install a package, package a package, setup a dev environment. And I am not certain in which order they belong in there.

(I think what I am saying is this: We certainly have an urge to write the stuff into the documentation that was hard to learn before. But we shouldn‘t underestimate the stuff that was previously in there because once it’s not it will be hard to learn.)

[sternenseemann]

(e.g. the implicit haskell.nix advertising.)

Don't necessarily need to argue about that :)

But we also need the tutorial style explanations for how to install a package, package a package, setup a dev environment. And I am not certain in which order they belong in there.

I definitely want to include them again, I don't want to remove any documentation we have already. Restructuring is gonna be easy when we have more content. Specifically I absolutely want to have the following items from the existing documentation:

• the section on ghcWithPackages
• A section on development environments using shellFor and developPackage (which we hadn't before, I think?)
• A section on generating haskell nix expressions using cabal2nix and the ifd helpers to do that
• The documentation of NIX_GHC
• A section on overriding and overlaying haskellPackages

What I'm less inclined to prominently port is all the documentation on having development environments using ghcWithPackages in your user profile. nix-env package management is deprecated for a reason and I wouldn't recommend using haskellPackages in this way.

What I'm uncertain currently is where to best fit in haskell-language-server and stack. I don't use both so, I'm unsure how to best integrate them into what I have in mind so far, but I definitely don't want their documentation to become an afterthought.

For stack, however, I am a bit sceptical: They develop their nix integration completely independently from us which doesn't always lead to too happy outcomes, so I'm not sure if we really should endorse its use as part of the documentation of our infrastructure.

My rough TOC would be

• General overview
• Generic Builder, generating expressions using cabal2nix
• Overriding, overlaying haskellPackages
• ghcWithPackages
• Development Environments (shellFor, developPackage, hls (?), pkg.env, ...)
• Contributing
• FAQ / Troubleshooting

However we may need to reorder some stuff depending on how it turns out. Ideally we'd also be able to add the documentation of haskell.lib in a nice way (#126375).

[sternenseemann]

One tendency of me is too give a too high level insight, so your concern about the tutorial style is very valid. I'm hoping this can be solved by coming up with a sensible order to things in our section…

[cdepillabout]

For stack, however, I am a bit sceptical: They develop their nix integration completely independently from us which doesn't always lead to too happy outcomes, so I'm not sure if we really should endorse its use as part of the documentation of our infrastructure.

I haven't closely read through what you have so far, but just to comment on this point: I think linking to their documentation should be sufficient: https://docs.haskellstack.org/en/stable/nix_integration/

---

It is sort of off topic, but it might also be nice to add a short section that explicitly says that Cabal "nix-style builds" don't involve Nix in any way: https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html. I've seen this question come up a few times. It'd be nice to have a canonical place to point to when people ask about this. Although now that I think about it, this would probably go better in the Cabal manual...

Somewhat confusingly, Cabal also has Nix integration: https://cabal.readthedocs.io/en/latest/nix-integration.html

---

Also, just so we have links to issues, this PR is for #121403.

[sternenseemann]

Superseded by #126674.