From af4a1ac7e58d2f839d7bfcac55ccba717d00b068 Mon Sep 17 00:00:00 2001 From: Mike Pilgrem Date: Wed, 1 Oct 2025 20:38:20 +0100 Subject: [PATCH] Improve documentation related to Stack hooks Reorganises the existing 'Stack hooks' content to bring forward how to get the hook (using the recommended method). In three relevant places, tells users that the commands to install GHCup and the Haskell Toolchain can safely be run again at any time. Introduces that the commands to install GHCup and the Haskell Toolchain use a `sh` script (true on all platforms). Makes the steps to get the Stack hook manually relevant to all operating systems (not just Unix-like ones). Updates the text for the passage of time: e.g. Stack 2.9.1 is no longer 'new'. Uses language about Stack that is closer to the language that Stack's online documentation uses about itself. Also fixes a closing

tag (present as

). --- docs/guide.md | 72 +++++++++++++++++++++++++++++++------------------ docs/index.md | 5 +++- docs/install.md | 4 ++- 3 files changed, 53 insertions(+), 28 deletions(-) diff --git a/docs/guide.md b/docs/guide.md index d35908c..acdd85f 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -316,40 +316,60 @@ git pull --ff-only origin master ## Stack integration -Stack manages GHC versions internally by default. In order to make it use ghcup installed -GHC versions there are two strategies. - -### Strategy 1: Stack hooks (new, recommended) - -Since stack 2.9.1 you can customize the installation logic of GHC completely, see -[https://docs.haskellstack.org/en/stable/configure/customisation_scripts/#ghc-installation-customisation](https://docs.haskellstack.org/en/stable/configure/customisation_scripts/#ghc-installation-customisation). - -We can use this to simply invoke ghcup whenever stack is trying to install/discover a GHC versions. This -is done via placing a shell script at `~/.stack/hooks/ghc-install.sh` and making it executable. +By default, Stack tries to manage GHC versions itself. However, Stack can use +GHC versions installed by GHCup. There are two strategies for doing so. + +### Strategy 1 (recommended): Hook up Stack to use GHCup + +Stack (since v2.9.1) can be configured to try to use GHCup to manage GHC +versions, using a 'hook'. + +The commands to [install GHCup and the Haskell Toolchain](install.md) include an +option to create that hook. That is the recommended way to do so. They can +safely be run again at any time. + +A hook can also be created manually, by placing a suitable `sh` script named +`ghc-install.sh` in a `hooks` directory in the Stack root. On Unix-like +operating systems, the script file should be marked as executable. + +You can create a hook manually with the following steps: + +```text +# Change to the Stack root directory: +stack path --stack-root | cd +# Make a hooks directory (if it does not exist): +mkdir hooks +# Change to that hooks directory: +cd hooks +# Download GHCup's ghc-install.sh file: +curl -O https://raw.githubusercontent.com/haskell/ghcup-hs/master/scripts/hooks/stack/ghc-install.sh +# On Unix-like operating systems only, mark file as executable: +chmod +x ghc-install.sh +# Hooks are only run when 'system-ghc: false' (Stack's default): +stack config set system-ghc false --global +``` -The ghcup bootstrap script asks you during installation whether you want to install this shell script. You can also -install/update it manually like so: +If the hook fails, by default, Stack will try to manage GHC versions itself. +Stack can be configured not to do that for any project (globally). To do so, +command: -```sh -mkdir -p ~/.stack/hooks/ -curl https://raw.githubusercontent.com/haskell/ghcup-hs/master/scripts/hooks/stack/ghc-install.sh \ - > ~/.stack/hooks/ghc-install.sh -chmod +x ~/.stack/hooks/ghc-install.sh -# hooks are only run when 'system-ghc: false' -stack config set system-ghc false --global +```text +stack config set install-ghc false --global ``` -By default, when the hook fails for whatever reason, stack will fall back to its own installation logic. To disable -this, run `stack config set install-ghc false --global`. +For more information about Stack hooks, see Stack's +[GHC installation customisation](https://docs.haskellstack.org/en/stable/configure/customisation_scripts/#ghc-installation-customisation) +documentation. -### Strategy 2: System GHC (works on all stack versions) +### Strategy 2 (alternative): Use only GHC on the PATH -You can instruct stack to use "system" GHC versions (whatever is in PATH). To do so, -run the following commands: +Stack can be configured for all projects (globally) to try to use the 'system' +GHC on the PATH (including one installed by GHCup) and not to try to manage GHC +versions itself. To do so, command: -```sh +```text +stack config set system-ghc true --global stack config set install-ghc false --global -stack config set system-ghc true --global ``` ### Using stack's setup-info metadata to install GHC diff --git a/docs/index.md b/docs/index.md index 596f505..0a535fb 100644 --- a/docs/index.md +++ b/docs/index.md @@ -37,7 +37,7 @@ hide:

To install on Windows

-

run the following in a PowerShell session (as a non-admin user):

+

run the following in a PowerShell session (as a non-admin user):

@@ -49,6 +49,9 @@ hide:
 	

 		What does this do?  ·  I don't like curl | sh 
 ·  Show all platforms
 ·  System requirements

 	

+  

+    
These commands can safely be run again at any time.

+
diff --git a/docs/install.md b/docs/install.md index d86d91e..3650e23 100644 --- a/docs/install.md +++ b/docs/install.md @@ -6,10 +6,12 @@ It follows the UNIX philosophy of [do one thing and do it well](https://en.wikip ## How to install -The following commands will download the `ghcup` binary into `~/.ghcup/bin` (or `C:\ghcup\bin` on windows) and then +The following commands will use a `sh` script to download the `ghcup` binary into `~/.ghcup/bin` (or `C:\ghcup\bin` on windows) and then run it to interactively install the [Haskell Toolchain](#supported-tools). These commands should be run as **non-root/non-admin user**. +These commands can safely be run again at any time. + For Linux, macOS, FreeBSD or Windows Subsystem 2 for Linux, run this in a terminal: ```sh