Merge branch 'stable'

doc/glossary.md

@@ -35,6 +35,7 @@ The following terms are used in Stack's documentation.
 |Linux              |A family of operating systems based on the Linux kernel.  |
 |macOS              |The primary operating system for Apple's Mac computers. Previously known as Mac OS X or OS X.|
 |Make               |A [build automation tool](https://www.gnu.org/software/make/).|
+|Markdown           |A plain text [formatting syntax](https://daringfireball.net/projects/markdown/) or software used to convert files in that format to HTML.|
 |MSYS2              |The [MSYS2](https://www.msys2.org/) software distribution and building platform for Windows.|
 |Nix                |A purely functional [package manager](https://nixos.org/), available for Linux and macOS.|
 |package            |A Haskell package is an organised collection of Haskell code and related files. It is described by a Cabal file or a `package.yaml` file, which is itself part of the package.|

doc/tutorial/hello_world_example.md

@@ -337,31 +337,69 @@ Having build the test suite executable, Stack then automatically runs it.
 Let's look at the `helloworld` example in more detail to understand better how
 Stack works.
 
-The files in the project include:
-
-~~~text
-app/Main.hs
-src/Lib.hs
-test/Spec.hs
-ChangeLog.md
-README.md
-LICENSE
-.gitignore
-package.yaml
-helloworld.cabal
-Setup.hs
-stack.yaml
+The files in the project are set out below. Click :material-plus-circle: to
+learn more about each file:
+
+~~~shell
+.
+├── app
+│   └── Main.hs # (1)!
+├── src
+│   └── Lib.hs # (2)!
+├── test
+│   └── Spec.hs # (3)!
+│
+├── .gitignore # (4)!
+├── CHANGELOG.md # (5)!
+├── LICENSE # (6)!
+├── README.md # (7)!
+│
+├── package.yaml # (8)!
+├── helloworld.cabal # (9)!
+├── Setup.hs # (10)!
+└── stack.yaml # (11)!
 ~~~
 
-The `app/Main.hs`, `src/Lib.hs`, and `test/Spec.hs` files are all Haskell
-source files that compose the actual functionality of our project. We won't
-dwell on them here.
+1.  The Haskell source code for the executable (application).
+
+    As your project develops you can add further source code files to the `app`
+    directory.
+
+2.  The executable uses a library. The Haskell source code for the library.
+
+    As your project develops you can add further source code files to the `src`
+    directory.
+
+3.  The package has a test suite executable. The Haskell source code for the
+    test suite.
+
+    As your project develops you can add further source code files to the `test`
+    directory.
+
+4.  A text file used to configure the Git tool to ignore certain files. Does not
+    affect the build.
+
+5.  A text file in the Markdown format in which changes to the project can be
+    documented. Does not affect the build.
+
+6.  A text file used to document the copyright applicable to the project's files
+    and the licence for the use of those files. Does not affect the build.
+
+7.  A text file in the Markdown format which is intended to be read by users of
+    the project. Does not affect the build.
 
-The `ChangeLog.md`, `README.md`, `LICENSE` and `.gitignore` files have no effect
-on the build.
+8.  A file describing the package in the Hpack format. See further below.
 
-The files of interest here are `package.yaml`, `helloworld.cabal`, `Setup.hs`
-and `stack.yaml`.
+9.  A file describing the package in the Cabal format. See further below.
+
+10. A Haskell source file which is a component of the Cabal build system. See
+    further below.
+
+11. A text file in the YAML format, containing Stack's project-level
+    configuration. See further below.
+
+The files of most interest here are `package.yaml`, `helloworld.cabal`,
+`Setup.hs` and `stack.yaml`.
 
 ### `package.yaml`
 
@@ -393,11 +431,222 @@ functionality to create a Cabal file.
     The [Hpack](https://github.com/sol/hpack#quick-reference) documentation
     is the reference for the Hpack package description format.
 
+??? question "What are the contents of the `package.yaml` file?"
+
+    The contents of the `package.yaml` file are described below, using
+    additional YAML comments:
+
+    ~~~yaml
+    # The name of the package:
+    name:                helloworld
+    # The version of the package:
+    version:             0.1.0.0
+    # The GitHub repository for the package:
+    github:              "githubuser/helloworld"
+    # The licence for the use of the package's files:
+    license:             BSD-3-Clause
+    # The author of the package:
+    author:              "Author name here"
+    # The email address to contact the maintainer of the package:
+    maintainer:          "example@example.com"
+    # The copyright for the package's files:
+    copyright:           "2024 Author name here"
+
+    # Extra files to be distributed with the source files of the package:
+    extra-source-files:
+    - README.md
+    - CHANGELOG.md
+
+    # Metadata used when publishing your package
+    # synopsis:            Short description of your package
+    # category:            Web
+
+    # To avoid duplicated efforts in documentation and dealing with the
+    # complications of embedding Haddock markup inside cabal files, it is
+    # common to point users to the README.md file.
+    description:         Please see the README on GitHub at
+                         <https://github.com/githubuser/helloworld#readme>
+
+    # Dependencies applicable to all components:
+    dependencies:
+    - base >= 4.7 && < 5
+
+    # GHC options common to all components:
+    ghc-options:
+    # These GHC flags affect which warnings GHC will emit:
+    - -Wall
+    - -Wcompat
+    - -Widentities
+    - -Wincomplete-record-updates
+    - -Wincomplete-uni-patterns
+    - -Wmissing-export-lists
+    - -Wmissing-home-modules
+    - -Wpartial-fields
+    - -Wredundant-constraints
+
+    # The main (unnamed) library component of the package:
+    library:
+      # Directories containing source files:
+      source-dirs: src
+
+    # The executable components of the package:
+    executables:
+      # The executable component named 'helloworld-exe':
+      helloworld-exe:
+        # The source file exporting the 'main' function:
+        main:                Main.hs
+        # Directories containing source files:
+        source-dirs:         app
+        # GHC options applicable to the component:
+        ghc-options:
+        # Link the program with the 'threaded' version of GHC's runtime system:
+        - -threaded
+        # Make all of GHC's runtime system (RTS) options available:
+        - -rtsopts
+        # Compile so as to use simultaneous threads when running the program,
+        # based on how many processors are in the machine.
+        - -with-rtsopts=-N
+        # Dependencies applicable to the component:
+        dependencies:
+        # The main library of the package:
+        - helloworld
+
+    # The test suite components of the package. Test suites have keys in common
+    # with executables:
+    tests:
+      # The test suite component named 'helloworld-test':
+      helloworld-test:
+        main:                Spec.hs
+        source-dirs:         test
+        ghc-options:
+        - -threaded
+        - -rtsopts
+        - -with-rtsopts=-N
+        dependencies:
+        - helloworld
+    ~~~
+
 ### `helloworld.cabal`
 
 The `helloworld.cabal` file is updated automatically as part of the
 `stack build` process and should not be modified.
 
+??? question "What are the contents of the `helloworld.cabal` file?"
+
+    The contents of the `helloworld.cabal` file are described below, using
+    additional Cabal file comments:
+
+    ~~~text
+    -- The version of the Cabal package description format specification:
+    cabal-version: 2.2
+
+    -- This file has been generated from package.yaml by hpack version 0.37.0.
+    --
+    -- see: https://github.com/sol/hpack
+
+    -- The name of the package:
+    name:           helloworld
+    -- The version of the package:
+    version:        0.1.0.0
+    -- The description of the package:
+    description:    Please see the README on GitHub at
+                    <https://github.com/githubuser/helloworld#readme>
+    -- A URL for the package:
+    homepage:       https://github.com/githubuser/helloworld#readme
+    -- A URL for bug reports for the package:
+    bug-reports:    https://github.com/githubuser/helloworld/issues
+    -- The author of the package:
+    author:         Author name here
+    -- The email address to contact the maintainer of the package:
+    maintainer:     example@example.com
+    -- The copyright for the package's files:
+    copyright:      2024 Author name here
+    -- The licence for the use of the package's files:
+    license:        BSD-3-Clause
+    -- The file documenting the terms of the licence:
+    license-file:   LICENSE
+    -- The Cabal system build type of the package:
+    build-type:     Simple
+    -- Extra files to be distributed with the source files of the package:
+    extra-source-files:
+        README.md
+        CHANGELOG.md
+
+    -- The respository for the package:
+    source-repository head
+      type: git
+      location: https://github.com/githubuser/helloworld
+
+    -- The main (unnamed) library component of the package:
+    library
+      -- The modules that the library exposes:
+      exposed-modules:
+          Lib
+      -- The other modules of the compoment:
+      other-modules:
+          Paths_helloworld
+      -- Automatically generated modules of the component:
+      autogen-modules:
+          Paths_helloworld
+      -- Directories containing source files:
+      hs-source-dirs:
+          src
+      -- GHC options applicable to the component. In this case, they are flags
+      -- that affect which warnings GHC will emit:
+      ghc-options: -Wall -Wcompat -Widentities -Wincomplete-record-updates
+                   -Wincomplete-uni-patterns -Wmissing-export-lists
+                   -Wmissing-home-modules -Wpartial-fields
+                   -Wredundant-constraints
+      -- Dependencies applicable to the building of the component:
+      build-depends:
+          base >=4.7 && <5
+      -- The applicable version of the Haskell language:
+      default-language: Haskell2010
+
+    -- The executable 'helloworld-exe' component of the package. Executable
+    -- components have fields in common with library components:
+    executable helloworld-exe
+      -- The source file exporting the 'main' function:
+      main-is: Main.hs
+      other-modules:
+          Paths_helloworld
+      autogen-modules:
+          Paths_helloworld
+      hs-source-dirs:
+          app
+      -- GHC options applicable to the component. In this case, they include
+      -- flags that affect GHC's runtime system (RTS).
+      ghc-options: -Wall -Wcompat -Widentities -Wincomplete-record-updates
+                   -Wincomplete-uni-patterns -Wmissing-export-lists
+                   -Wmissing-home-modules -Wpartial-fields
+                   -Wredundant-constraints -threaded -rtsopts -with-rtsopts=-N
+      build-depends:
+          base >=4.7 && <5
+        , helloworld
+      default-language: Haskell2010
+
+    -- The test suite 'helloworld-test' component of the package. Test suite
+    -- components have fields in common with executable components:
+    test-suite helloworld-test
+      -- The type of the test suite:
+      type: exitcode-stdio-1.0
+      main-is: Spec.hs
+      other-modules:
+          Paths_helloworld
+      autogen-modules:
+          Paths_helloworld
+      hs-source-dirs:
+          test
+      ghc-options: -Wall -Wcompat -Widentities -Wincomplete-record-updates
+                   -Wincomplete-uni-patterns -Wmissing-export-lists
+                   -Wmissing-home-modules -Wpartial-fields
+                   -Wredundant-constraints -threaded -rtsopts -with-rtsopts=-N
+      build-depends:
+          base >=4.7 && <5
+        , helloworld
+      default-language: Haskell2010
+    ~~~
+
 ### `Setup.hs`
 
 The `Setup.hs` file is a component of the Cabal build system.