From d3ce59c1c29efdf05f5fcb9d3aefa9f89f7d4fa0 Mon Sep 17 00:00:00 2001 From: Mike Pilgrem Date: Sat, 18 May 2024 15:34:45 +0100 Subject: [PATCH] Re #5585 & #6580 Doc why `system-ghc: true` and 'hook' incompatible --- doc/yaml_configuration.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/doc/yaml_configuration.md b/doc/yaml_configuration.md index 6e2bdb9014..714883fb7f 100644 --- a/doc/yaml_configuration.md +++ b/doc/yaml_configuration.md @@ -1993,9 +1993,17 @@ The script **must** return an exit code of `0` and the standard output **must** be the absolute path to the GHC binary that was installed. Otherwise Stack will ignore the script and possibly fall back to its own installation procedure. -The script is not run when `system-ghc: true`. +When `system-ghc: true`, the script is not run. That is because the two +mechanisms reflect distinct concepts, namely: -When `install-ghc: false`, the script is still run, which allows you to ensure +* `system-ghc: true` causes Stack to search the PATH for a version of GHC; and + +* `hooks/ghc-install.sh` causes Stack to execute a script that is intended to + send to standard output a path to a version of GHC. The path in question may + or may not be in the PATH. The script may also do other things, including + installation. + +When `install-ghc: false`, the script is still run. That allows you to ensure that only your script will install GHC and Stack won't default to its own installation logic, even when the script fails.