stack-1.3.0: doc/ghci.md

# GHCi

`stack ghci` allows you to load components and files of your project into
`ghci`. It uses the same TARGET syntax as `stack build`, and can also take
options like `--test`, `--bench`, and `--flag`.  Similarly to `stack build`, the
default is to load up ghci with all libraries and executables in the project.

In order to load multiple components, `stack ghci` combines all of the ghc options
together.  This doesn't work in the general case, but when the packages being
loaded share similar conventions, it should work out.  A common source of issues
is when one component defines default extensions which aren't assumed by another
component.  For example, specifying `NoImplicitPrelude` in one component but
not another is quite likely to cause failures.  `ghci` will be run with
`-XNoImplicitPrelude`, but it is likely that modules in the other component
assume that the Prelude is implicitly imported.

## Selecting Main module

When loading multiple packages, there may be multiple definitions for the `Main`
module.  You can specify which Main module to load by passing in the
`--main-is TARGET` flag.  If no selection is made and there are multiple `Main`
modules, you will be asked to select from a list of options.

## Speeding up initial load

There are two ways to speed up the initial startup of ghci:

* `--no-build`, to skip an initial build step.  This only works if the
  dependencies have already been built.

* `--no-load`, to skip loading all defined modules into ghci.  You can then
  directly use `:load MyModule` to load a specific module in your project.

## Loading a filepath directly

Instead of the `TARGET` syntax, it is also possible to directly run
`stack ghci src/MyFile.hs`.  This will figure out which component the file is
associated with, and use the options from that component.

## Specifying extra packages to build / depend on

Sometimes you want to load ghci with an additional package, that isn't a direct
dependency of your components.  This can be achieved by using the `--package` flag.
For example, if I want to experiment with the lens library, I can run
`stack ghci --package lens`.

## Running plain ghci

`stack ghci` always runs ghci configured to load code from packages in your
project.  In particular, this means it passes in flags like `-hide-all-packages`
and `-package-id=` in order to configure which packages are visible to ghci.

For doing experiments which just involve packages installed in your databases,
it may be useful to run ghci plainly like `stack exec ghci`. This will run a
plain `ghci` in an environment which includes `GHC_PACKAGE_PATH`, and so will
have access to your databases.