1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
<div class="hidden-warning"><a href="https://docs.haskellstack.org/"><img src="https://cdn.jsdelivr.net/gh/commercialhaskell/stack/doc/img/hidden-warning.svg"></a></div>
# Stack work directories
Stack work directories are directories within a local project or package
directory in which Stack stores files created during the build process. Stack
can be used without an understanding of the content of those directories. In
particular, the [`stack exec`](exec_command.md) command sets up an environment
where relevant subdirectories of the project Stack work directory are on the
PATH.
## Naming
By default, Stack work directories are named `.stack-work`. The name can be
overidden by:
* the use of the
[`STACK_WORK` environment variable](environment_variables.md#stack_work);
* the [`work-dir`](yaml_configuration.md#work-dir) non-project specific
configuration option; or
* the [`--work-dir`](global_flags.md#-work-dir-option) command line option.
Given the location of Stack work directories, the name of the work directories
must be a relative path to a directory.
## Location
If the work directory does not already exist, it will be created by the
[`stack build`](build_command.md) command as a subdirectory of each project
package directory and, if different, the project directory.
## Project package Stack work directory
The Stack work directory for a project package will contain a `dist` directory.
This directory will contain a path to a directory containing:
* a `build` directory;
* a `package.conf.inplace` directory;
* a `stack-build-caches` directory;
* a `build-lock` file;
* a `setup-config` file;
* a `stack-cabal-mod` file. This file is used by Stack only for its modification
time;
* a `stack-project-root` file. This file contains an absolute path to the
project root directory; and
* a `stack-setup-config-mod` file. This file is used by Stack only for its
modification time.
The directory, relative to the project package directory or the project
directory, is the one reported by [`stack path --dist-dir`](path_command.md).
=== "Unix-like"
On Unix-like operating systems, the path to the directory is a directory
named after the platform (including Stack's classification of variants of
Linux distributions) followed by a directory named after the GHC version.
=== "Windows"
On Windows, the path to the directory is an eight-character hash of the
path that applies on Unix-like operating systems.
## Project Stack work directory
The Stack work directory for a project will contain a `install` directory.
This directory will contain a path to a directory containing:
* a `bin` directory, containing built executable files;
* a `doc` directory, containing a directory for each project package. This is
the directory reported by [`stack path --local-doc-root`](path_command.md);
* if the [`stack hpc`](hpc_command.md) command is used, a `hpc` directory. This
is the directory reported by [`stack path --local-hpc-root`](path_command.md);
* a `lib` directory, containing a directory named after the platform and the
GHC version and, within that, a directory for each project package;
* a `pkgdb` directory. This is the directory reported by
[`stack path --local-pkg-db`](path_command.md);
* a `stack.sqlite3` file; and
* a `stack.sqlite3.pantry-write-lock` file.
The directory is the one reported by
[`stack path --local-install-root`](path_command.md).
=== "Unix-like"
On Unix-like operating systems, the path to the directory is a directory
named after the platform (including Stack's classification of variants of
Linux distributions) followed by a directory named after a SHA 256 hash
(see further below) followed by a directory named after the version number
of GHC.
The SHA 256 hash is a hash of the following information:
* the path to the specified compiler;
* the information about the compiler provided by `ghc --info`;
* the options that Stack passes to GHC for package that is not a project
package; and
* information about the immutable dependencies: their location, whether or
not Haddock documentation is to be built, their flags, their GHC options,
and their Cabal configuration options.
The options that Stack passes to GHC for a package that is not a project
package depend on:
* the specification of
[profiling](https://docs.haskellstack.org/en/stable/build_command/#flags-affecting-ghcs-behaviour);
* the specification of
[stripping](https://docs.haskellstack.org/en/stable/build_command/#flags-affecting-ghcs-behaviour); and
* if
[`apply-ghc-options: everything`](yaml_configuration.md#apply-ghc-options)
is specified, any GHC command line options specified on the command line.
!!! note
As a consequence, the path reported by the following commands will
differ (and similarly for the paths established by the
[`stack exec`](exec_command.md) command):
~~~text
stack path --local-install-root
stack --profile path --local-install-root
stack --no-strip path --local-install-root
stack --profile --no-strip path --local-install-root
~~~
=== "Windows"
On Windows, the path to the directory is an eight-character hash of the
path that applies on Unix-like operating systems.
Following a `stack ghci` or `stack repl` command, the Stack work directory for
a project will contain a `ghci` directory. This directory will contain paths to
`cabal_macos.h` files that are generated automatically by Cabal.
!!! note
Haskell Language Server makes use of the `stack ghci` command to obtain
information.
If the [`stack hoogle`](hoogle_command.md) command is used, the Stack work
directory for a project will contain a `hoogle` directory. This directory will
contain a directory being the one reported by
[`stack path --local-hoogle-root`](path_command.md). The naming of the path to
the directory is same as for the path to the directory in the `install`
directory.
|
