doc/internal/multi-repl.md

   1 ---
   2 author: matthew
   3 title: Multiple Component support for cabal repl
   4 postName: cabal-multi-unit
   5 categories: cabal, ghc, hls, hasura, open-source
   6 showtoc: true
   7 ---
   8
   9 Following on from [our work implementing support for compiling multiple units
  10 at once in GHC](https://well-typed.com/blog/2022/01/multiple-home-units/), we have now been extending the ecosystem to take
  11 advantage of this new support. This work has once again been made possible by
  12 [Hasura](https://hasura.io/). This work continues our productive and
  13 [long-running
  14 collaboration](https://well-typed.com/blog/2022/05/hasura-supports-haskell-tooling/)
  15 on important and difficult tooling tasks which will ultimately benefit the
  16 entire ecosystem.
  17
  18 This post focuses on updates to the `cabal repl` command, allowing
  19 multiple components to be loaded at once into an interactive session. The work is being
  20 reviewed in [Cabal MR #8726](https://github.com/haskell/cabal/pull/8726), and should
  21 be available in a future release of `cabal-install`.
  22
  23 <!-- more -->
  24
  25 # Multiple Component Repl
  26
  27 When using `cabal`, most commands take a "target" which specifies which units you want
  28 to operate on. A command such as `cabal build <target>` will resolve all the units that
  29 the target `<target>` resolves to, and build all of them. The behaviour of the `cabal repl`
  30 command is different: you must specify a single unit to build.
  31
  32 Here are some common targets which you can specify when using `cabal`.
  33
  34 * `all`: Build all the locally defined components.
  35 * `exe:haskell-language-server`: Build the executable called `haskell-language-server`
  36 * `lib:pkg-a lib:pkg-b`: Build the local libraries pkg-a and pkg-b.
  37 * `src/Main.hs`: Build the unit which `src/Main.hs` belongs to.
  38
  39 After enabling multi-repl, passing a target specification to `cabal repl` which
  40 resolves to multiple units will load all those units into a single repl session.
  41 For example:
  42
  43 ```
  44 cabal repl --enable-multi-repl lib:pkg-a lib:pkg-b
  45 ```
  46
  47 When the modules are compiled, the unit which they came from is listed next
  48 to the module name. The `interactive` herald in the build plan indicates that
  49 the library will be loaded into GHCi rather than being built like a normal package.
  50
  51 ```
  52 In order, the following will be built (use -v for more details):
  53  - pkg-a-0 (interactive) (lib) (first run)
  54  - pkg-b-0 (interactive) (lib) (dependency rebuilt)
  55 Preprocessing library for pkg-a-0..
  56 Preprocessing library for pkg-b-0..
  57 GHCi, version 9.4.3: https://www.haskell.org/ghc/  :? for help
  58 [1 of 2] Compiling Foo[pkg-a-0-inplace]
  59 [2 of 2] Compiling Bar[pkg-b-0-inplace]
  60 Ok, two modules loaded.
  61 ```
  62
  63 You will need to use at least `ghc-9.4.1` in order to use multiple unit support.
  64 It's advised to use `ghc-9.4.5` or `9.6.1`, in order to benefit from bug fixes.
  65
  66 ## Enabling Multi-repl
  67
  68 There are three ways to enable the multi-repl depending on how much you like it:
  69
  70 * Globally: Add `multi-repl: True` to your `~/.cabal/config` file.
  71 * Project-wide: Add `multi-repl: True` to your cabal.project file.
  72 * Per-invocation: Pass `--enable-multi-repl` when invoking `cabal repl`.
  73
  74 A future cabal version is likely to enable multi-repl by default. For the time being,
  75 and due to the experimental nature of the command and lack of support in ghci for some features,
  76 the multi-repl feature is opt-in.
  77
  78 # Closure Property for Multiple Home Units
  79
  80 For tools or libraries using the GHC API there is one very [important closure property](https://well-typed.com/blog/2022/01/multiple-home-units/#closure-property-for-home-units)
  81 which must be adhered to:
  82
  83 > Any dependency which is not a home unit must not (transitively) depend on a home unit.
  84
  85 For example, if you have three units `p`, `q` and `r`, and `p` depends on `q` which depends on `r`, then it
  86 is illegal to load both `p` and `r` as home units but not `q`, because `q` is a dependency of the home unit `p` which depends
  87 on another home unit `r`.
  88
  89 `cabal` will automatically enable loading of all units which are needed by the closure
  90 property (including non-local) packages. Given the previous example, if you specify
  91 on the command line `cabal repl lib:p lib:q` then `lib:r` will also be loaded
  92 into the same session as it is needed for the closure property.
  93
  94 # Configuring and Promised Dependencies
  95
  96 The lowest-level interface which the `Cabal` library provides in order to build a package
  97 is the [`Setup.hs` script](https://cabal.readthedocs.io/en/3.10/setup-commands.html).
  98 This consists of a normal Haskell file which depends on the `Cabal` library and can be executed
  99 in order to build the package. This is done, after compiling `Setup.hs`, via the following invocations:
 100
 101 ```
 102 ./Setup configure
 103 ./Setup build
 104 ```
 105
 106 The `configure` phase checks to make sure that everything is in order so that when
 107 the build phase is run we know that all the environmental dependencies have already
 108 been provisioned by the user.
 109
 110 In the very old days, people would compile and run `Setup.hs` themselves in order to
 111 build a package, but these days, all the interactions with `Setup.hs` are managed by a
 112 higher-level build tool such as `cabal-install`, `stack` or `nix`. All of these tools
 113 ultimately call `Setup.hs` scripts.
 114
 115 The main technical change to enable the multi-repl was to modify the `Setup.hs`
 116 scripts to allow you to configure a package before all its dependencies are
 117 built. Now you can **promise** to `Setup.hs`
 118 that a certain dependency will be built by the time we attempt to build the unit. Since
 119 all units in a project are going to be built at the same time with one GHC invocation, they
 120 all need to be configured before anything else is built. So we just **promise** that all local
 121 packages will be built.
 122
 123 ```
 124 ./Setup configure --promised-dependency=pkg-a
 125 ```
 126
 127 In addition to the `configure` and `build` commands, `Setup.hs` also provides a `repl`
 128 command which starts `GHCi` and loads a single component.
 129
 130 ```
 131 ./Setup repl
 132 ```
 133
 134 This design is quite awkward because the `Setup.hs` scripts operate on a per-component basis. The
 135 interface is not aware of the existence of complicated multi-component projects, that is solely the
 136 domain of higher-level tools like `cabal-install`. Therefore, instead of starting the repl from
 137 the `Setup.hs` script, we need to start a multi-repl from `cabal-install`. However, the `Setup.hs`
 138 script is still responsible for computing the arguments we need to pass to GHC in order to compile
 139 that component. The solution is to allow the `repl` command to write its arguments into a file
 140 so that they can be collected later by `cabal-install` to correctly start a multi-component session.
 141
 142 ```
 143 ./Setup repl --repl-multi-file=multi-args
 144 # Arguments can be found in the `multi-args` directory.
 145 ```
 146
 147 This allows all the units in your project to be configured before any of them are built.
 148 After a project is configured, the `Setup` executable can be consulted to find out what
 149 options GHC **would** use to build the unit, and because we have **promised** to
 150 make sure things are built in the right order, we can supply these options to GHC
 151 in order to start a multi unit GHCi session.
 152
 153 # HLS support for multiple home units
 154
 155 Zubin has already updated HLS to use native multiple home unit support for GHC-9.4.
 156
 157 The missing piece has been a mechanism to set up a multi component session which
 158 satisfies the closure property. Without such a mechanism, HLS would construct a multiple component session
 159 incrementally by adding units to a session as they are opened by the user. For a complicated
 160 project structure, users would have to very carefully load their files in the right order to
 161 get a session which worked correctly.
 162 Even worse, this doesn't even work when a non-local package is needed to satisfy the
 163 closure property.
 164
 165 HLS consults cabal in order to set up a session: it invokes `cabal repl`
 166 and intercepts the final call to `ghc` which would start the repl. That command is then
 167 used as the options which are needed for the session in order to compile that unit.
 168
 169 Now that `cabal repl` supports creating a command line which specifies the options
 170 for multiple components at once, it makes sense to augment the HLS session loading logic
 171 to also understand these command lines in order to set up a whole multi-component session
 172 at once.
 173
 174 HLS now can understand and parse the kind of command line produced by a multiple
 175 component session. As a result:
 176
 177 * The correct session is initialised up-front. Loading any component in your
 178   local project will work seamlessly and quickly.
 179 * The time taken to initialise a session is reduced, because no local dependencies
 180   are built before the session is started. All local components are configured
 181   before anything is built.
 182 * Cabal ensures the closure property holds, even for non-local packages.
 183
 184 I have been testing this support when working on `cabal` and `ghc`, both projects
 185 with many local dependencies and the experience is much improved. In particular for
 186 `cabal`, the non-local `hackage-security` package is needed for the closure property but could
 187 never be loaded before. This made using HLS on `cabal` very error-prone because if
 188 you opened a file from the `Cabal` library and `cabal-install` library, you would
 189 break the session without a way to recover it. For `ghc`, it is a lifeline to be able to
 190 edit packages like `template-haskell` and see the changes ripple upwards through all
 191 the boot libraries and compiler.
 192
 193 # Limitations
 194
 195 Now that there is a way to easily create and invoke a multi-repl session,
 196 users are probably going to run into limitations of the multi-repl.
 197
 198 Many features are not yet implemented because there is not a good way to change what
 199 the "active unit" of the repl session is. Some more careful thinking needs to be done
 200 to modify the GHCi interface in order to work nicely with multiple components in all situations.
 201
 202 At this time, the multi-repl is best used for interactive development situations where
 203 you want to use the repl to obtain fast-feedback about your project.
 204 We have made sure that the multi-repl works with `ghcid` for example.
 205
 206 # Conclusion
 207
 208 Adding `cabal repl` support for multiple home units allows developers to easily
 209 interact with multiple home unit support in GHC. There are still limitations to
 210 the repl supported in multiple unit sessions, but as more users start using and wanting this
 211 feature we hope to expand the repl to work properly with multiple home units as well.
 212
 213 Well-Typed is able to work on GHC, HLS, Cabal and other core Haskell
 214 infrastructure thanks to funding from various sponsors. If your company might be
 215 able to contribute to this work, sponsor maintenance efforts, or fund the
 216 implementation of other features, please
 217 [read about how you can help](/blog/2022/11/funding-ghc-maintenance) or
 218 [get in touch](mailto:info@well-typed.com).