CONTRIBUTING.md

Contributing to Cabal

Building Cabal for hacking

If you use the latest version of cabal published on Hackage, it is sufficient to run:

cabal build cabal

If not, you aren't able to build the testsuite, so you need to disable the default cabal.project that implies configuring the testsuite, e.g., with:

cabal build --project-file=cabal.project.release cabal

Note If you're using Nix, you might find it convenient to work within a shell that has all the Cabal development dependencies:

$ nix-shell -p cabal-install ghc ghcid haskellPackages.fourmolu_0_12_0_0 pkgconfig zlib.dev

A Nix flake developer shell with these dependencies is also available, supported solely by the community, through the command nix develop github:yvan-sraka/cabal.nix.

The location of your build products will vary depending on which version of cabal-install you use to build; see the documentation section Where are my build products? to find the binary (or just run find -type f -executable -name cabal).

Here are some other useful variations on the commands:

cabal build Cabal # build library only
cabal build Cabal-tests:unit-tests # build Cabal's unit test suite
cabal build cabal-tests # etc...

Running tests

Using GitHub Actions. If you are not in a hurry, the most convenient way to run tests on Cabal is to make a branch on GitHub and then open a pull request; our continuous integration service on GitHub Actions builds and tests your code. Title your PR with WIP so we know that it does not need code review.

Some tips for using GitHub Actions effectively:

• GitHub Actions builds take a long time. Use them when you are pretty sure everything is OK; otherwise, try to run relevant tests locally first.

• If you are only changing documentation in the docs/ subdirectory, or if you change README.md or CONTRIBUTING.md, then we only run a small subset of the CI jobs. You can therefore open small PRs with improvements to the documentation without feeling guilty about wasted resources!

• Watch over your jobs on the GitHub Actions website. If you know a build of yours is going to fail (because one job has already failed), be nice to others and cancel the rest of the jobs, so that other commits on the build queue can be processed.

How to debug a failing CI test. One of the annoying things about running tests on CI is when they fail, there is often no easy way to further troubleshoot the broken build. Here are some guidelines for debugging continuous integration failures:

1. Can you tell what the problem is by looking at the logs? The cabal-testsuite tests run with -v logging by default, which is dumped to the log upon failure; you may be able to figure out what the problem is directly this way.

2. Can you reproduce the problem by running the test locally? See the next section for how to run the various test suites on your local machine.

3. Is the test failing only for a specific version of GHC, or a specific operating system? If so, try reproducing the problem on the specific configuration.

4. Is the test failing on a GitHub Actions per-GHC build. In this case, if you click on "Branch", you can get access to the precise binaries that were built by GitHub Actions that are being tested. If you have an Ubuntu system, you can download the binaries and run them directly.

If none of these let you reproduce, there might be some race condition or continuous integration breakage; please file a bug.

Running tests locally. To run tests locally with cabal, you will need to know the name of the test suite you want. Cabal and cabal-install have several. Also, you'll want to read Where are my build products?

The most important test suite is cabal-testsuite: most user-visible changes to Cabal should come with a test in this framework. See cabal-testsuite/README.md for more information about how to run tests and write new ones. Quick start: use cabal-tests to run Cabal tests, and cabal-tests --with-cabal=/path/to/cabal to run cabal-install tests (don't forget --with-cabal! Your cabal-install tests won't run without it).

There are also other test suites: