repl command - The Haskell Tool Stack (2024)

stack ghci [TARGET/FILE] [--pedantic] [--ghci-options OPTIONS] [--ghc-options OPTIONS] [--flag PACKAGE:[-]FLAG] [--with-ghc GHC] [--[no-]load] [--package PACKAGE] [--main-is TARGET] [--load-local-deps] [--[no-]package-hiding] [--only-main] [--trace] [--profile] [--no-strip] [--[no-]test] [--[no-]bench]

A read–evaluate–print loop (REPL) environment takes single user inputs, executesthem, and returns the result to the user. GHCi is GHC's interactive environment.The stack ghci or stack repl commands, which are equivalent, allow you toload components and files of your project into GHCi.

The command accepts the same TARGET syntax asstack build. By default:

Stack loads up GHCi with all the library and executable components of all the packages in the project. Pass the flag --test to include test suite components (unlike stack build, test suites will not be run). Pass the flag --bench to include benchmark components (unlike stack build, benchmarks will not be run).

It is also possible to specify a module source code file. For example:

stack ghci src/MyFile.hs

Stack will identify which component the file is associated with, and use theoptions from that component.

Pass the --package option to load GHCi with an additional package that is nota direct dependency of your components. This option can be specified multipletimes.

Pass the option --flag <package_name>:<flag_name> or--flag <package_name:-<flag_name> to set or unset a Cabal flag. This optioncan be specified multiple times. The same Cabal flag name can be set (or unset)for multiple packages with:

--flag *:[-]<flag_name>

Note

In order to set a Cabal flag for a GHC boot package, the package must eitherbe an extra-dep or the package version must be specified with the--package option.

By default:

Stack uses the GHC specified in Stack's configuration. Pass the --with-ghc option with a file path to the executable to specify a different GHC executable;
Stack performs an inital build step. Pass the --no-build flag to skip the step. Pass the --ghc-options option to pass flags or options to GHC. Pass the --profile, --no-strip, --trace flags for the same behaviour as in the case of the stack build command.
Info
Not performing the initial build step speeds up the startup of GHCi. Itonly works if the dependencies of the loaded packages have already beenbuilt.
Stack runs GHCi via ghc --interactive. Pass the --ghc-options option to pass flags or options to GHC (during the initial build step) and to GHCi. Pass the --pedantic flag to pass the GHC options -Wall and -Werror to GHCi (only). Pass the --ghci-options option to pass flags or options to GHCi (only).
Stack configures GHCi to hide unnecessary packages, unless no packages are targetted and no additional packages are specified. Pass the --package-hiding flag to hide unnecessary packages or --no-package-hiding flag not to hide unnecessary packages.
Stack loads and imports all of the modules for each target. Pass the --no-load flag to skip the loading of modules. Pass the --only-main flag to skip the loading of modules other than the main module. Pass the --load-local-deps flag to include all local dependencies of targets.
Info
Not loading modules speeds up the startup of GHCi. Once in GHCi, you canuse :load myModule to load a specific module in your project.
Info
The --only-main flag can be useful if:
1. You're loading the project in order to run it in GHCi (e.g. via main), and you intend to reload while developing. Without flag, you will need to quit and restart GHCi whenever a module gets deleted. With the flag, reloading should work fine in this case.
2. If many of your modules have exports named the same thing, then you'll need to refer to them using qualified names. To avoid this, use the --only-main flag to start with a blank slate and just import the modules you are interested in.
If there are multiple definitions for the Main module, Stack will ask you to select one from a list of options. Pass the --main-is <target> option to specific which Main module to load.

Stack combines all of the GHC options of components.

Note

Combining GHC options should work out when packages share similarconventions. However, conflicts may arise, such as when one componentdefines default extensions which aren't assumed by another. For example,specifying NoImplicitPrelude in one component but not another is likely tocause failures. GHCi will be run with -XNoImplicitPrelude, but it islikely that modules in the other component assume that the Prelude isimplicitly imported.

stack ghci configures GHCi by using a GHCi script file. Such files are locatedin subdirectories of <XDG_CACHE_HOME>/stack/ghci-script, where<XDG_CACHE_HOME> refers to theXDG Base Directory Specificationfor user-specific non-essential (cached) data.

Unix-likeWindows

The default for <XDG_CACHE_HOME> is $HOME/.cache.

On Windows, the default for <XDG_CACHE_HOME> is %LOCALAPPDATA%.

Running plain GHCi¶

stack ghci always runs GHCi configured to load code from packages in yourproject. In particular, this means it passes in flags like -hide-all-packagesand -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.

Note

Running stack ghci on a pristine copy of the code doesn't currently buildlibraries(issue #2790) orinternal libraries(issue #4148). Itis recommended to always use stack build before using stack ghci, untilthese two issues are closed.