Improve READMEs, reproducibility, and make contributing easier

README.md

@@ -59,3 +59,25 @@ contains the derivation as the source repository.
 * directory
 * source archive (zip, tar.gz, ...) from http or https URL or local file.
 * git, mercurial, svn or bazaar repository
+
+## `hackage2nix`
+
+This repository also contains, in the [`hackage2nix/`](./hackage2nix) directory,
+the tool to update the Haskell packages in
+[nixpkgs](https://github.com/NixOS/nixpkgs). It has its own README there.
+
+## Building
+
+For ease of contribution, we support these methods to build `cabal2nix`:
+
+* `stack build` if you have [_Stack_](http://haskellstack.org/)
+  * The Stack build can use system dependencies from a pinned nixpkgs
+    version for increased reproducibility (see [`stack.yaml`](./stack.yaml)).
+    On NixOS this happens automatically.
+    On non-NixOS, use `stack --nix build` for that.
+* `cabal install` if you have [_cabal-install_](https://www.haskell.org/cabal/)
+  installed
+* TODO: Add a build method that requires only `nix` preinstalled,
+  also pins nixpkgs, and is thus fully reproducible.
+
+When making changes, please ensure that all these methods continue to work.

cabal2nix.cabal

@@ -61,7 +61,9 @@ library
   other-modules:      Paths_cabal2nix
   hs-source-dirs:     src
   build-depends:      base                 > 4.11
-                    , Cabal                == 3.2.*
+                    -- When changing the Cabal version, ensure that it builds
+                    -- with all installation methods mentioned in the README!
+                    , Cabal                >= 3.0
                     , aeson                > 1
                     , ansi-wl-pprint
                     , bytestring

hackage2nix/README.md

@@ -1,36 +1,60 @@
-# Hackage2nix
+# `hackage2nix`
 
-This tool is used to update the `hackage-packages.nix` file in the nixpkgs repo.
-Most of the time we will not need run this manually (since it is run automatically
-on the upstream nixpkgs).  The cases when we would need to run this manually are:
+This tool is used to update the Haskell package set in
+[nixpkgs](https://github.com/NixOS/nixpkgs)
+([`hackage-packages.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/haskell-modules/hackage-packages.nix)).
 
-* We have changed hackage2nix in some way and we want to check that it
-behaves correctly.
+Most of the time we do not need run this manually (since it is run automatically
+on the upstream nixpkgs).  Exceptions:
 
-* We have a fork of nixpkgs where we have added or changed
-the name or location in nixpkgs of a native package used by a hackage package
-and we want to check that hackage-packages.nix will be updated correctly.
+* To update the Haskell package set in nixpkgs.
 
-**Important:** this must be run on a **case sensitive file system**.
-On macOS you can use [this](https://gist.github.com/dixson3/8360571) to create one
-(you can replace 60g with 4g as that should be plenty).
+* To test that a structural change to nixpkgs (e.g. name change of a system
+  package) does not break Haskell packages.
+
+* To test changes to `hackage2nix` itself.
+
+#### Video tutorial
 
 There is a [video on YouTube](https://www.youtube.com/watch?v=qX0mgtSm360)
 that gives a thorough walk-through of these steps.
 
+It also explains many of the background considerations.
+
+#### Requirements
+
+This must be run on a **case sensitive file system**.
+On OSX you can use [this](https://gist.github.com/dixson3/8360571) to create one
+(you can replace `60g` with `4g` as that should be plenty).
+
 #### Setup
-Replace `git@github.com:NixOS/nixpkgs.git` with a fork you have access to.
-```
-git clone git@github.com:NixOS/cabal2nix.git
+
+This shows the setup that nixpkgs Haskell maintainers use to iterate on both
+`cabal2nix`, `hackage2nix`, and the Haskell package set in nixpkgs.
+
+It clones `cabal2nix` and puts a `nixpkgs` checkout into it, which the
+repo's `update-nixpkgs.sh` script will update for you.
+
+_Replace `git@github.com:NixOS/nixpkgs.git` with a fork you have push access
+to._
+
+```sh
+git clone https://github.com/NixOS/cabal2nix.git
 cd cabal2nix
-git clone git@github.com:NixOS/nixpkgs.git
-git clone git@github.com:commercialhaskell/all-cabal-hashes.git --branch hackage hackage
+git clone git@github.com:NixOS/nixpkgs.git # replace this with your fork
+git clone https://github.com/commercialhaskell/all-cabal-hashes.git --branch hackage hackage
+# For high reproducibility and pinned nixpkgs for native dependencies
+# (you can leave `--nix` off on NixOS, or if you don't have nix installed):
+stack --nix build
+# Alternatively, to use Cabal's resolver:
 cabal install
 ```
 
-#### Running Hackage2nix
+#### Running `hackage2nix`
+
 Runs hackage2nix and pushes a commit with the updated `hackage-packages.nix`
 file to your fork of `nixpkgs`.
-```
+
+```sh
 ./update-nixpkgs.sh
 ```

src/Distribution/Nixpkgs/Haskell/FromCabal.hs

@@ -1,3 +1,4 @@
+{-# LANGUAGE CPP #-}
 {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE RecordWildCards #-}
 
@@ -106,8 +107,13 @@ fromPackageDescription haskellResolver nixpkgsResolver missingDeps flags Package
                              then fromMaybe (error (display package ++ ": X-Cabal-File-Hash field is missing")) (lookup "X-Cabal-File-Hash" customFieldsPD)
                              else "")
     & metaSection .~ ( Nix.nullMeta
+#if MIN_VERSION_Cabal(3,2,0)
                      & Nix.homepage .~ strip isSpace (fromShortText homepage)
                      & Nix.description .~ fromShortText synopsis
+#else
+                     & Nix.homepage .~ strip isSpace homepage
+                     & Nix.description .~ synopsis
+#endif
                      & Nix.license .~ nixLicense
                      & Nix.platforms .~ Nix.allKnownPlatforms
                      & Nix.hydraPlatforms .~ (if isFreeLicense nixLicense then Nix.allKnownPlatforms else Set.empty)

stack.yaml

@@ -0,0 +1,14 @@
+resolver: lts-15.9 # When changing this: Ensure the nixpkgs path below has the matching GHC!
+packages:
+- .
+nix:
+  path:
+    # Recent `nixos-unstable` branch; this branch is
+    # guaranteed to have binary cache results.
+    # The chosen nixpkgs commit must provide the GHC version
+    # chosen in the `resolver` field above.
+    - nixpkgs=https://github.com/NixOS/nixpkgs/archive/22a3bf9fb9edad917fb6cd1066d58b5e426ee975.tar.gz
+  # Native packages that cabal2nix and its dependencies need:
+  packages:
+    - openssl
+    - zlib