file to edit: https://github.com/haskell/cabal-userguide/blob/main/src/new_to_cabal/06_first_cabal_library.md

Brief Summary

This chapter should walk the user through getting a library set up via their cabal repo. Ideally it will build on the previous chapter that walks the user through top level .cabal file properties. It should also explain how to make modules visible, and how to load the library into ghci or cabal repl to test things out.

Prior Art

Haskell School library and executable
Haskell School module visibility

Resources

Old cabal user guide library vs executable

Brief Summary

This chapter should cover the most important basic properties for a cabal package. These are the top level properties in a .cabal file. It is important to be thoughtful about the ramifications of specific properties i.e. the name field needs to be globally unique across the hackage archive! Another consideration is that this guide is not intended to be reference material, but rather a user guide, so its important to take into account what a user needs to know vs all the minute details.

Resources

Reference for package properties
Description of what a package is

file to edit: https://github.com/haskell/cabal-userguide/blob/main/src/leveling_up/01_refactoring_and_re-use.md

Brief Summary

The motivation for this chapter is to show ways that common blocks in .cabal files can be factored out using common stanzas.

Resources

Old cabal user guide common stanza intro
Old cabal user guide common stanza reference

file to edit: https://github.com/haskell/cabal-userguide/blob/main/src/new_to_cabal/01_installing_cabal_and_ghc.md

Brief Summary

This should be the minimal instruction to get haskell and cabal running for the rest of the guide.

Prior Art

Kowainik Cabal Installation
Haskell School Blog Post Installation Instructions

Resources

Ghcup instructions from haskell.org
Ghcup repo instructions

file to edit: https://github.com/haskell/cabal-userguide/blob/main/src/leveling_up/06_uploading_package_to_hackage.md

Brief Summary

