From 760068cecb5b79945d7f72a745ddaa07b2e5a28f Mon Sep 17 00:00:00 2001 From: Mike Pilgrem Date: Mon, 29 Jul 2024 21:04:50 +0100 Subject: [PATCH] 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 ~~~