Skip to content

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 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:

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 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.

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.

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 stack.sqlite3 file (being a SQLite v3 database); and
  • a stack.sqlite3.pantry-write-lock file (used to ensure that only one process is trying to write to the database at any time).

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;
  • if the stack hpc command is used, a hpc directory. This is the directory reported by stack path --local-hpc-root;
  • a lib directory, containing a directory named after the platform and the GHC version and, within that, a directory for each project package; and
  • a pkgdb directory. This is the directory reported by stack path --local-pkg-db.

The directory is the one reported by stack path --local-install-root.

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:

Note

As a consequence, the path reported by the following commands will differ (and similarly for the paths established by the stack exec command):

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

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 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. The naming of the path to the directory is same as for the path to the directory in the install directory.