Hadrian: Add ./hadrian/ghci.sh script for fast development feedback

Running the `./hadrian/ghci` target will load the main compiler into
a ghci session. This is intended for fast development feedback, modules are only
typechecked so it isn't possible to run any functions in the repl.

You can also use this target with `ghcid`.

The first time this command is run hadrian will need to compile a few dependencies
which will take 1-2 minutes. Loading GHC into GHCi itself takes about 30 seconds.

Internally this works by calling a new hadrian target called `tool-args`.
This target prints out the package and include flags which are necessary
to load files into ghci. The same target is intended to be used by other
tooling which uses the GHC API in order to set up the correct GHC API
session. For example, using this target it is also possible to use HIE
when developing on GHC.

1 files changed, 38 insertions, 0 deletions

diff --git a/hadrian/README.md b/hadrian/README.md
index 179d9d07ce..77c3cd0950 100644
--- a/hadrian/README.md
+++ b/hadrian/README.md
@@ -158,6 +158,27 @@ build stage2:lib:text
 build stage1:exe:haddock
 ```
 
+#### Fast feedback using ghci
+
+Running the `./hadrian/ghci.sh` script will load the main compiler into
+a ghci session. This is intended for fast development feedback, modules are only
+typechecked so it isn't possible to run any functions in the repl.
+
+```
+./hadrian/ghci.sh
+```
+
+You can also use this target with `ghcid`.
+
+```
+ghcid --command="./hadrian/ghci.sh"
+```
+
+The first time this command is run hadrian will need to compile a few dependencies
+which will take 1-2 minutes. Loading GHC into GHCi itself takes about 30 seconds and
+reloads after that take in the region of 1-5 seconds depending on which modules
+need to be recompiled.
+
 #### Testing
 
 To run GHC testsuite, use `build test`. See
@@ -203,6 +224,23 @@ a compiler built using Stage2. This is useful for cross-compilation. Detailed
 instructions can be found in the corresponding
 [part of the user settings manual](doc/user-settings.md#specifying-the-final-stage-to-build).
 
+#### Integrating Hadrian into other tooling
+
+The `tool-args` target is designed to allow hadrian to be integrated into other
+tooling which uses the GHC API.
+`tool-args` prints out a list of flags which hadrian will use to compile
+a module in the `compiler` directory. Using these flags you can then set up
+a GHC API session with the correct environment to load a module into your own
+GHC session. This is how `haskell-ide-engine` is able to support hadrian.
+
+```
+> ./hadrian/build.sh tool-args
+-hide-all-packages -no-user-package-db -package-db _build/stage0/lib/packag...
+```
+
+
+The `./hadrian/ghci.sh` script is implemented using this target.
+
 Troubleshooting
 ---------------