README.md
1The Cabal library package
2=========================
3
4See the [Cabal web site] for more information.
5
6If you also want the `cabal` command-line program, you need the
7[cabal-install] package in addition to this library.
8
9[cabal-install]: ../cabal-install/README.md
10
11Installing the Cabal library
12============================
13
14If you already have the `cabal` program
15---------------------------------------
16
17In this case run:
18
19 $ cabal install
20
21However, if you do not have an existing version of the `cabal` program,
22you first must install the Cabal library. To avoid this bootstrapping
23problem, you can install the Cabal library directly as described below.
24
25
26Installing as a user (no root or administrator access)
27------------------------------------------------------
28
29 ghc -threaded --make Setup
30 ./Setup configure --user
31 ./Setup build
32 ./Setup install
33
34Note the use of the `--user` flag at the configure step.
35
36Compiling 'Setup' rather than using `runghc Setup` is much faster and
37works on Windows. For all packages other than Cabal itself, it is fine
38to use `runghc`.
39
40This will install into `$HOME/.cabal/` on Unix and into
41`Documents and Settings\$User\Application Data\cabal\` on Windows.
42If you want to install elsewhere, use the `--prefix=` flag at the
43configure step.
44
45
46Installing as root or Administrator
47-----------------------------------
48
49 ghc -threaded --make Setup
50 ./Setup configure
51 ./Setup build
52 sudo ./Setup install
53
54Compiling Setup rather than using `runghc Setup` is much faster and
55works on Windows. For all packages other than Cabal itself, it is fine
56to use `runghc`.
57
58This will install into `/usr/local` on Unix, and on Windows it will
59install into `$ProgramFiles/Haskell`. If you want to install elsewhere,
60use the `--prefix=` flag at the configure step.
61
62
63Using older versions of GHC and Cabal
64======================================
65
66It is recommended that you leave any pre-existing version of Cabal
67installed. In particular, it is *essential* you keep the version that
68came with GHC itself, since other installed packages require it (for
69instance, the "ghc" API package).
70
71Prior to GHC 6.4.2, however, GHC did not deal particularly well with
72having multiple versions of packages installed at once. So if you are
73using GHC 6.4.1 or older and you have an older version of Cabal
74installed, you should probably remove it by running:
75
76 $ ghc-pkg unregister Cabal
77
78or, if you had Cabal installed only for your user account, run:
79
80 $ ghc-pkg unregister Cabal --user
81
82The `filepath` dependency
83=========================
84
85Cabal uses the [filepath] package, so it must be installed first.
86GHC version 6.6.1 and later come with `filepath`, however, earlier
87versions do not by default. If you do not already have `filepath`,
88you need to install it. You can use any existing version of Cabal to do
89that. If you have neither Cabal nor `filepath`, it is slightly
90harder but still possible.
91
92Unpack Cabal and `filepath` into separate directories. For example:
93
94 tar -xzf filepath-1.1.0.0.tar.gz
95 tar -xzf Cabal-1.6.0.0.tar.gz
96
97 # rename to make the following instructions simpler:
98 mv filepath-1.1.0.0/ filepath/
99 mv Cabal-1.6.0.0/ Cabal/
100
101 cd Cabal
102 ghc -i../filepath -cpp --make Setup.hs -o ../filepath/setup
103 cd ../filepath/
104 ./setup configure --user
105 ./setup build
106 ./setup install
107
108This installs `filepath` so that you can install Cabal with the normal
109method.
110
111[filepath]: http://hackage.haskell.org/package/filepath
112
113More information
114================
115
116Please see the [Cabal web site] for the [user guide] and [API
117documentation]. There is additional information available on the
118[development wiki].
119
120[user guide]: http://www.haskell.org/cabal/users-guide
121[API documentation]: http://www.haskell.org/cabal/release/cabal-latest/doc/API/Cabal/Distribution-Simple.html
122[development wiki]: https://github.com/haskell/cabal/wiki
123
124
125Bugs
126====
127
128Please report bugs and feature requests to Cabal's [bug tracker].
129
130
131Your help
132---------
133
134To help Cabal's development, it is enormously helpful to know from
135Cabal's users what their most pressing problems are with Cabal and
136[Hackage]. You may have a favourite Cabal bug or limitation. Look at
137Cabal's [bug tracker]. Ensure that the problem is reported there and
138adequately described. Comment on the issue to report how much of a
139problem the bug is for you. Subscribe to the issues's notifications to
140discussed requirements and keep informed on progress. For feature
141requests, it is helpful if there is a description of how you would
142expect to interact with the new feature.
143
144[Hackage]: http://hackage.haskell.org
145
146
147Source code
148===========
149
150You can get the master development branch using:
151
152 $ git clone https://github.com/haskell/cabal.git
153
154
155Credits
156=======
157
158See the `AUTHORS` file.
159
160Authors of the [original Cabal
161specification](https://www.haskell.org/cabal/proposal/pkg-spec.pdf):
162
163- Isaac Jones
164- Simon Marlow
165- Ross Patterson
166- Simon Peyton Jones
167- Malcolm Wallace
168
169
170[bug tracker]: https://github.com/haskell/cabal/issues
171[Cabal web site]: http://www.haskell.org/cabal/
172