From 28b15ff6ec2df7283725938db945e4fd74d55aab Mon Sep 17 00:00:00 2001
From: Moritz Angermann <moritz.angermann@gmail.com>
Date: Thu, 25 May 2023 11:22:45 +0800
Subject: [PATCH] Update README.md (#65)

Improve readme regarding the devshells we have.

---------

Co-authored-by: Andrea Bedini <andrea@andreabedini.com>
---
 README.md | 58 +++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 48 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 61ea418..1b90574 100644
--- a/README.md
+++ b/README.md
@@ -1,23 +1,61 @@
-# Developer Experience Repo
+# The Developer Experience Shell
 
-To obtain a development shell for hacking on haskell based projects at use
+This repo contains a `nix develop` shell for haskell. Its primary purpose is to
+help get a development shell for haskell quickly and across multiple
+operating systems (and architectures).
 
-```
+It requires [`nix` to be installed](https://nixos.org/download.html).
+
+Once you have `nix`, (linux, macOS, windows WSL) you can use
+
+```bash
 nix develop github:input-output-hk/devx#ghc8107 --no-write-lock-file --refresh
 ```
 
-if you want to pick a specific system (e.g. you are on an apple silicon mac, and want to switch between different architectures):
+to obtain a haskell evelopment shell for GHC 8.10.7 including `cabal-install`,
+as well as `hls` and `hlint`. If you are on macOS on an apple silicon chip (M1, M2, ...),
+and want to switch between Intel (x86_64) and Apple Silicon (aarch64), you can do
+this by simply passing the corresponding `--system` argument:
 
-```
+```bash
 nix develop github:input-output-hk/devx#ghc8107 --no-write-lock-file --refresh --system x86_64-darwin
 ```
 or
-```
+```bash
 nix develop github:input-output-hk/devx#ghc8107 --no-write-lock-file --refresh --system aarch64-darwin
 ```
 
-To use a different compiler, chose `#ghc925` instead of `#ghc8107` or similar. There are also other configurations:
+## Compilers and Flavours
 
-- `#ghc8107-minimal` (same as `#ghc8107`, but without `haskell-langauge-server` or `hlint`).
-- `#ghc8107-static` (same as `#ghc8107`, but configured to produce static outputs instead of dynamically linked ones).
-- `#ghc8107-static-minimal` (same as `#ghc8107-static`, but configured without `haskell-language-server` or `hlint`).
+There are multiple compilers available, and usually the latest for each series
+from 8.10 to 9.6 (a slight delay between the official release announcement and
+the compiler showing up in the devx shell is expected due to integration work
+necessary). The current available ones are: `ghc8107`, `ghc902`, `ghc945`, and
+`ghc961` (these are the same ones as in [haskell.nix](https://github.com/input-output-hk/haskell.nix) and may contain patches for defects in the official releases).
+
+### Flavours
+There are various flavours available as suffixes to the compiler names (e.g. `#ghc8107-minimal-iog`).
+
+| Flavour | Description | Example | Included |
+| - | - | - | - |
+| empty | General Haskell Dev | `#ghc8107` | `ghc`, `cabal-install`, `hls`, `hlint` |
+| `-iog` | IOG Haskell Dev | `#ghc8107` | adds `sodium-vrf`, `blst`, `secp256k1`, `R`, `postgresql` |
+| `-minimal` | Only GHC, and Cabal | `#ghc8107-minimal` | drops `hls`, `hlint` |
+| `-static` | Building static binaries | `#ghc8107-static` | static haskell cross compiler |
+| `-js` | JavaScript Cross Compiler | `#ghc8107-js` | javascript haskell cross compiler |
+| `-windows` | Windows Cross Compiler | `#ghc8107-windows` | windows haskell cross compiler |
+
+these can then be comined following this schema:
+```
+#ghc<ver>[-js|-windows|-static][-minimal][-iog]
+```
+For example
+```bash
+nix develop github:input-output-hk/devx#ghc8107-windows-minimal-iog --no-write-lock-file --refresh
+```
+would provide a development shell with a windows cross compiler as well as cabal, and the IOG specific libraries, but no Haskell Language Server (hls), and no HLint.
+
+A full list of all available `devShells` can be see with:
+```bash
+nix flake show github:input-output-hk/devx
+```