diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 062ee73f3d5..fa1d5385d68 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,19 +3,41 @@ Building Cabal for hacking -------------------------- -If you use the latest version of cabal published on Hackage, it is sufficient to run: +If you use the `cabal` executable from the latest version of the +[cabal-install](https://hackage.haskell.org/package/cabal-install) package +published on Hackage, it is sufficient to run: ``` -cabal build cabal +$ 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: +If you have trouble building the testsuite for this initial build, try building +with the release project that excludes this testsuite: ``` -cabal build --project-file=cabal.release.project cabal +$ cabal build cabal --project-file=cabal.release.project ``` -> **Note** +> [!NOTE] +> The default `cabal.project` is picked up implicitly as if the +> `--project-file=cabal.project` explicit option had been given. + +For developing, we recommend using the locally built version of `cabal`, the +executable, if only because one of the released versions available may be +lacking a fix. This can be installed: + +``` +$ cabal install cabal-install:exe:cabal --overwrite-policy=always +``` + +It can be run without first installing it with `cabal run cabal --` followed by +its own arguments, as shown here for `build --help`: + +``` +$ cabal run cabal -- build --help +``` + +> [!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 @@ -30,9 +52,9 @@ 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... +$ 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