Share project between hls and hdb

Author: philderbeast

CONTRIBUTING.md

@@ -167,6 +167,41 @@ For these test executables, `-p` which applies a regex filter to the test
 names. When running `cabal-install` test suites, one need only use `cabal test` or
 `cabal run <test-target>` in order to test locally.
 
+## Using Haskell Language Server
+
+[Haskell Language Server][hls] (HLS) works on this repository through the
+[`hie.yaml`](./hie.yaml) cradle in the root, which points it at the
+[`cabal.hie.project`](./cabal.hie.project) project rather than the default
+`cabal.project`. With that in place, there is nothing to set up beyond having
+an HLS that matches the `ghc` on your `PATH`.
+
+> [!WARNING]
+> Without `hie.yaml`, HLS tries to load the default project and fails with
+> `Failed to parse result of calling cabal` when the `cabal` on your `PATH` is
+> cabal-install 3.18 or later, including a build of this repository. HLS uses
+> [hie-bios][hie-bios], which asks `cabal repl --with-repl` for the flags to
+> load the project, and that fails to resolve dependencies because
+> `cabal-testsuite` has a custom setup depending on an older and incompatible
+> version of `Cabal`. hie-bios then falls back to an older method that
+> cabal-install 3.18 broke. The `cabal.hie.project` project leaves out
+> `cabal-testsuite`, so its own code is the one part of the repository that HLS
+> doesn't cover.
+
+To check the setup from the command line, run HLS on a file. It loads the file
+the same way as it would in an editor and reports what it found:
+
+```
+$ haskell-language-server-9.14.1 cabal-install/main/Main.hs
+...
+Completed (1 file worked, 0 files failed)
+```
+
+HLS and the Haskell debugger share a build directory under `~/.cache/hie-bios`,
+which is why they share a project. Starting the debugger while HLS is still
+loading, or the other way around, can make them trip over each other in there.
+
+[hls]: https://haskell-language-server.readthedocs.io/
+
 ## Using the Haskell Debugger
 
 We can debug `cabal` with the [Haskell debugger][hdb] to set breakpoints, step
@@ -191,14 +226,15 @@ To get set up:
 
 We have a project and cradle for debugging:
 
-* [`cabal.hdb.project`](./cabal.hdb.project) with a subset of packages, leaving
-  out `cabal-testsuite`.
+* [`cabal.hie.project`](./cabal.hie.project) with a subset of packages, leaving
+  out `cabal-testsuite`. This is the same project that Haskell Language Server
+  uses.
 
 * [`hie-hdb.yaml`](./hie-hdb.yaml) uses this project and lists which components
   to load.  Breakpoints can only be set in those components. Everything else is
-  a compiled dependency. The cradle is not named `hie.yaml` so that the Haskell
-  Language Server won't pick it up. This means it has to be given explicitly to
-  `hdb`.
+  a compiled dependency. This is a separate cradle from the `hie.yaml` that
+  Haskell Language Server uses, as it loads many components at once, so it has
+  to be given explicitly to `hdb`.
 
 > [!WARNING]
 > Do not use `cabal.project`, the default project, for debugging. `hdb` tries to

cabal.hdb.project

@@ -0,0 +1,20 @@
+-- A project for the tools that load this repository through hie-bios: Haskell
+-- Language Server (via hie.yaml) and the Haskell debugger (via hie-hdb.yaml).
+-- See the "Using Haskell Language Server" and "Using the Haskell Debugger"
+-- sections of CONTRIBUTING.md.
+--
+-- This leaves out cabal-testsuite because `cabal repl --with-repl`, that
+-- hie-bios relies on, needs Cabal >= 3.16 for the setup of every package in the
+-- project and the custom setup of cabal-testsuite depends on an older Cabal.
+import: project-cabal/ghc-options.config
+import: project-cabal/ghc-latest.config
+import: project-cabal/pkgs/cabal.config
+import: project-cabal/pkgs/install.config
+import: project-cabal/pkgs/tests.config
+import: project-cabal/constraints.config
+
+tests: True
+
+-- The tools load packages as bytecode, ignoring optimization flags and warning
+-- that they do so.
+optimization: False

cabal.hie.project

@@ -1,11 +1,12 @@
 # A hie-bios cradle for debugging cabal with the Haskell debugger (hdb), see
 # the "Using the Haskell debugger" section of CONTRIBUTING.md.
 #
-# This file is deliberately not named hie.yaml so that HLS does not pick it up.
-# Pass it to hdb explicitly, with --cradle-file or "cradleFile".
+# This is not the hie.yaml that Haskell Language Server uses, because it loads
+# many components at once. Pass it to hdb explicitly, with --cradle-file or
+# "cradleFile".
 cradle:
   cabal:
-    cabalProject: cabal.hdb.project
+    cabalProject: cabal.hie.project
     # Breakpoints can only be set in the components loaded here. To debug a
     # test suite, add its component, e.g. cabal-install:test:unit-tests.
     componentsToLoad:

hie-hdb.yaml

@@ -0,0 +1,5 @@
+# The hie-bios cradle for Haskell Language Server, see the "Using Haskell
+# Language Server" section of CONTRIBUTING.md.
+cradle:
+  cabal:
+    cabalProject: cabal.hie.project

hie.yaml

@@ -6,7 +6,7 @@ We have these projects, all in the root:
 $ tree -P '*.project' --prune -L 1
 .
 ├── cabal.bootstrap.project
-├── cabal.hdb.project
+├── cabal.hie.project
 ├── cabal.meta.project
 ├── cabal.project
 ├── cabal.release.project
@@ -78,13 +78,13 @@ package group.
 | Project          | pkgs | cabal | tests | install |
 |------------------|:---: |:---:  |:---:  |:---:    |
 | default          | ✓    |       |       |         |
-| hdb              |      | ✓     | ✓     | ✓       |
+| hie              |      | ✓     | ✓     | ✓       |
 | libonly          |      | ✓     | ✓     |         |
 | release          |      | ✓     | ✓     | ✓       |
 | validate         | ✓    |       |       |         |
 | validate.libonly |      | ✓     | ✓     |         |
 
-The `hdb` project is for use with the Haskell debugger, see
+The `hie` project is for use with Haskell Language Server and the Haskell debugger, see
 [CONTRIBUTING.md](../CONTRIBUTING.md#using-the-haskell-debugger). It imports the
 same package groups as the `release` project, leaving out `cabal-testsuite` and
 the benchmarks.
@@ -103,7 +103,7 @@ Additional configuration is imported:
 | Project          | ghc-options | ghc-latest | constraints |
 |------------------|:---:        |:---:       |:---:        |
 | default          | ✓           | ✓          | ✓           |
-| hdb              | ✓           | ✓          | ✓           |
+| hie              | ✓           | ✓          | ✓           |
 | libonly          | ✓           |            |             |
 | release          |             |            |             |
 | validate         | ✓           | ✓          | ✓           |