HACKING.md 2.71 KB
Newer Older
Ian D. Bollinger's avatar
Ian D. Bollinger committed
1
2
3
Contributing to Cabal
=====================

Duncan Coutts's avatar
Duncan Coutts committed
4
5
If you want to hack on Cabal, don't be intimidated!

6
7
* Read the [guide to the source
  code](https://github.com/haskell/cabal/wiki/Source-Guide).
8

9
10
* Subscribe to the [mailing
  list](http://www.haskell.org/mailman/listinfo/cabal-devel).
11

12
* Browse the [list of open issues](https://github.com/haskell/cabal/issues).
Duncan Coutts's avatar
Duncan Coutts committed
13

14
15
* There are other resources listed on the [development
  wiki](https://github.com/haskell/cabal/wiki).
Duncan Coutts's avatar
Duncan Coutts committed
16

17
18
* See [Cabal/tests/README.md] for information about writing package tests.

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

Ian D. Bollinger's avatar
Ian D. Bollinger committed
22
[Cabal/tests/README.md]: Cabal/tests/README.md
23

24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
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](http://hackage.haskell.org/package/cabal-install) 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
    ```

74
75
76
77
78
Dependencies policy
-------------------

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

80
81
82
83
84
85
86
87
88
89
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.