Merge branch 'stable'

doc/commands/build_command.md

@@ -614,7 +614,9 @@ command line arguments. For example, to pass `'a single quoted string'`:
     The content of single quotes is taken literally. Within single quotes, `''`
     escapes a single quote.
 
-=== "Windows (PowerShell)"
+=== "Windows"
+
+    In PowerShell:
 
     `stack bench --benchmark-arguments '"''a single quoted string''"'`
 
@@ -650,7 +652,9 @@ command line arguments. For example, to pass `'a single quoted string'`:
     The content of single quotes is taken literally. Within single quotes, `''`
     escapes a single quote.
 
-=== "Windows (PowerShell)"
+=== "Windows"
+
+    In PowerShell:
 
     `stack build --exec '<command> "''a single quoted string''"'`
 
@@ -687,7 +691,9 @@ command line arguments. For example, to pass `'a single quoted string'`:
     The content of single quotes is taken literally. Within single quotes, `''`
     escapes a single quote.
 
-=== "Windows (PowerShell)"
+=== "Windows"
+
+    In PowerShell:
 
     `stack test --test-arguments '"''a single quoted string''"'`
 

doc/commands/exec_command.md

@@ -58,7 +58,9 @@ command line arguments. For example, to pass `'a single quoted string'`:
     The content of single quotes is taken literally. Within single quotes, `''`
     escapes a single quote.
 
-=== "Windows (PowerShell)"
+=== "Windows"
+
+    In PowerShell:
 
     `stack exec <command> -- '''a single quoted string'''`
 

doc/commands/ghci_command.md

@@ -132,6 +132,10 @@ for user-specific non-essential (cached) data.
 
 === "Windows"
 
+     On Windows, the default for `<XDG_CACHE_HOME>` is `$Env:LOCALAPPDATA`.
+
+=== "Windows (Command Prompt)"
+
      On Windows, the default for `<XDG_CACHE_HOME>` is `%LOCALAPPDATA%`.
 
 ## Running plain GHCi

doc/commands/upload_command.md

@@ -101,14 +101,22 @@ example:
     stack upload .
     ~~~
 
-=== "Windows (with PowerShell)"
+=== "Windows"
 
     ~~~text
     $Env:HACKAGE_USERNAME='<username>'
     $Env:HACKAGE_PASSWORD='<password>'
     stack upload .
     ~~~
 
+=== "Windows (Command Prompt)"
+
+    ~~~text
+    set HACKAGE_USERNAME=<username>
+    set HACKAGE_PASSWORD=<password>
+    stack upload .
+    ~~~
+
 ## The `HACKAGE_KEY` environment variable
 
 [:octicons-tag-24: 2.7.5](https://github.com/commercialhaskell/stack/releases/tag/v2.7.5)
@@ -127,9 +135,16 @@ example:
      stack upload .
      ~~~
 
-=== "Windows (with PowerShell)"
+=== "Windows"
 
      ~~~text
      $Env:HACKAGE_KEY=<api_authentification_token>
      stack upload .
      ~~~
+
+=== "Windows (Command Prompt)"
+
+     ~~~text
+     set HACKAGE_KEY=<api_authentification_token>
+     stack upload .
+     ~~~

doc/configure/environment_variables.md

@@ -41,13 +41,20 @@ example:
      stack upload .
      ~~~
 
-=== "Windows (with PowerShell)"
+=== "Windows"
 
      ~~~text
      $Env:HACKAGE_KEY=<api_authentification_token>
      stack upload .
      ~~~
 
+=== "Windows (Command Prompt)"
+
+     ~~~text
+     set HACKAGE_KEY=<api_authentification_token>
+     stack upload .
+     ~~~
+
 ## `HACKAGE_USERNAME` and `HACKAGE_PASSWORD`
 
 [:octicons-tag-24: 2.3.1](https://github.com/commercialhaskell/stack/releases/tag/v2.3.1)
@@ -67,14 +74,22 @@ example:
     stack upload .
     ~~~
 
-=== "Windows (with PowerShell)"
+=== "Windows"
 
     ~~~text
     $Env:HACKAGE_USERNAME='<username>'
     $Env:HACKAGE_PASSWORD='<password>'
     stack upload .
     ~~~
 
+=== "Windows (Command Prompt)"
+
+    ~~~text
+    set HACKAGE_USERNAME=<username>
+    set HACKAGE_PASSWORD=<password>
+    stack upload .
+    ~~~
+
 ## `NO_COLOR`
 
 Related command: all commands that can produce colored output using control

doc/configure/yaml/non-project.md

@@ -924,7 +924,28 @@ Stack's defaults differ between Unix-like operating systems and Windows.
 
 === "Windows"
 
-    Default: `%LOCALAPPDATA%\Programs\stack`, if the `%LOCALAPPDATA%`
+    Default: `$Env:LOCALAPPDATA\Programs\stack`, if the `LOCALAPPDATA`
+    environment variable exists. Otherwise, the `programs` directory in the
+    [Stack root](../../topics/stack_root.md).
+
+    The MSYS2 tool is also installed in the Stack 'programs' directory.
+
+    !!! warning
+
+        If there is a space character in the path to Stack's 'programs'
+        directory this may cause problems with building packages that make use
+        of the GNU project's `autoconf` package and `configure` shell script
+        files. That may be the case particularly if there is no corresponding
+        short name ('8 dot 3' name) for the directory in the path with the space
+        (which may be the case if '8 dot 3' names have been stripped or their
+        creation not enabled by default). If there are problems building, it
+        will be necessary to specify an alternative path that does not contain
+        space characters. Examples of packages on Hackage that make use of
+        `configure` are `network` and `process`.
+
+=== "Windows (Command Prompt)"
+
+    Default: `%LOCALAPPDATA%\Programs\stack`, if the `LOCALAPPDATA`
     environment variable exists. Otherwise, the `programs` directory in the
     [Stack root](../../topics/stack_root.md).
 

doc/configure/yaml/project.md

@@ -290,15 +290,14 @@ For example, a user-message is inserted by `stack init` when it omits packages
 or adds external dependencies, namely:
 
 ~~~yaml
-user-message: ! 'Warning: Some packages were found to be incompatible with the resolver
-  and have been left commented out in the packages section.
+user-message: |
+  Warning (added by new or init): Some packages were found to be incompatible
+  with the snapshot and have been left commented out in the packages section.
 
-  Warning: Specified resolver could not satisfy all dependencies. Some external packages
-  have been added as dependencies.
+  Warning (added by new or init): Specified snapshot could not satisfy all
+  dependencies. Some external packages have been added as dependencies.
 
   You can omit this message by removing it from stack.yaml
-
-'
 ~~~
 
 ## custom-preprocessor-extensions

doc/faq.md

@@ -125,9 +125,9 @@
 
     ~~~text
     myproject/
-      stack-ghc-9.0.2.yaml
-      stack-ghc-9.2.4.yaml
-      stack.yaml --> symlink to stack-ghc-9.2.4.yaml
+      stack-ghc-9.6.6.yaml
+      stack-ghc-9.8.2.yaml
+      stack.yaml --> symlink to stack-ghc-9.6.6.yaml
       myproject.cabal
       src/
         ...
@@ -138,16 +138,22 @@
 
     === "Unix-like"
 
-        ~~~bash
-        stack build  # builds using the default stack.yaml
-        STACK_YAML=stack-ghc-7.10.yaml
-        stack build  # builds using the given yaml file
+        ~~~text
+        STACK_YAML=stack-ghc-9.8.2.yaml
+        stack build
         ~~~
 
-    === "Windows (with PowerShell)"
+    === "Windows"
 
-        ~~~ps
-        $Env:STACK_YAML='stack-ghc-9.0.2.yaml'
+        ~~~text
+        $Env:STACK_YAML='stack-ghc-9.8.2.yaml'
+        stack build
+        ~~~
+
+    === "Windows (Command Prompt)"
+
+        ~~~text
+        set STACK_YAML=stack-ghc-9.8.2.yaml
         stack build
         ~~~
 
@@ -181,9 +187,9 @@
 
 ??? question "On Windows, `stack setup` tells me to add certain paths to the PATH instead of doing it?"
 
-    With PowerShell, it is easy to automate even that step. Command:
+    In PowerShell, it is easy to automate even that step. Command:
 
-    ~~~ps
+    ~~~text
     $Env:Path = ( stack setup | %{ $_ -replace '[^ ]+ ', ''} ), $Env:Path -join ";"
     ~~~
 

doc/install_and_upgrade.md

@@ -47,6 +47,20 @@ used, it sets other things up as needed.
 
         Stack installs executables to:
 
+        ~~~text
+        $Env:APPDATA\local\bin
+        ~~~
+
+        For example: `C:\Users\<user-name>\AppData\Roaming\local\bin`.
+
+        If you don't have that directory in your PATH, you may need to update
+        your PATH. That can be done by searching for 'Edit Environment variables
+        for your account' under Start.
+
+    === "Windows (Command Prompt)"
+
+        Stack installs executables to:
+
         ~~~text
         %APPDATA%\local\bin
         ~~~
@@ -736,6 +750,19 @@ Stack can be installed directly or by using the GHCup tool.
         'http proxy setting' in your Control Panel would not result in Stack
         traffic going through the proxy.
 
+    === "Windows (Command Prompt)"
+
+        ~~~text
+        set http_proxy=IP:PORT
+        stack install
+        ~~~
+
+        It is not mandatory for programs to follow the 'system-wide' HTTP proxy.
+        Some programs, such as browsers, do honor this 'system-wide' HTTP proxy
+        setting, while other programs do not. That means configuring
+        'http proxy setting' in your Control Panel would not result in Stack
+        traffic going through the proxy.
+
 ## Upgrade Stack
 
 The Stack project recommends the use of the latest released version of Stack.

doc/maintainers/releases.md

@@ -463,12 +463,14 @@ final release.
             git shortlog -s origin/release..HEAD|sed 's/^[0-9 \t]*/* /'|LC_ALL=C sort -f
             ~~~
 
-        === "Windows (with PowerShell)"
+        === "Windows"
 
             ~~~text
             (git shortlog -s origin/release..HEAD) -Replace '^[0-9 \t]*', '* ' | Sort-Object
             ~~~
 
+            in PowerShell.
+
     Publish the GitHub release.
 
     ### D: Consider adding other platforms to the GitHub release
@@ -598,7 +600,7 @@ final release.
         curl -vL https://get.haskellstack.org/upgrade/linux-x86_64.tar.gz >/dev/null
         ~~~
 
-    === "Windows (with PowerShell)"
+    === "Windows"
 
         ~~~text
         curl -vL https://get.haskellstack.org/stable/linux-x86_64.tar.gz >NUL

doc/topics/scripts.md

@@ -56,7 +56,7 @@ main = echo "Hello World!"
     stack turtle-example.hs
     ~~~
 
-=== "Windows (with PowerShell)"
+=== "Windows"
 
     The first line beginning with the 'shebang' (`#!`) has a meaning on
     Unix-like operating systems but will be ignored by PowerShell. It can be

doc/topics/stack_root.md

@@ -34,6 +34,34 @@ command line.
 
 === "Windows"
 
+    The default Stack root is `$Env:APPDIR\stack`.
+
+    If the `LOCALAPPDATA` environment variable exists, then the default location
+    of tools is `$Env:LOCALAPPDATA\Programs\stack`. Otherwise, it is the
+    `programs` directory in the Stack root.
+
+    !!! warning
+
+        If there is a space character in the `$Env:LOCALAPPDATA` path (which may
+        be the case if the relevant user account name and its corresponding user
+        profile path have a space) this may cause problems with building
+        packages that make use of the GNU project's `autoconf` package and
+        `configure` shell script files. That may be the case particularly if
+        there is no corresponding short name ('8 dot 3' name) for the directory
+        in the path with the space (which may be the case if '8 dot 3' names
+        have been stripped or their creation not enabled by default). If there
+        are problems building, it will be necessary to override the default
+        location of Stack's 'programs' directory to specify an alternative path
+        that does not contain space characters. Examples of packages on
+        Hackage that make use of `configure` are `network` and `process`.
+
+    On Windows, the length of filepaths may be limited (to
+    [MAX_PATH](https://docs.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=cmd)),
+    and things can break when this limit is exceeded. Setting a Stack root with
+    a short path to its location (for example, `C:\sr`) can help.
+
+=== "Windows (Command Prompt)"
+
     The default Stack root is `%APPDIR%\stack`.
 
     If the `LOCALAPPDATA` environment variable exists, then the default location

doc/tutorial/building_existing_projects.md

@@ -133,7 +133,9 @@ it. You may see something like this:
 
 ~~~text
 stack build
-Warning: Some packages were found to be incompatible with the resolver and have been left commented out in the packages section.
-Warning: Specified resolver could not satisfy all dependencies. Some external packages have been added as dependencies.
+Warning (added by new or init): Some packages were found to be incompatible
+with the snapshot and have been left commented out in the packages section.
+Warning (added by new or init): Specified snapshot could not satisfy all
+dependencies. Some external packages have been added as dependencies.
 You can suppress this message by removing it from stack.yaml
 ~~~

doc/tutorial/executing_commands.md

@@ -31,10 +31,10 @@ stack exec --package stm -- echo I installed the stm package via --package stm
 yields output like:
 
 ~~~text
-Run from outside a project, using implicit global project config
-Using latest snapshot resolver: lts-22.21
-Writing global (non-project-specific) config file to: /home/michael/.stack/global/stack.yaml
-Note: You can change the snapshot via the resolver field there.
+Writing the configuration file for the implicit global project to:
+.../global-project/stack.yaml. Note: You can change the snapshot via the
+snapshot field there.
+Using the latest snapshot lts-22.31.
 I installed the stm package via --package stm
 ~~~