Skip to content

Commit bc418bc

Browse files
mpilgremmpilgrem
committed
Re commercialhaskell#5522 Extend documentation of stack ghci
Also reorganises content to be less tutorial-like.
1 parent f94fe15 commit bc418bc

File tree

1 file changed

+80
-75
lines changed

1 file changed

+80
-75
lines changed

‎doc/ghci.md

Lines changed: 80 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -15,105 +15,110 @@ them, and returns the result to the user. GHCi is GHC's interactive environment.
1515
The `stack ghci` or `stack repl` commands, which are equivalent, allow you to
1616
load components and files of your project into GHCi.
1717

18-
The command uses the same TARGET syntax as `stack build`. It can also take flags
19-
like `--test` and `--bench` and options like `--flag`. Similarly to
20-
`stack build`, the default is to load up GHCi with all libraries and executables
21-
in the project.
22-
23-
In order to load multiple components, `stack ghci` combines all of the GHC
24-
options together. This doesn't work in the general case, but when the packages
25-
being loaded share similar conventions, it should work out. A common source of
26-
issues is when one component defines default extensions which aren't assumed by
27-
another component. For example, specifying `NoImplicitPrelude` in one component
28-
but not another is quite likely to cause failures. GHCi will be run with
29-
`-XNoImplicitPrelude`, but it is likely that modules in the other component
30-
assume that the `Prelude` is implicitly imported.
18+
The command accepts the same TARGET syntax as
19+
[`stack build`](build_command.md#target-syntax). By default:
3120

32-
`stack ghci` configures GHCi by using a GHCi script file. Such files are located
33-
in subdirectories of `<XDG_CACHE_HOME>/stack/ghci-script`, where
34-
`<XDG_CACHE_HOME>` refers to the
35-
[XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)
36-
for user-specific non-essential (cached) data. On Unix-like operating systems,
37-
the default for `<XDG_CACHE_HOME>` is `$HOME/.cache`. On Windows, the default
38-
is `%LOCALAPPDATA%`.
21+
* Stack loads up GHCi with all the library and executable components of all the
22+
packages in the project. Pass the flag `--test` to include test suite
23+
components (unlike `stack build`, test suites will not be run). Pass the flag
24+
`--bench` to include benchmark components (unlike `stack build`, benchmarks
25+
will not be run).
3926

40-
## Selecting Main module
27+
It is also possible to specify a module source code file. For example:
4128

42-
When loading multiple packages, there may be multiple definitions for the `Main`
43-
module. You can specify which `Main` module to load with the
44-
`--main-is <target>` option. If no selection is made and there are multiple
45-
`Main` modules, you will be asked to select from a list of options.
29+
~~~text
30+
stack ghci src/MyFile.hs
31+
~~~
4632

47-
## Speeding up initial load
33+
Stack will identify which component the file is associated with, and use the
34+
options from that component.
4835

49-
There are two ways to speed up the initial startup of GHCi:
36+
Pass the `--package` option to load GHCi with an additional package that is not
37+
a direct dependency of your components. This option can be specified multiple
38+
times.
5039

51-
1. Pass the `--no-build` flag, to skip an initial build step. This works only
52-
if the dependencies have already been built.
40+
Pass the option `--flag <package_name>:<flag_name>` or
41+
`--flag <package_name:-<flag_name>` to set or unset a Cabal flag. This option
42+
can be specified multiple times. The same Cabal flag name can be set (or unset)
43+
for multiple packages with:
5344

54-
2. Pass the `--no-load` flag, to skip loading all defined modules into GHCi.
55-
You can then directly use `:load MyModule` in GHCi to load a specific module
56-
in your project.
45+
~~~text
46+
--flag *:[-]<flag_name>
47+
~~~
5748

58-
## Loading just the main module
49+
!!! note
5950

60-
By default, `stack ghci` loads and imports all of the modules in the package.
61-
This allows you to easily use anything exported by your package. This is usually
62-
quite convenient, but in some cases it makes sense to only load one module, or
63-
no modules at all. The `--only-main` flag allows this. It specifies that only
64-
the main module will be loaded, if any. This is particularly useful in the
65-
following circumstances:
51+
In order to set a Cabal flag for a GHC boot package, the package must either
52+
be an extra-dep or the package version must be specified with the
53+
`--package` option.
6654

67-
1. You're loading the project in order to run it in GHCi (e.g. via `main`), and
68-
you intend to reload while developing. Without the `--only-main` flag, you
69-
will need to quit and restart GHCi whenever a module gets deleted. With the
70-
flag, reloading should work fine in this case.
55+
By default:
7156

72-
2. If many of your modules have exports named the same thing, then you'll need
73-
to refer to them using qualified names. To avoid this, it may be easier to
74-
use the `--only-main` flag to start with a blank slate and just import the
75-
modules you are interested in.
57+
* Stack uses the GHC specified in Stack's configuration. Pass the `--with-ghc`
58+
option with a file path to the executable to specify a different GHC
59+
executable;
7660

77-
## Loading a filepath directly
61+
* Stack loads and imports all of the modules for each target. Pass the
62+
`--no-load` flag to skip the loading of modules. Pass the `--only-main` flag
63+
to skip the loading of modules other than the main module.
7864

79-
Instead of the `TARGET` syntax, it is also possible to command directly, for
80-
example:
65+
!!! info
8166

82-
~~~text
83-
stack ghci src/MyFile.hs
84-
~~~
67+
Not loading modules speeds up the startup of GHCi. Once in GHCi, you can
68+
use `:load myModule` to load a specific module in your project.
8569

86-
This will figure out which component the file is associated with, and use the
87-
options from that component.
70+
!!! info
8871

89-
## Specifying extra packages to build or depend on
72+
The `--only-main` flag can be useful if:
9073

91-
Sometimes you want to load GHCi with an additional package, that isn't a direct
92-
dependency of your components. This can be achieved by using the `--package`
93-
option. For example, if I want to experiment with the `lens` library, I can
94-
command:
74+
1. You're loading the project in order to run it in GHCi (e.g. via
75+
`main`), and you intend to reload while developing. Without flag,
76+
you will need to quit and restart GHCi whenever a module gets
77+
deleted. With the flag, reloading should work fine in this case.
9578

96-
~~~text
97-
stack ghci --package lens
98-
~~~
79+
2. If many of your modules have exports named the same thing, then
80+
you'll need to refer to them using qualified names. To avoid this,
81+
use the `--only-main` flag to start with a blank slate and just
82+
import the modules you are interested in.
9983

100-
## Specifying Cabal flags
84+
* If there are multiple definitions for the `Main` module, Stack will ask you
85+
to select one from a list of options. Pass the `--main-is <target>` option
86+
to specific which `Main` module to load.
10187

102-
`--flag <package_name>:[-]<flag_name>` sets (or unsets) the specified Cabal flag
103-
for the specified package.
88+
* Stack performs an inital build step. Pass the `--no-build` flag to skip the
89+
step.
10490

105-
This option can be specified multiple times to set (or unset) multiple Cabal
106-
flags.
91+
!!! info
10792

108-
The same Cabal flag name can be set (or unset) for multiple packages with:
93+
Not performing the initial build step speeds up the startup of GHCi. It
94+
only works if the dependencies of the loaded packages have already been
95+
built.
10996

110-
~~~text
111-
--flag *:[-]<flag_name>
112-
~~~
97+
Stack combines all of the GHC options of components.
98+
99+
!!! note
100+
101+
Combining GHC options should work out when packages share similar
102+
conventions. However, conflicts may arise, such as when one component
103+
defines default extensions which aren't assumed by another. For example,
104+
specifying `NoImplicitPrelude` in one component but not another is likely to
105+
cause failures. GHCi will be run with `-XNoImplicitPrelude`, but it is
106+
likely that modules in the other component assume that the `Prelude` is
107+
implicitly imported.
108+
109+
`stack ghci` configures GHCi by using a GHCi script file. Such files are located
110+
in subdirectories of `<XDG_CACHE_HOME>/stack/ghci-script`, where
111+
`<XDG_CACHE_HOME>` refers to the
112+
[XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)
113+
for user-specific non-essential (cached) data.
114+
115+
=== "Unix-like"
116+
117+
The default for `<XDG_CACHE_HOME>` is `$HOME/.cache`.
118+
119+
=== "Windows"
113120

114-
In order to set a Cabal flag for a GHC boot package, the package must either be
115-
an extra-dep or the package version must be specified with the `--package`
116-
option.
121+
On Windows, the default for `<XDG_CACHE_HOME>` is `%LOCALAPPDATA%`.
117122

118123
## Running plain GHCi
119124

0 commit comments

Comments
 (0)