Recommend cabal (#1822)

Changes to documentation etc. to recommend the use of `cabal` rather than `stack`.  Closes #1820.

- [x] Update `README.md`
- [x] Update `feedback.yaml`
- [x] Update scripts in `scripts/`
- [x] Update `CONTRIBUTING.md`
- [x] Maybe HLS defaults to using Stack now? Should we create a `hie.yaml.cabal` file with `cradle: cabal:`?
    - See https://discourse.haskell.org/t/whats-the-current-status-of-hls-cradle-discovery/8254/5
    - See https://github.com/Avi-D-coder/implicit-hie

CONTRIBUTING.md

@@ -203,8 +203,6 @@ check the `hie.yaml.stack` file. Pure Cabal should work fine with the defaults,
 but you might want to [add a GHC flag](https://haskell-language-server.readthedocs.io/en/latest/features.html)
 to build docs into `cabal.project.local`.
 
-**TIP:** To run tests, you can use the [`scripts/run-tests.sh` script](scripts/run-tests.sh) to avoid problems with incremental compilation in alternation with `stack build`.
-
 ### Conventions
 
 We follow a few conventions to help keep everyone on the same page.

README.md

@@ -46,21 +46,30 @@ unreleased features), read on.
 
        git clone https://github.com/swarm-game/swarm.git
 
-1. If you don't already have the `stack` tool:
+1. If you don't already have the `cabal` tool:
     1. Get the [`ghcup` tool](https://www.haskell.org/ghcup/), a handy
        one-stop utility for managing all the different pieces of a
        Haskell toolchain.
-    1. Use `ghcup` to install `stack`:
+    1. Use `ghcup` to install a supported version of GHC:
 
-           ghcup install stack
+           ghcup install ghc 9.6.4
 
-1. Now use `stack` to build and run Swarm:
+    1. Use `ghcup` to install `cabal`:
+
+           ghcup install cabal
+
+1. Now use `cabal` to build and run Swarm:
 
        cd /path/to/the/swarm/repo
-       stack run
+       cabal run -O0 swarm:exe:swarm
+
+   (Note that we recommend turning off optimizations with `-O0` since
+   they don't seem to make much difference to the speed of the
+   resulting executable, but they make a big difference in compilation
+   time.)
 
-1. Go get a snack while `stack` downloads a Haskell compiler and
-   all of Swarm's dependencies.
+1. Go get a snack while `cabal` downloads and builds all of Swarm's
+   dependencies.
 
 1. You might also want to check out the `scripts` directory, which
    contains an assortment of useful scripts for developers.

feedback.yaml

@@ -1,3 +1,3 @@
 loops:
-  test: stack test swarm:swarm-integration swarm:swarm-unit --fast
-  unit: stack test swarm:swarm-unit --fast
+  test: cabal test -j -O0 --test-show-details=direct swarm:swarm-integration swarm:swarm-unit
+  unit: cabal test -j -O0 --test-show-details=direct swarm:swarm-unit --fast

hie.cabal.yaml

@@ -0,0 +1,10 @@
+-- If you want to use HLS with Cabal (recommended), simply do
+--
+--   cp hie.cabal.yaml hie.yaml
+--
+-- the file hie.yaml is ignored, so it will not
+-- show in git status ;)
+--
+-- If you are using Stack, you can ignore this file.
+cradle:
+  cabal:

hie.yaml.stack → hie.stack.yaml

@@ -1,6 +1,6 @@
 -- If you want to use HLS with Stack, simply do
 --
---   cp hie.yaml.stack hie.yaml
+--   cp hie.stack.yaml hie.yaml
 --
 -- the file hie.yaml is ignored, so it will not
 -- show in git status ;)

scripts/autoplay-tutorials.sh

@@ -7,7 +7,7 @@ cd $SCRIPT_DIR/..
 if command -v stack &> /dev/null; then
     SWARM="stack exec swarm --"
 else
-    SWARM="cabal run swarm -O0 --"
+    SWARM="cabal run -j -O0 swarm --"
 fi
 
 for tutorial in $(cat scenarios/Tutorials/00-ORDER.txt | xargs); do

scripts/build-game.sh

@@ -7,4 +7,4 @@ cd $(git rev-parse --show-toplevel)
 # target 'swarm:exe:swarm' to the 'stack' command, to avoid building
 # extra dependencies.
 
-stack build --fast swarm:swarm
+cabal build -j -O0 swarm:exe:swarm

scripts/gen/autopopulate-spellchecker.sh

@@ -13,7 +13,7 @@ cd $SCRIPT_DIR/../..
 # Then, generate *.hie files:
 #
 #    cp hie.yaml.stack hie.yaml
-#    stack build --fast
+#    cabal build -j -O0
 
 DBNAME=hie.sqlite
 hiedb --database $DBNAME index .hie

scripts/gen/schema-docs.sh

@@ -3,4 +3,4 @@
 SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
 cd $SCRIPT_DIR/../..
 
-stack build --fast && stack exec -- swarm generate cheatsheet --scenario
+cabal run -j -O0 -- swarm-docs cheatsheet --scenario

scripts/play.sh

@@ -6,4 +6,4 @@ cd $(git rev-parse --show-toplevel)
 # It's been observed in certain versions of GHC that compiling with optimizations
 # results in the swarm UI freezing for a potentially long time upon starting a scenario.
 # See https://github.com/swarm-game/swarm/issues/1000#issuecomment-1378632269
-scripts/build-game.sh && stack exec swarm -- "$@"
+scripts/build-game.sh && cabal run -j -O0 swarm:exe:swarm -- "$@"