This (like haddocks #22) is another poorly documented area. This section should cover common considerations (versioning, globally unique names), the relevant metadata in the .cabal file that will make it on to hackage, and the process of uploading a library to hackage.

file to edit: https://github.com/haskell/cabal-userguide/blob/main/src/leveling_up/05_generating_documentation_with_haddock.md

Brief Summary

In my opinion this is a relatively undocumented aspect of cabal. I think that it can be very mysterious to beginners, it is also really useful to be able to locally host project specific haddocks. It can also be confusing when misconfigured i.e. you are building haddocks on every build / ghcid recompilation. While this shouldn't be a haddock reference guide, it might be useful to cover some of the basic / more common haddock syntax in the example.

file to edit: https://github.com/haskell/cabal-userguide/blob/main/src/new_to_cabal/04_initializing_a_cabal_repo.md

Brief Summary

This chapter should give a new user all the information they need to start a cabal repo. It should cover manually initializing a repo , initializing with cabal init --interactive, and initializing with cabal init. The chapter should go into a brief introduction of the directory structure of a standard cabal package, but no go into so much depth as to explain the more complicated aspects (i.e. Setup.hs

Prior Art

Kowainik Blog section on init

Resources

Old cabal user guide init section
Old cabal user guide initialization explanation
Source code for interactive init
Source code for non-interactive init

file to edit: https://github.com/haskell/cabal-userguide/blob/main/src/preamble/03_what_is_hackage.md

Brief Summary

Hackage is a key piece of haskell infrastructure. It is also critical to cabal, and (in my opinion) receives very little treatment in documentation in comparison to how critical it is. This chapter should go over key hackage features and why they are important for someone who wants to use Cabal.

Resources

Hackage Website
How Cabal uses hackage

file to edit: https://github.com/haskell/cabal-userguide/blob/main/src/new_to_cabal/02_cabal_repl.md

Brief Summary

In the content discussion issue it was mentioned that the easiest way to show a new user how to use cabal is through an interactive environment where they can try things out. This chapter should show the users the basics of the cabal repl (loading a package with --build-depends, basic repl like activities). The intent of the chapter should be to show the user how to experiment with cabal. It might also be nice to show how cabal repl integrates into an interactive workflow via something like ghcid.

Prior Art

Kowainik blog post repl section

Resources

Prior Cabal User Guide
Repl Command Source

file to edit: https://github.com/haskell/cabal-userguide/blob/main/src/new_to_cabal/07_first_cabal_executable.md

Brief Summary

This chapter should build off of the previous one #14 and demonstrate how to create an executable that uses the library. However, it would be a good idea to show that an executable can exist without depending on the library. It might be nice to show 2 executables that use the same library, this would demonstrate that there can be more than one exe unlike libraries. It would also be nice to show the user how to run their executable.

Prior Art

Kowainik blog adding an executable
Haskell School building and running executables

Resources

Old cabal user guide library vs executable

This repository intends to create a new Quickstart and User guide for the Cabal build tool. The Cabal team acknowledges that the current state of documents, located at cabal.readthedocs.io, serves more as a reference, and less as a guide for getting started or gathering intuition about how to effectively use the tool on projects. We would like to change this.

Tools

Rust has had a very successful, community-driven book built on mdbook, which allows users to contribute markdown to a codebase which may be compiled into a nice, legible and locally hostable book format. I propose we adopt this style, and contribute the missing content for this book in that format.

Content

There are two major areas of content that I'd like to cover:

1. Quickstart. How does a user come up to speed in as quickly a manner as possible, such that they can get hacking with minimal fuss. The sample out line for this content would look something like the following:

• Installation
• Creating a project from scratch
• Working with an existing project, considering existing tooling like stack, or otherwise.
• Hello world! Building and running a small project to output. This section would probably list a small subset of useful commands.

2. User guide. Given a sample project, with a contrived object, how would the user go about:

• Creating the project from scratch. Discussing naming conventions, the anatomy of a simple .cabal and its components/vocabulary/syntax at a high level
• Modifying a project: adding modules exposed or otherwise, adding dependencies, warnings, etc etc. at a high level, and discussing good practice for naming conventions and managing bounds.
• Building a project: this section could discuss the basic commands used to build a project once a selection of modules has been described, and mention cabal.project and local cabal.project configuration commands, syntax, and multiproject management. Here, we could add some content regarding remote source repositories like git.
• Testing a project
• Benchmarking a project
• Profiling a project
• Working with extra-build-tools and the more exotic parts of the .cabal ecosystem
• How to package a project and work with Hackage to release

Goals

The goals of this project, in my opinion, should achieve the following:

1. We want a quick reference to cite to beginners for getting up and running with a project that prints "Hello, World!" in as few commands as possible.
2. We want a user-guide that can serve as a hand-holding exercise for beginners and more casual haskellers, who can follow along with a relatively simple, contrived project that slowly builds up some complexity into something publishable by the end.
3. We want to delineate best practices for maintaining a cabal file, so that there is less confusion
4. We want to show people how to publish and release.
5. We would like people to walk away with a general understanding of how to do the most fundamental aspects of project maintenance, ranging from module additions, to testing, benchmarking, and profiling, as well as an understanding of how to work in general with dependencies, bounds, and remote source repos.
6. We should aim to be as friendly and high level as possible, while also achieving these goals.

I'm interested to hear from @JonathanLorimer, @Mikolaj, @fgaz, @gbaz, and anyone else who has time to hash out an outline for this book. I'd love to have a public record here of our discussions for posterity.

This is a placeholder issue. The documentation section is blocked on haskell/cabal#6481

file to edit: https://github.com/haskell/cabal-userguide/blob/main/src/new_to_cabal/08_adding_dependencies.md

Brief Summary

This is a very important chapter as it will introduce new users to one of the primary use cases of cabal, bringing in external libraries. This should go over all 3 ways of adding dependencies:

• Local packages
• Hackage packages
• Packages as tarballs

There should be some discussion of version bounds, their syntax and semantics, and strategies for organizing version bounds.

Prior Art

Kowainik Blog adding a dependency
Haskell School adding a dependency

Resources

Matt Parson's blog post on version bounding
Old cabal user guide adding dependencies
Old cabal user guide build depends

file to edit: https://github.com/haskell/cabal-userguide/blob/main/src/leveling_up/04_build_products_and_caching.md

Brief Summary

The motivation for this chapter is to reveal some of the internals of cabal. It shouldn't be a deep dive, but an explanation of where things end up, and some performance considerations that will be useful! It might be a good idea to cover manually busting the cache, and clearing out build artefacts, as well as best practices.

Resources

Old cabal user guide build products
Old cabal user guide caching

file to edit: https://github.com/haskell/cabal-userguide/blob/main/src/preamble/01_what_do_we_mean_when_we_say_cabal.md

Brief Summary

The purpose of this chapter is to clear up some of the ambiguity around the overloaded term "cabal". We at least want to cover these four terms:

• cabal-install - the cli
• Cabal - the hackage package
• cabal.project - The configuration file
• .cabal - The package specific configuration file

If there are other cabal related terms that might be confusing, this would be a good place to precisely define them, and distinguish them from other cabal related things.

Prior Art

• Kowainik Blog Post
• Haskell School Post

Resources

• cabal-install
• cabal cli
• .cabal file
• cabal.project

file to edit: https://github.com/haskell/cabal-userguide/blob/main/src/leveling_up/02_first_cabal_test-suite.md

Brief Summary

The motivation for this chapter is to show users how to setup a test suite in cabal, how to test their library, and how to test their executable code. It would be helpful to mention how compilation works wrt test suites.

Resources

Old cabal user guide test reference

file to edit: https://github.com/haskell/cabal-userguide/blob/main/src/preamble/02_what_is_a_module_and_a_package.md

Brief Summary

Some people coming to this user guide will not have clear definitions of packages and modules in mind, let alone what a package and module is with regards to cabal. These are two fundamental concepts that motivate the structure of cabal and its use cases. They are also terms that are overloaded in the software engineering community at large. It will be useful to clarify these two concepts as they pertain to cabal

Prior Art

Discussion of modules
Discussion of packages

Resources

How cabal interacts with packages
What's in a package
Philosophical discussion of packages

file to edit: https://github.com/haskell/cabal-userguide/blob/main/src/preamble/04_how_to_install_software_with_cabal-install.md

Brief Summary

This issue was added because of discussion on the initial content ideation issue (starting here). This is an important subject, because users often do want to install software without having to understand anything about packaging software. This section should explain how to install software with the cabal-install cli.

Resources

Installing packages
The install command

file to edit: https://github.com/haskell/cabal-userguide/blob/main/src/leveling_up/03_first_cabal_benchmark.md

Brief Summary

The motivation for this section is to show new users how to benchmark the performance of their applications using cabal.

Resources

Old cabal user guide bench-marking reference