Merge pull request #5740 from mpilgrem/msys2Docs

Update MSYS2-related documentation

Author: mpilgrem

doc/GUIDE.md

@@ -15,7 +15,7 @@ note on [issue #4252](https://github.com/commercialhaskell/stack/issues/4252).
 ## Stack's functions
 
 stack handles the management of your toolchain (including GHC — the Glasgow
-Haskell Compiler — and, for Windows users, MSYS), building and registering
+Haskell Compiler — and, for Windows users, MSYS2), building and registering
 libraries, building build tool dependencies, and more. While it can use existing
 tools on your system, stack has the capacity to be your one-stop shop for all
 Haskell tooling you need. This guide will follow that stack-centric approach.
@@ -1402,7 +1402,7 @@ is that it's the catch-all project whenever you're running stack somewhere else.
 `stack path --stack-root` will tell you the location of the 'stack root'. This
 is where stack stores snapshot packages, among other things. On operating
 systems other than Windows, it is also where stack stores tools such as ghc and
-msys by default, in a `programs` folder. (On Windows, the default location for
+MSYS2 by default, in a `programs` folder. (On Windows, the default location for
 such tools is `%LOCALAPPDATA%\Programs\stack`.)
 
 The location of the stack root can be configured by setting the `STACK_ROOT`

doc/developing_on_windows.md

@@ -3,7 +3,7 @@
 # Developing on windows #
 
 On Windows, Stack comes with an installation of
-[msys2](https://www.msys2.org/). Msys2 will be used by Stack to
+[MSYS2](https://www.msys2.org/). MSYS2 will be used by Stack to
 provide a unix-like shell for Stack. This may be necessary for installing some Haskell packages, such as those which use `configure` scripts.
 No
 matter which terminal you choose (cmd.exe, powershell, git bash or any
@@ -38,7 +38,7 @@ additional entries via a pull request.
 Cmake has trouble finding other tools even if they are available on
 the `PATH`. Likely this is not a cmake problem but one of the
 environment not fully integrating. For example GHC comes with a copy
-of GCC which is not installed by msys itself. If you want to use this
+of GCC which is not installed by MSYS2 itself. If you want to use this
 GCC you can provide a full path to it, or find it first with
 `System.Directory.findExecutable` if you want to launch GCC from a
 Haskell file such as `Setup.hs`.

doc/maintainers/msys.md

@@ -1,31 +1,82 @@
 <div class="hidden-warning"><a href="https://docs.haskellstack.org/"><img src="https://cdn.jsdelivr.net/gh/commercialhaskell/stack/doc/img/hidden-warning.svg"></a></div>
 
-# Upgrading msys
+# Upgrading MSYS2
 
 When installing GHC on Windows, Stack will also install
-[msys2](http://www.msys2.org/) to provide a Unix shell and environment,
-necessary for such things as running configure scripts. This section explains
-the steps required to upgrade the msys2 version used by Stack.
+[MSYS2](http://www.msys2.org/). MSYS2 provides a Unix shell and environment, and
+is necessary for such things as running configure scripts. This section explains
+the steps required to upgrade the MSYS2 version used by Stack.
 
-1.  Download latest installers from msys2's website. These installers are
-    executables, versioned by date (YYYYMMDD), and are separate for `x86_64`
-    and `i686`. You'll usually be upgrading both at the same time, which we'll
-    assume here.
+1.  Download latest installer(s) from MSYS2's website. Historically, there were
+    separate installers for 32 bit (`i686`) and 64 bit (`x86_64`). On
+    17 May 2020, the MSYS2 project announced it did not plan to release any
+    further `i686` installers. An installer is an executable, versioned by a
+    date in the format YYYYMMDD - for example, `msys2-x86_64-20220503.exe`.
 
-2.  Run the installer and install to the default location (`c:\msys64` and
-    `c:\msys32`, respectively).
+2.  Run the installer and install to the default location (`C:\msys64` for the
+    64 bit version; the location for the 32 bit version was `C:\msys32`). Do not
+    use the installed version; it will create a `.bash_history` file if you do.
 
-3.  Create tarballs for each directory:
+3.  Create a tarball for each relevant directory (eg `C:\msys64`). That requires
+    a version of [`tar`](https://www.gnu.org/software/tar/tar.html) that
+    supports the compression option `--xz`. The version of `tar` that is
+    supplied with Windows (`C:\Windows\System32\tar.exe`) does not support that
+    option, but MSYS2 can supply a [version](https://packages.msys2.org/package/tar)
+    that does (using its `pacman` tool). Using the existing Stack-supplied
+    MSYS2, in PowerShell and located in a folder with write permissions (so the `.tar.xz` file can be created):
 
     ```
-    $ cd /c/
-    $ tar cJf msys2-YYYYMMDD-x86_64.tar.xz msys64
-    $ tar cJf msys2-YYYYMMDD-i686.tar.xz msys32
+    > stack exec -- pacman -S tar
+    > stack exec -- tar cJf msys2-YYYYMMDD-x86_64.tar.xz C:\msys64
     ```
 
-4.  Create a new release named `msys2-YYYYMMDD` on the
-    [fpco/stackage-content](https://github.com/fpco/stackage-content)
-    repo, and upload these two files.
+4.  Create a new release tagged and named `msys2-YYYYMMDD` in the `master`
+    branch of the [commercialhaskell/stackage-content](https://github.com/commericalhaskell/stackage-content)
+    GitHub repository, uploading the tarball file(s) into that release.
 
-5.  Create a PR for the [stack-setup-2.yaml file](https://github.com/fpco/stackage-content/blob/master/stack/stack-setup-2.yaml)
-    to switch over to using the newly uploaded files. You should test this file locally first.
+5.  Changes need to be made to the [stackage-content/stack/stack-setup-2.yaml](https://github.com/commercialhaskell/stackage-content/blob/master/stack/stack-setup-2.yaml)
+    file, to switch over to using the newly uploaded files. For example
+    (extract):
+
+    ~~~yaml
+    # For upgrade instructions, see: https://github.com/commercialhaskell/stack/blob/stable/doc/maintainers/msys.md
+    msys2:
+        windows32:
+            version: "20200517"
+            url: "https://github.com/fpco/stackage-content/releases/download/20200517/msys2-20200517-i686.tar.xz"
+            content-length: 79049224
+            sha256: 9152ddf50c6bacfae33c1436338235f8db4b10d73aaea63adefd96731fb0bceb
+        windows64:
+            version: "20220503"
+            url: "https://github.com/commercialhaskell/stackage-content/releases/download/msys2-20220503/msys2-20220503-x86_64.tar.xz"
+            content-length: 93835868
+            sha256: c918f66e984f70add313ee3a5c5b101132cd93d5a3f8e3555e129e2d3dcb3718
+    ~~~
+
+    The `content-length:` key's value is the size of the file in bytes. It can
+    be obtained from the `Length` field of the `dir` command. The `sha256:`
+    key's value can be obtained from the command (in PowerShell):
+
+    ~~~
+    ❯ (Get-FileHash msys2-YYYYMMDD-x86_64.tar.xz -Algorithm SHA256).Hash.ToLower()
+    ~~~
+
+    The `sha256:` key only accepts lowercase hash results as values.
+
+6.  The changed `stack-setup-2.yaml` file should be tested locally. This can be
+    done by:
+
+    * temporarily disabling the existing local copy of MSYS2 by changing the
+      name of the `msys2-YYYYMMDD.installed` file in the `stack path --programs` directory; and
+
+    * executing the command:
+
+      ~~~
+      > stack setup --setup-info-yaml <path to local copy of stack-setup-2.yaml>
+      ~~~
+
+    If all is well, the command should proceed to download the updated version
+    of MSYS2 that has been specified.
+
+7.  Raise a pull request on `commercialhaskell/stackage-contents` for the
+    changes to the locally-tested `stack-setup-2.yaml` file.

doc/maintainers/releases.md

@@ -339,7 +339,10 @@ Now continue to the **General Windows setup** subsection below.
 
 15. Run `C:\p\env.bat` (do this every time you open a new command prompt)
 
-16. `stack exec -- gpg --import`, and paste in the your GPG secret key (must be done using `stack exec` because that uses the right keyring for the embedded msys GPG; you can get the key from another machine with `gpg --export-secret-keys --armor <KEY ID>`)
+16. `stack exec -- gpg --import`, and paste in the your GPG secret key (must be
+    done using `stack exec` because that uses the right keyring for the embedded
+    MSYS2 GPG; you can get the key from another machine with
+    `gpg --export-secret-keys --armor <KEY ID>`)
 
 17. Run in command prompt (adjust the `user.email` and `user.name` settings):
 

doc/yaml_configuration.md

@@ -718,7 +718,7 @@ ghc:
 
 (Since 0.1.5)
 
-Allows augmenting from where tools like GHC and msys2 (on Windows) are
+Allows augmenting from where tools like GHC and MSYS2 (on Windows) are
 downloaded. Most useful for specifying locations of custom GHC binary
 distributions (for use with the [ghc-variant](#ghc-variant) option).
 
@@ -1013,7 +1013,7 @@ Since 0.1.10.0
 
 ### skip-msys
 
-Skips checking for and installing msys2 when stack is setting up the
+Skips checking for and installing MSYS2 when stack is setting up the
 environment.  This is only useful on Windows machines, and usually doesn't make
 sense in project configurations, just in `config.yaml`.  Defaults to `false`, so
 if this is used, it only really makes sense to use it like this:
@@ -1061,7 +1061,7 @@ Since 0.1.4.0
 ### local-programs-path
 
 This overrides the location of the programs directory, where tools like ghc and
-msys get installed.
+MSYS2 get installed.
 
 On most systems, this defaults to a folder called `programs`
 within the stack root directory. On Windows, if the `LOCALAPPDATA` environment

mkdocs.yml

@@ -44,7 +44,7 @@ pages:
     - Maintainer team process: maintainers/team_process.md
     - Add GHC version: maintainers/ghc.md
     - Docker images: maintainers/docker.md
-    - Upgrading msys: maintainers/msys.md
+    - Upgrading MSYS2: maintainers/msys.md
   - Signing key: SIGNING_KEY.md
 
 markdown_extensions: