From e1e0206af85ab0c2e86afb8d2df44cc403421ac1 Mon Sep 17 00:00:00 2001 From: Mike Pilgrem Date: Sun, 28 Jul 2024 23:17:20 +0100 Subject: [PATCH 1/3] Assume a Windows user is in PowerShell --- doc/commands/build_command.md | 12 +++++++--- doc/commands/exec_command.md | 4 +++- doc/commands/ghci_command.md | 4 ++++ doc/commands/upload_command.md | 19 ++++++++++++++-- doc/configure/environment_variables.md | 19 ++++++++++++++-- doc/configure/yaml/non-project.md | 23 ++++++++++++++++++- doc/faq.md | 30 +++++++++++++++---------- doc/install_and_upgrade.md | 27 ++++++++++++++++++++++ doc/maintainers/releases.md | 6 +++-- doc/topics/scripts.md | 2 +- doc/topics/stack_root.md | 28 +++++++++++++++++++++++ doc/tutorial/hello_world_example.md | 2 +- doc/tutorial/locations_used_by_stack.md | 4 ++-- 13 files changed, 153 insertions(+), 27 deletions(-) diff --git a/doc/commands/build_command.md b/doc/commands/build_command.md index f608455126..a2432116df 100644 --- a/doc/commands/build_command.md +++ b/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 ' "''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''"'` diff --git a/doc/commands/exec_command.md b/doc/commands/exec_command.md index 58b9033bd6..c18bb45eae 100644 --- a/doc/commands/exec_command.md +++ b/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 -- '''a single quoted string'''` diff --git a/doc/commands/ghci_command.md b/doc/commands/ghci_command.md index 12412e8dec..ee5136498d 100644 --- a/doc/commands/ghci_command.md +++ b/doc/commands/ghci_command.md @@ -132,6 +132,10 @@ for user-specific non-essential (cached) data. === "Windows" + On Windows, the default for `` is `$Env:LOCALAPPDATA`. + +=== "Windows (Command Prompt)" + On Windows, the default for `` is `%LOCALAPPDATA%`. ## Running plain GHCi diff --git a/doc/commands/upload_command.md b/doc/commands/upload_command.md index 788b6dc9c9..465bcf6c85 100644 --- a/doc/commands/upload_command.md +++ b/doc/commands/upload_command.md @@ -101,7 +101,7 @@ example: stack upload . ~~~ -=== "Windows (with PowerShell)" +=== "Windows" ~~~text $Env:HACKAGE_USERNAME='' @@ -109,6 +109,14 @@ example: stack upload . ~~~ +=== "Windows (Command Prompt)" + + ~~~text + set HACKAGE_USERNAME= + set HACKAGE_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= stack upload . ~~~ + +=== "Windows (Command Prompt)" + + ~~~text + set HACKAGE_KEY= + stack upload . + ~~~ diff --git a/doc/configure/environment_variables.md b/doc/configure/environment_variables.md index 47aa95fc6a..60a96db837 100644 --- a/doc/configure/environment_variables.md +++ b/doc/configure/environment_variables.md @@ -41,13 +41,20 @@ example: stack upload . ~~~ -=== "Windows (with PowerShell)" +=== "Windows" ~~~text $Env:HACKAGE_KEY= stack upload . ~~~ +=== "Windows (Command Prompt)" + + ~~~text + set HACKAGE_KEY= + stack upload . + ~~~ + ## `HACKAGE_USERNAME` and `HACKAGE_PASSWORD` [:octicons-tag-24: 2.3.1](https://github.com/commercialhaskell/stack/releases/tag/v2.3.1) @@ -67,7 +74,7 @@ example: stack upload . ~~~ -=== "Windows (with PowerShell)" +=== "Windows" ~~~text $Env:HACKAGE_USERNAME='' @@ -75,6 +82,14 @@ example: stack upload . ~~~ +=== "Windows (Command Prompt)" + + ~~~text + set HACKAGE_USERNAME= + set HACKAGE_PASSWORD= + stack upload . + ~~~ + ## `NO_COLOR` Related command: all commands that can produce colored output using control diff --git a/doc/configure/yaml/non-project.md b/doc/configure/yaml/non-project.md index 8abfc3d6fe..4df26aee20 100644 --- a/doc/configure/yaml/non-project.md +++ b/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). diff --git a/doc/faq.md b/doc/faq.md index 8b2590d07b..e0f9d7de30 100644 --- a/doc/faq.md +++ b/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 ";" ~~~ diff --git a/doc/install_and_upgrade.md b/doc/install_and_upgrade.md index e5f1d418aa..c8a5c4ef64 100644 --- a/doc/install_and_upgrade.md +++ b/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\\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. diff --git a/doc/maintainers/releases.md b/doc/maintainers/releases.md index 662b9c5f9f..de0e940d02 100644 --- a/doc/maintainers/releases.md +++ b/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 diff --git a/doc/topics/scripts.md b/doc/topics/scripts.md index 2453c83aa7..019efc9b8f 100644 --- a/doc/topics/scripts.md +++ b/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 diff --git a/doc/topics/stack_root.md b/doc/topics/stack_root.md index 9d38b45095..bcfe952c00 100644 --- a/doc/topics/stack_root.md +++ b/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 diff --git a/doc/tutorial/hello_world_example.md b/doc/tutorial/hello_world_example.md index 219e49331a..a41a4370da 100644 --- a/doc/tutorial/hello_world_example.md +++ b/doc/tutorial/hello_world_example.md @@ -108,7 +108,7 @@ occurring. This command may take some time, depending on download speeds. /home//.stack/programs/x86_64-linux/ghc-9.6.5/bin/ghc ~~~ - === "Windows (with PowerShell)" + === "Windows" ~~~text stack exec -- where.exe ghc diff --git a/doc/tutorial/locations_used_by_stack.md b/doc/tutorial/locations_used_by_stack.md index 0e74705cde..8b408cbd77 100644 --- a/doc/tutorial/locations_used_by_stack.md +++ b/doc/tutorial/locations_used_by_stack.md @@ -55,9 +55,9 @@ installed: /home//.stack/programs/x86_64-linux/ghc-9.0.2.installed ~~~ -=== "Windows (with PowerShell)" +=== "Windows" - Command: + In PowerShell, command: ~~~text dir "$(stack path --programs)/*.installed" From b48d74345b23627628e7bc5bdaac3fed669913e0 Mon Sep 17 00:00:00 2001 From: Mike Pilgrem Date: Mon, 29 Jul 2024 00:02:37 +0100 Subject: [PATCH 2/3] Fix render of bullet point list --- doc/tutorial/hello_world_example.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/tutorial/hello_world_example.md b/doc/tutorial/hello_world_example.md index a41a4370da..5d77ca5997 100644 --- a/doc/tutorial/hello_world_example.md +++ b/doc/tutorial/hello_world_example.md @@ -50,6 +50,7 @@ For this first Stack command, Stack will do some setting up. For example, it will create the [Stack root](../topics/stack_root.md) directory. Other than any setting up, Stack will: + * create the project directory; * download the project template; * attempt to populate the project template based on parameters; and From 760068cecb5b79945d7f72a745ddaa07b2e5a28f Mon Sep 17 00:00:00 2001 From: Mike Pilgrem Date: Mon, 29 Jul 2024 21:04:50 +0100 Subject: [PATCH 3/3] Update multi-package and references to resolver key --- doc/configure/yaml/project.md | 11 ++-- doc/tutorial/building_existing_projects.md | 6 +- doc/tutorial/executing_commands.md | 8 +-- doc/tutorial/hello_world_example.md | 10 ++-- doc/tutorial/multi-package_projects.md | 69 +++++++++++++++------- 5 files changed, 67 insertions(+), 37 deletions(-) diff --git a/doc/configure/yaml/project.md b/doc/configure/yaml/project.md index 3683d24026..54c71594b7 100644 --- a/doc/configure/yaml/project.md +++ b/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 diff --git a/doc/tutorial/building_existing_projects.md b/doc/tutorial/building_existing_projects.md index 03bd1f931c..da94a6b814 100644 --- a/doc/tutorial/building_existing_projects.md +++ b/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 ~~~ diff --git a/doc/tutorial/executing_commands.md b/doc/tutorial/executing_commands.md index 85f5d4e52b..11a61032c8 100644 --- a/doc/tutorial/executing_commands.md +++ b/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 ~~~ diff --git a/doc/tutorial/hello_world_example.md b/doc/tutorial/hello_world_example.md index 5d77ca5997..b82b888d7e 100644 --- a/doc/tutorial/hello_world_example.md +++ b/doc/tutorial/hello_world_example.md @@ -420,19 +420,19 @@ The contents of the file include comments beginning `#`. Ignoring those comments, the contents will look something like this: ~~~yaml -resolver: - url: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/22/21.yaml +snapshot: + url: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/22/31.yaml packages: - . ~~~ -The key [`resolver`](../configure/yaml/project.md#resolver) is a +The key [`snapshot`](../configure/yaml/project.md#snapshot) is a project-specific configuration option. Its value tells Stack *how* to build your package: which GHC version to use, which versions of package dependencies to use, and so on. Our value here says to use -[LTS Haskell 22.21](https://www.stackage.org/lts-22.21), which implies GHC 9.6.5 +[LTS Haskell 22.31](https://www.stackage.org/lts-22.31), which implies GHC 9.6.6 (which is why `stack build` installs that version of GHC if it is not already -available to Stack). There are a number of values you can use for `resolver`, +available to Stack). There are a number of values you can use for `snapshot`, which we'll cover later. The key [`packages`](../configure/yaml/project.md#packages) is another diff --git a/doc/tutorial/multi-package_projects.md b/doc/tutorial/multi-package_projects.md index 1609c18d1f..fd3fbd705f 100644 --- a/doc/tutorial/multi-package_projects.md +++ b/doc/tutorial/multi-package_projects.md @@ -2,49 +2,78 @@ # 7. Multi-package projects -Until now, everything we've done with Stack has used a single-package project. +Until now, everything we have done with Stack has used a single-package project. However, Stack's power truly shines when you're working on multi-package projects. All the functionality you'd expect to work just does: dependencies between packages are detected and respected, dependencies of all packages are just as one cohesive whole, and if anything fails to build, the build commands exits appropriately. -Let's demonstrate this with the `wai-app-static` and `yackage` packages, +Let us demonstrate this with the `wai-app-static` and `yackage` packages, starting in the root directory for all our Haskell projects. Command: ~~~text mkdir multi cd multi stack unpack wai-app-static yackage -Unpacked wai-app-static (from Hackage) to .../multi/wai-app-static-3.1.7.4/ -Unpacked yackage (from Hackage) to .../multi/yackage-0.8.1/ +~~~ + +The last command should report something like: + +~~~text +... +Unpacked wai-app-static (from Hackage) to .../multi/wai-app-static-3.1.9/. +Unpacked yackage (from Hackage) to .../multi/yackage-0.8.1/. +~~~ + +Then command: + +~~~text stack init -Looking for .cabal or package.yaml files to use to init the project. -Using cabal packages: -- wai-app-static-3.1.7.4/ -- yackage-0.8.1/ +~~~ -Cabal file warning in .../multi/yackage-0.8.1/yackage.cabal@47:40: version operators used. To use version operators the package needs to specify at least 'cabal-version: >= 1.8'. -Cabal file warning in .../multi/yackage-0.8.1/yackage.cabal@21:36: version operators used. To use version operators the package needs to specify at least 'cabal-version: >= 1.8'. -Selecting the best among 18 snapshots... +The command should report something like: -* Matches ... +~~~text +Looking for Cabal or package.yaml files to use to initialise Stack's +project-level configuration file. + +Using the Cabal packages: +* wai-app-static-3.1.9/ +* yackage-0.8.1/ + +Cabal file warning in .../multi/yackage-0.8.1/yackage.cabal@47:40: version +operators used. To use version operators the package needs to specify at least +'cabal-version: >= 1.8'. +Cabal file warning in .../multi/yackage-0.8.1/yackage.cabal@21:36: version +operators used. To use version operators the package needs to specify at least +'cabal-version: >= 1.8'. +Selecting the best among 12 snapshots... -Selected resolver: ... -Initialising configuration using resolver: ... -Total number of user packages considered: 2 -Writing configuration to file: stack.yaml +Note: Matches ... + +Selected the snapshot ... +Initialising Stack's project-level YAML configuration file using snapshot ... +Considered 2 user packages. +Writing configuration to stack.yaml. +Stack's project-level YAML configuration file has been initialised. +~~~ + +Then command: + +~~~text stack build --haddock --test -# Goes off to build a whole bunch of packages ~~~ +Stack should build and test the project packages. + If you look at the `stack.yaml` file, you'll see exactly what you'd expect: ~~~yaml -resolver: - url: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/19/17.yaml +snapshot: + url: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/22/31.yaml packages: -- wai-app-static-3.1.7.4 +- wai-app-static-3.1.9 - yackage-0.8.1 ~~~