From 44c1e91d79cb2595fdd0a713da4172ab140ff7e8 Mon Sep 17 00:00:00 2001 From: Mike Pilgrem Date: Fri, 6 Oct 2023 22:35:57 +0100 Subject: [PATCH] Fix #6271 Document Stack root contents --- doc/stack_root.md | 167 +++++++++++++++++++++++++++++++++++++++------- 1 file changed, 143 insertions(+), 24 deletions(-) diff --git a/doc/stack_root.md b/doc/stack_root.md index 32224ac63d..65b4dd59a5 100644 --- a/doc/stack_root.md +++ b/doc/stack_root.md @@ -1,12 +1,20 @@
-# Stack root location +# Stack root -The Stack root is a directory where Stack stores important files. The location -and contents of the directory depend on the operating system, whether -Stack is configured to use the XDG Base Directory Specification, and/or -whether an alternative location to Stack's default 'programs' directory has -been specified. +The Stack root is a directory where Stack stores important files. + +On Unix-like operating systems and Windows, Stack can be configured to follow +the XDG Base Directory Specification if the environment variable `STACK_XDG` is +set to any non-empty value. However, Stack will ignore that configuration if the +Stack root location has been set on the command line or the `STACK_ROOT` +environment variable exists. + +## Location + +The location of the Stack root depends on the operating system, whether Stack is +configured to use the XDG Base Directory Specification, and/or whether an +alternative location to Stack's default 'programs' directory has been specified. The location of the Stack root can be configured by setting the [`STACK_ROOT`](environment_variables.md#stack_root) environment variable or @@ -25,13 +33,6 @@ command line. === "Windows" - The Stack root contains snapshot packages; Stack's global - [YAML configuration](yaml_configuration.md#yaml-configuration) file - (`config.yaml`); and Stack's - [`global-projects`](yaml_configuration.md#yaml-configuration) directory. The - default location of tools such as GHC and MSYS2 is outside of the Stack - root. - The default Stack root is `%APPDIR%\stack`. If the `LOCALAPPDATA` environment variable exists, the default location of @@ -60,17 +61,6 @@ command line. === "XDG Base Directory Specification" - On Unix-like operating systems and Windows, Stack can be configured to - follow the XDG Base Directory Specification if the environment variable - `STACK_XDG` is set to any non-empty value. However, Stack will ignore that - configuration if the Stack root location has been set on the command line or - the `STACK_ROOT` environment variable exists. - - If Stack is following the XDG Base Directory Specification, the Stack root - contains what it would otherwise contain for the operating system, but - Stack's global YAML configuration file (`config.yaml`) may be located - elsewhere. - The Stack root is `/stack`. If the `XDG_DATA_HOME` environment variable does not exist, the default is `~/.local/share/stack` on Unix-like operating systems and `%APPDIR%\stack` on Windows. @@ -117,3 +107,132 @@ command: ~~~text stack path --programs ~~~ + +## Contents + +The contents of the Stack root depend on the operating system, whether Stack is +configured to use the XDG Base Directory Specification, and/or whether an +alternative location to Stack's default 'programs' directory has been specified. + +=== "Unix-like" + + The Stack root contains snapshot packages; (by default) tools such as GHC, + in a `programs` directory; Stack's global + [YAML configuration](yaml_configuration.md#yaml-configuration) file + (`config.yaml`); and Stack's + [`global-projects`](yaml_configuration.md#yaml-configuration) directory. + +=== "Windows" + + The Stack root contains snapshot packages; Stack's global + [YAML configuration](yaml_configuration.md#yaml-configuration) file + (`config.yaml`); and Stack's + [`global-projects`](yaml_configuration.md#yaml-configuration) directory. The + default location of tools such as GHC and MSYS2 is outside of the Stack + root. + +=== "XDG Base Directory Specification" + + If Stack is following the XDG Base Directory Specification, the Stack root + contains what it would otherwise contain for the operating system, but + Stack's global YAML configuration file (`config.yaml`) may be located + elsewhere. + +### `config.yaml` + +This is Stack's global configuration file. For further information, see the +documentation for non-project specific +[configuration](yaml_configuration.md#non-project-specific-configuration). + +If the file is deleted, and Stack needs to consult it, Stack will create a file +with default contents. + +### `stack.sqlite3` + +This is a 'user' database that Stack uses to cache certain information. The +associated lock file is `stack.sqlite3.pantry-write-lock`. + +### `global-project` directory + +This contains: + +* an explanation of the directory (`README.txt`); +* the project-level configuration file (`stack.yaml`) for the global project + and its associated lock file (`stack.yaml.lock`); and +* if created, Stack's working directory (`.stack-work`) for the global project. + +If the project-level configuration file is deleted, and Stack needs to consult +it, Stack will recreate the contents of the directory. + +### `pantry\hackage` directory + +This contains the package index. If the contents of the directory are deleted, +and Stack needs to consult the package index, Stack will seek to download the +latest package index. + +### `pantry` directory + +This contains: + +* the Pantry database used by Stack (`pantry.sqlite3`) and its associated lock + file (`pantry.sqlite2.pantry-write-lock`). If the database is deleted, and + Stack needs to consult it, Stack will seek to create and initialise it. The + database is initialised with information from the package index; and +* a database of package versions that come with each version of GHC + (`global-hints-cache.yaml`). + +### `programs` directory + +This contains a directory for the platform. That directory contains for each +installed Stack-supplied tool: + +* the archive file for the tool. This can be deleted; +* a file indicating the tool is installed (`.installed`); and +* a directory for the tool. + +To remove a Stack-supplied tool, delete all of the above. If Stack needs a +Stack-supplied tool and it is unavailable, Stack will seek to obtain it. + +### `setup-exe-cache` directory + +This contains a directory for the platform. That directory contains, for each +version of GHC (an associated version of Cabal (the library)) that Stack has +used, an executable that Stack uses to access Cabal (the library). + +If the contents of the directory are deleted, and Stack needs the executable, +Stack will seek to rebuild it. + +### `setup-exe-src` directory + +See the documentation for the +[`setup-exe-cache` directory](#setup-exe-cache-directorysetup-exe-cache). This +contains: + +* the two source files (`setup-.hs` and `setup-shim-.hs`) that Stack + uses to build the executable; and +* associated GHC build artefacts (`*.hi` and `*.o` files). + +If the contents of the directory are deleted, and Stack needs the executable, +Stack will recreate them. + +### `snapshots` directory + +This contains a directory for each snapshot that Stack creates when building +immutable dependencies of projects. + +If the contents of the directory are deleted, and the snapshot is not available +to Stack when it builds, Stack will recreate the snapshot. + +### `templates` directory + +This contains a `.hsfile` for each project template that Stack has used. For +further information, see the [`stack templates`](templates_command.md) command +documentation. + +If the contents of the directory are deleted, an Stack needs a project template, +Stack will seek to download the template. + +### `upload` directory + +This may contain saved credentials for uploading packages to Hackage +(`credentials.json`).