Skip to content

Commit 31c0154

Browse files
mpilgremmpilgrem
committed
Document Stack work directories
1 parent 7ced7b4 commit 31c0154

File tree

3 files changed

+146
-0
lines changed

3 files changed

+146
-0
lines changed

‎doc/stack_work.md

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

‎mkdocs.yml

+1
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,7 @@ nav:
8888
- Travis CI: travis_ci.md
8989
- Azure CI: azure_ci.md
9090
- Lock files: lock_files.md
91+
- Stack work directories: stack_work.md
9192
- How Stack works (advanced):
9293
- Build overview: build_overview.md
9394
- Stack's code (advanced):

‎stack.cabal

+1
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,7 @@ extra-source-files:
8585
doc/SIGNING_KEY.md
8686
doc/Stack_and_VS_Code.md
8787
doc/stack_root.md
88+
doc/stack_work.md
8889
doc/stack_yaml_vs_cabal_package_file.md
8990
doc/templates_command.md
9091
doc/travis_ci.md

0 commit comments

Comments
 (0)