diff --git a/doc/glossary.md b/doc/glossary.md index e0fdcd8740..425dc09fec 100644 --- a/doc/glossary.md +++ b/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.| diff --git a/doc/tutorial/hello_world_example.md b/doc/tutorial/hello_world_example.md index db2c9202de..3dd0c5173b 100644 --- a/doc/tutorial/hello_world_example.md +++ b/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 + + + # 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 + + -- 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.