# RFC: A new Cabal user guide

**URL:** <https://discourse.haskell.org/t/rfc-a-new-cabal-user-guide/2639>\
**Category:** Haskell Foundation\
**Created:** [June 11, 2021, 6:36pm UTC](https://discourse.haskell.org/t/rfc-a-new-cabal-user-guide/2639 "2021-06-11T18:36:46Z")\
**Posts on this page:** 10\
**Page:** 1

<div class="post-metadata">

**Author:** ![emilypi](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.haskell.org/emilypi/32/5307_2.png) [@emilypi](https://discourse.haskell.org/u/emilypi)\
**Post date:** [June 11, 2021, 6:36pm UTC](https://discourse.haskell.org/t/rfc-a-new-cabal-user-guide/2639/1 "2021-06-11T18:36:47Z")

</div>

Hello Everyone!

I’ve created a new repo for an exciting new prospect that the HF is trying to find volunteers for: a Cabal User Guide. The Cabal maintenance team acknowledges that the current state of docs is… not the best, to put it lightly. More concretely, the [Cabal documentation](https://cabal.readthedocs.io/en/latest/) reads more like a reference and a wall of text, rather than an actual guide. We are seeking to remedy this by excising the relevant quickstart/guide content from the documentation, keeping the rest of the documentation as a reference, and creating a new Rustbook-style mdBook effort to satisfy this gap in the documentation. I’ve created the new repo [here](https://github.com/haskell/cabal-userguide), and raised its first issue, which is an RFC for content structure. I’d love for you all to be involved. To be clear: HF would love for volunteers to help drive this effort! We want your input, and your contributions.

The below text is redundant with the issue.

* * *

> 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](https://cabal.readthedocs.io/en/latest/), 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](https://github.com/rust-lang/book) built on [mdbook](https://github.com/rust-lang/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.
> 
> 1. **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.

Cheers!  
Emily

---

<div class="post-metadata">

**Author:** ![gilmi](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.haskell.org/gilmi/32/45_2.png) [@gilmi](https://discourse.haskell.org/u/gilmi)\
**Post date:** [June 11, 2021, 6:57pm UTC](https://discourse.haskell.org/t/rfc-a-new-cabal-user-guide/2639/2 "2021-06-11T18:57:50Z")

</div>

I’m very happy to see this initiative!

Do you think setting up CI for a cabal project is something that should be covered in this guide as well?

---

<div class="post-metadata">

**Author:** ![emilypi](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.haskell.org/emilypi/32/5307_2.png) [@emilypi](https://discourse.haskell.org/u/emilypi)\
**Post date:** [June 11, 2021, 7:03pm UTC](https://discourse.haskell.org/t/rfc-a-new-cabal-user-guide/2639/3 "2021-06-11T19:03:54Z")

</div>

Great addition @gilmi! Absolutely. I think introducing `haskell-ci` and `haskell/actions` would be incredibly useful. You should comment 😉

---

<div class="post-metadata">

**Author:** ![tonyday567](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.haskell.org/tonyday567/32/1073_2.png) [@tonyday567](https://discourse.haskell.org/u/tonyday567)\
**Post date:** [June 12, 2021, 5:47am UTC](https://discourse.haskell.org/t/rfc-a-new-cabal-user-guide/2639/4 "2021-06-12T05:47:24Z")

</div>

Hi Emily,

As you may know, I’ve been poking around in cabal, looking at how to do things that I used to do in stack.

As an avid reader of the docs, I say, unfair! They are very well-written but just suffer from being behind current development, which is muy rapido. Maybe a bit of structural refactoring.

Big picture, I would like to see a clear description of what cabal is, and how it fits in with everything else. If we have to live with the confusions of what is Cabal, cabal & cabal-install (and then, out of scope, the poor user has to work out what stack is) then we should at least write a good apology and move on. We cannot say Cabal (resp. cabal-install) forever.

The end result of not covering the basics is then mis-understanding mid-level docs. An example is that I don’t know what “nix-style local builds” are, so I can’t work out what cabal builds are.

Related to this are all the various cabal prefixed libraries, some you mention below, some like cabal-bounds forgotten, some like cabal-extras with lots of interesting tidbits but where future direction is uncertain (for me). What’s in scope?

Your concept of tool documentation describing the environment it manipulates, a Haskell project eventually shipped to Hackage, is a wonderful structure. The community will fill that in. If a package fails on Hackage, what do I do next, if it compiles locally. Do I still need “Setup.hs”? etc etc

A toy project with a library, an app, tests and benchmark, hlinted, formatted by Ormolu, and wired up for CI and HLS is a big template, and may not be a toy.

---

<div class="post-metadata">

**Author:** ![Carloon](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.haskell.org/carloon/32/1035_2.png) [@Carloon](https://discourse.haskell.org/u/Carloon)\
**Post date:** [June 17, 2021, 12:43am UTC](https://discourse.haskell.org/t/rfc-a-new-cabal-user-guide/2639/5 "2021-06-17T00:43:34Z")

</div>

As Apple does each June, they reinvent something(s). This year it’s documentation. They claim they will open source their documentation generator in a few months. It integrates tutorials with online docs.  
I have no idea if this is useful; but somebody who actually understands the problem domain might give this Apple application a quick perusal.

---

<div class="post-metadata">

**Author:** ![Ericson2314](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.haskell.org/ericson2314/32/1026_2.png) [@Ericson2314](https://discourse.haskell.org/u/Ericson2314)\
**Post date:** [July 1, 2021, 2:01pm UTC](https://discourse.haskell.org/t/rfc-a-new-cabal-user-guide/2639/6 "2021-07-01T14:01:58Z")

</div>

I hate to be a format grouch — the overall idea here is really good. especially that references and guides are both needed and one will not suffice without the other.

But having looked at and worked on [https://doc.rust-lang.org/book/](https://doc.rust-lang.org/book/) and also [https://nixos.org/manual/nix/unstable/](https://nixos.org/manual/nix/unstable/), I wanted to say I’m a bit sour on mdbook. As a user, the fact that it only makes a TOC entry for a separate pages seems to lead to these really small pages, which makes browsing with ones eyes, rather annoying. The Sphinx/read-the-docs we have now (and which we also use for GHC) avoids that problem in particular, and frankly just looks much better to me, presentation-wise.

I would be sad if we improved the content only to downgrade the presentation.

---

<div class="post-metadata">

**Author:** ![Vlix](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.haskell.org/vlix/32/1551_2.png) [@Vlix](https://discourse.haskell.org/u/Vlix)\
**Post date:** [July 2, 2021, 11:55am UTC](https://discourse.haskell.org/t/rfc-a-new-cabal-user-guide/2639/7 "2021-07-02T11:55:18Z")

</div>

I’m totally for this, since I still don’t “get” cabal most of the time.  
I’ll wait until the new documentation/guides are in a somewhat complete-ish state to have a fresh “moving from stack” experience to later on give some comments on what is still unclear or could be improved.

---

<div class="post-metadata">

**Author:** ![FrancisKing](https://avatars.discourse-cdn.com/v4/letter/f/c68b51/32.png) [@FrancisKing](https://discourse.haskell.org/u/FrancisKing)\
**Post date:** [July 4, 2021, 6:24pm UTC](https://discourse.haskell.org/t/rfc-a-new-cabal-user-guide/2639/8 "2021-07-04T18:24:03Z")

</div>

The first item has got to be - what is Cabal, and how does it relate to Stack. Then an explanation of the two kinds of Cabal, v1 and v2, and what the difference is. I got into difficulties with the last point.

How do I contribute to this project? (It may be obvious to some, not to me).

---

<div class="post-metadata">

**Author:** ![jaror](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.haskell.org/jaror/32/3271_2.png) [@jaror](https://discourse.haskell.org/u/jaror)\
**Post date:** [July 4, 2021, 7:03pm UTC](https://discourse.haskell.org/t/rfc-a-new-cabal-user-guide/2639/9 "2021-07-04T19:03:24Z")

</div>

> [@FrancisKing](#):
>
> How do I contribute to this project? (It may be obvious to some, not to me).

See [the call for contributors here](http://discourse.haskell.org/t/call-for-contributors-new-cabal-user-guide/2721).

---

<div class="post-metadata">

**Author:** ![ketzacoatl](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.haskell.org/ketzacoatl/32/1203_2.png) [@ketzacoatl](https://discourse.haskell.org/u/ketzacoatl)\
**Post date:** [July 7, 2021, 10:04pm UTC](https://discourse.haskell.org/t/rfc-a-new-cabal-user-guide/2639/10 "2021-07-07T22:04:19Z")

</div>

> [@FrancisKing](#):
>
> The first item has got to be - what is Cabal, and how does it relate to Stack. Then an explanation of the two kinds of Cabal, v1 and v2, and what the difference is. I got into difficulties with the last point.

💯 This would be really nice to clarify for new haskellers beginning their journey!