From 07715fab8678f2831f18e58d6fbcc2e53c18ebd8 Mon Sep 17 00:00:00 2001 From: Mike Pilgrem Date: Sat, 5 Nov 2022 12:37:37 +0000 Subject: [PATCH] Improve documentation of `stack path` command --- doc/GUIDE.md | 97 ++++++++++++++++++++++++++++------------------------ 1 file changed, 53 insertions(+), 44 deletions(-) diff --git a/doc/GUIDE.md b/doc/GUIDE.md index 7ae8513832..775dcb1609 100644 --- a/doc/GUIDE.md +++ b/doc/GUIDE.md @@ -1236,60 +1236,69 @@ for more information. Generally, you don't need to worry about where Stack stores various files. But some people like to know this stuff. That's when the `stack path` command is -useful. For example, command: +useful. `stack path --help` explains the available options and, consequently, +the output of the command: ~~~text -stack path -snapshot-doc-root: ... -local-doc-root: ... -local-hoogle-root: ... -stack-root: ... -project-root: ... -config-location: ... -bin-path: ... -programs: ... -compiler-exe: ... -compiler-bin: ... -compiler-tools-bin: ... -local-bin: ... -extra-include-dirs: ... -extra-library-dirs: ... -snapshot-pkg-db: ... -local-pkg-db: ... -global-pkg-db: ... -ghc-package-path: ... -snapshot-install-root: ... -local-install-root: ... -dist-dir: ... -local-hpc-root: ... -local-bin-path: ... -ghc-paths: ... -~~~ - -In addition, `stack path` accepts command line arguments to state which of -these keys you're interested in, which can be convenient for scripting. As a +--stack-root Global Stack root directory +--project-root Project root (derived from stack.yaml file) +--config-location Configuration location (where the stack.yaml file is) +--bin-path PATH environment variable +--programs Install location for GHC and other core tools (see + 'stack ls tools' command) +--compiler-exe Compiler binary (e.g. ghc) +--compiler-bin Directory containing the compiler binary (e.g. ghc) +--compiler-tools-bin Directory containing binaries specific to a + particular compiler (e.g. intero) +--local-bin Directory where Stack installs executables (e.g. + ~/.local/bin (Unix-like OSs) or %APPDATA%\local\bin + (Windows)) +--extra-include-dirs Extra include directories +--extra-library-dirs Extra library directories +--snapshot-pkg-db Snapshot package database +--local-pkg-db Local project package database +--global-pkg-db Global package database +--ghc-package-path GHC_PACKAGE_PATH environment variable +--snapshot-install-root Snapshot installation root +--local-install-root Local project installation root +--snapshot-doc-root Snapshot documentation root +--local-doc-root Local project documentation root +--local-hoogle-root Local project documentation root +--dist-dir Dist work directory, relative to package directory +--local-hpc-root Where HPC reports and tix files are stored +--local-bin-path DEPRECATED: Use '--local-bin' instead +--ghc-paths DEPRECATED: Use '--programs' instead +--global-stack-root DEPRECATED: Use '--stack-root' instead +~~~ + +In addition, `stack path` accepts the flags above on the command line to state +which keys you're interested in. This can be convenient for scripting. As a simple example, let's find out the sandboxed versions of GHC that Stack installed: -On Unix-like operating systems, command: +=== "Unix-like" -~~~text -ls $(stack path --programs)/*.installed -/home//.stack/programs/x86_64-linux/ghc-9.0.2.installed -~~~ + Command: -On Windows (with PowerShell), command: + ~~~text + ls $(stack path --programs)/*.installed + /home//.stack/programs/x86_64-linux/ghc-9.0.2.installed + ~~~ -~~~text -dir "$(stack path --programs)/*.installed" +=== "Windows (with PowerShell)" -Directory: C:\Users\mikep\AppData\Local\Programs\stack\x86_64-windows + Command: -Mode LastWriteTime Length Name ----- ------------- ------ ---- --a--- 27/07/2022 5:40 PM 9 ghc-9.0.2.installed --a--- 25/02/2022 11:39 PM 9 msys2-20210604.installed -~~~ + ~~~text + dir "$(stack path --programs)/*.installed" + + Directory: C:\Users\mikep\AppData\Local\Programs\stack\x86_64-windows + + Mode LastWriteTime Length Name + ---- ------------- ------ ---- + -a--- 27/07/2022 5:40 PM 9 ghc-9.0.2.installed + -a--- 25/02/2022 11:39 PM 9 msys2-20210604.installed + ~~~ While we're talking about paths, to wipe our Stack install completely, here's what typically needs to be removed: