ghcjs-stack/special/cabal/HACKING.md

Contributing to Cabal

If you want to hack on Cabal, don't be intimidated!

• Read the guide to the source code.

• Subscribe to the mailing list.

• Browse the list of open issues.

• There are other resources listed on the development wiki.

• See Cabal/tests/README.md for information about writing package tests.

Of particular value are the open issues list and the cabal-devel mailing list, which is a good place to ask questions.

Building Cabal from git cloned sources and running the tests

Building Cabal from from source requires the following:

• Glorious/Glasgow Haskell Compiler (ghc).
• An existing (relatively recent) cabal binary (e.g. obtained as part of the Haskell Platform, bootstrapped from the source tarball on Hackage or installed from your Linux vendor).

Once you have these, the steps are:

1. Change into the directory where you want to stash the cabal sources, eg:

   cd ~/MyHaskellCode
   

2. Clone the repo and change into the cabal-install directory:

   git clone https://github.com/haskell/cabal.git
   cd cabal/cabal-install/
   

3. If you are hacking on Cabal you probaly don't want your development version to interfere with the cabal executable you actually use, so we'll set up and use a cabal sandbox:

   cabal sandbox init
   

4. Now add the Cabal library and install all the dependencies into the sandbox:

   cabal sandbox add-source ../Cabal
   cabal --enable-tests install --dependencies-only
   

   Since you used add-source, any changes to Cabal/ will automatically be picked up when building inside cabal-install/ from now on.

5. Build cabal-install and run the tests:

   cabal build
   cabal test
   

Dependencies policy

Cabal's policy is to support being built by versions of GHC that are up to 3 years old.

The Cabal library must be buildable out-of-the-box, i.e., the dependency versions required by Cabal must have shipped with GHC for at least 3 years. Cabal may use newer libraries if they are available, as long as there is a suitable fallback when only older versions exist.

cabal-install must be buildable by versions of GHC that are up to 3 years old. It need not be buildable out-of-the-box, so cabal-install may depend on newer versions of libraries if they can still be compiled by 3-year-old versions of GHC.