1 # Cabal [![Hackage version](https://img.shields.io/hackage/v/Cabal.svg?label=Hackage)](https://hackage.haskell.org/package/Cabal) [![Stackage version](https://www.stackage.org/package/Cabal/badge/lts?label=Stackage)](https://www.stackage.org/package/Cabal) [![Build Status](https://secure.travis-ci.org/haskell/cabal.svg?branch=master)](http://travis-ci.org/haskell/cabal) [![Windows build status](https://ci.appveyor.com/api/projects/status/yotutrf4i4wn5d9y/branch/master?svg=true)](https://ci.appveyor.com/project/23Skidoo/cabal) [![Documentation Status](http://readthedocs.org/projects/cabal/badge/?version=latest)](http://cabal.readthedocs.io/en/latest/?badge=latest)
3 This Cabal Git repository contains the following packages:
5 * [Cabal](Cabal/README.md): the Cabal library package ([license](Cabal/LICENSE))
6 * [cabal-install](cabal-install/README.md): the package containing the `cabal` tool ([license](cabal-install/LICENSE))
8 The canonical upstream repository is located at
9 https://github.com/haskell/cabal.
14 Assuming that you have a pre-existing, older version of `cabal-install`,
18 cabal install cabal-install
21 To get the latest version of `cabal-install`. (You may want to `cabal
24 To install the latest version from the Git repository, clone the
25 Git repository and then run:
28 (cd Cabal; cabal install)
29 (cd cabal-install; cabal install)
32 Building Cabal for hacking
33 --------------------------
35 The current recommended way of developing Cabal is to use the
36 `new-build` feature which [shipped in cabal-install-1.24](http://blog.ezyang.com/2016/05/announcing-cabal-new-build-nix-style-local-builds/). Assuming
37 that you have a sufficiently recent cabal-install (see above),
38 it is sufficient to run:
44 To build a local, development copy of cabal-install. The location
45 of your build products will vary depending on which version of
46 cabal-install you use to build; see the documentation section
47 [Where are my build products?](http://cabal.readthedocs.io/en/latest/nix-local-build.html#where-are-my-build-products)
48 to find the binary (or just run `find -type f -executable -name cabal`).
50 Here are some other useful variations on the commands:
53 cabal new-build Cabal # build library only
54 cabal new-build Cabal:unit-tests # build Cabal's unit test suite
55 cabal new-build cabal-tests # etc...
59 Many of the core developers of Cabal dogfood `cabal-install` HEAD
60 when doing development on Cabal. This helps us identify bugs
61 which were missed by the test suite and easily experiment with new
64 The recommended workflow in this case is slightly different: you will
65 maintain two Cabal source trees: your production tree (built with a
66 released version of Cabal) which always tracks `master` and which you
67 update only when you want to move to a new version of Cabal to dogfood,
68 and your development tree (built with your production Cabal) that you
69 actually do development on.
71 In more detail, suppose you have checkouts of Cabal at `~/cabal-prod`
72 and `~/cabal-dev`, and you have a release copy of cabal installed at
73 `/opt/cabal/1.24/bin/cabal`. First, build your production tree:
77 /opt/cabal/1.24/bin/cabal new-build cabal
80 This will produce a cabal binary (see also: [Where are my build products?](http://cabal.readthedocs.io/en/latest/nix-local-build.html#where-are-my-build-products)
81 ). Add this binary to your PATH,
82 and then use it to build your development copy:
92 **Using Travis and AppVeyor.**
93 If you are not in a hurry, the most convenient way to run tests on Cabal
94 is to make a branch on GitHub and then open a pull request; our
95 continuous integration service on Travis and AppVeyor will build and
96 test your code. Title your PR with WIP so we know that it does not need
99 Some tips for using Travis effectively:
101 * Travis builds take a long time. Use them when you are pretty
102 sure everything is OK; otherwise, try to run relevant tests locally
105 * Watch over your jobs on the [Travis website](http://travis-ci.org).
106 If you know a build of yours is going to fail (because one job has
107 already failed), be nice to others and cancel the rest of the jobs,
108 so that other commits on the build queue can be processed.
110 * If you want realtime notification when builds of your PRs finish, we have a [Slack team](https://haskell-cabal.slack.com/). To get issued an invite, fill in your email at [this sign up page](https://haskell-cabal.herokuapp.com).
112 **How to debug a failing CI test.**
113 One of the annoying things about running tests on CI is when they
114 fail, there is often no easy way to further troubleshoot the broken
115 build. Here are some guidelines for debugging continuous integration
118 1. Can you tell what the problem is by looking at the logs? The
119 `cabal-testsuite` tests run with `-v` logging by default, which
120 is dumped to the log upon failure; you may be able to figure out
121 what the problem is directly this way.
123 2. Can you reproduce the problem by running the test locally?
124 See the next section for how to run the various test suites
125 on your local machine.
127 3. Is the test failing only for a specific version of GHC, or
128 a specific operating system? If so, try reproducing the
129 problem on the specific configuration.
131 4. Is the test failing on a Travis per-GHC build
132 ([for example](https://travis-ci.org/haskell-pushbot/cabal-binaries/builds/208128401))?
133 In this case, if you click on "Branch", you can get access to
134 the precise binaries that were built by Travis that are being
135 tested. If you have an Ubuntu system, you can download
136 the binaries and run them directly.
138 5. Is the test failing on AppVeyor? Consider logging in via
139 Remote Desktop to the build VM:
140 https://www.appveyor.com/docs/how-to/rdp-to-build-worker/
142 If none of these let you reproduce, there might be some race condition
143 or continuous integration breakage; please file a bug.
145 **Running tests locally.**
146 To run tests locally with `new-build`, you will need to know the
147 name of the test suite you want. Cabal and cabal-install have
148 several. Also, you'll want to read [Where are my build products?](http://cabal.readthedocs.io/en/latest/nix-local-build.html#where-are-my-build-products)
150 The most important test suite is `cabal-testsuite`: most user-visible
151 changes to Cabal should come with a test in this framework. See
152 [cabal-testsuite/README.md](cabal-testsuite/README.md) for more
153 information about how to run tests and write new ones. Quick
154 start: use `cabal-tests` to run `Cabal` tests, and `cabal-tests
155 --with-cabal=/path/to/cabal` to run `cabal-install` tests
156 (don't forget `--with-cabal`! Your cabal-install tests won't
159 There are also other test suites:
161 * `Cabal:unit-tests` are small, quick-running unit tests
162 on small pieces of functionality in Cabal. If you are working
163 on some utility functions in the Cabal library you should run this
166 * `cabal-install:unit-tests` are small, quick-running unit tests on
167 small pieces of functionality in cabal-install. If you are working
168 on some utility functions in cabal-install you should run this test
171 * `cabal-install:solver-quickcheck` are QuickCheck tests on
172 cabal-install's dependency solver. If you are working
173 on the solver you should run this test suite.
175 * `cabal-install:integration-tests2` are integration tests on some
176 top-level API functions inside the `cabal-install` source code.
178 For these test executables, `-p` which applies a regex filter to the test
186 * Try to follow style conventions of a file you are modifying, and
187 avoid gratuitous reformatting (it makes merges harder!)
189 * A lot of Cabal does not have top-level comments. We are trying to
190 fix this. If you add new top-level definitions, please Haddock them;
191 and if you spend some time understanding what a function does, help
192 us out and add a comment. We'll try to remind you during code review.
194 * If you do something tricky or non-obvious, add a comment.
196 * For local imports (Cabal module importing Cabal module), import lists
197 are NOT required (although you may use them at your discretion.) For
198 third-party and standard library imports, please use explicit import
201 * You can use basically any GHC extension supported by a GHC in our
202 support window, except Template Haskell, which would cause
203 bootstrapping problems in the GHC compilation process.
205 * Our GHC support window is five years for the Cabal library and three
206 years for cabal-install: that is, the Cabal library must be
207 buildable out-of-the-box with the dependencies that shipped with GHC
208 for at least five years. The Travis CI checks this, so most
209 developers submit a PR to see if their code works on all these
210 versions of GHC. `cabal-install` must also be buildable on all
211 supported GHCs, although it does not have to be buildable
212 out-of-the-box. Instead, the `cabal-install/bootstrap.sh` script
213 must be able to download and install all of the dependencies (this
214 is also checked by CI). Also, self-upgrade to the latest version
215 (i.e. `cabal install cabal-install`) must work with all versions of
216 `cabal-install` released during the last three years.
218 * `Cabal` has its own Prelude, in `Distribution.Compat.Prelude`,
219 that provides a compatibility layer and exports some commonly
220 used additional functions. Use it in all new modules.
222 * As far as possible, please do not use CPP. If you must use it,
223 try to put it in a `Compat` module, and minimize the amount of code
224 that is enclosed by CPP. For example, prefer:
227 #ifdef mingw32_HOST_OS
236 #ifdef mingw32_HOST_OS
245 We like [this style guide][guide].
247 [guide]: https://github.com/tibbe/haskell-style-guide/blob/master/haskell-style.md
252 There are a few main venues of communication:
254 * Most developers subscribe to receive messages from [all issues](https://github.com/haskell/cabal/issues); issues can be used to [open discussion](https://github.com/haskell/cabal/issues?q=is%3Aissue+is%3Aopen+custom+label%3A%22type%3A+discussion%22). If you know someone who should hear about a message, CC them explicitly using the @username GitHub syntax.
256 * For more organizational concerns, the [mailing
257 list](http://www.haskell.org/mailman/listinfo/cabal-devel) is used.
259 * Many developers idle on `#hackage` on `irc.freenode.net` ([archives](http://ircbrowse.net/browse/hackage)). `#ghc` ([archives](http://ircbrowse.net/browse/ghc)) is also a decently good bet.
264 Notes for how to make a release are at the
265 wiki page ["Making a release"](https://github.com/haskell/cabal/wiki/Making-a-release).
266 Currently, @23Skidoo, @rthomas, @tibbe and @dcoutts have access to
267 `haskell.org/cabal`, and @davean is the point of contact for getting
273 Auto-generated API documentation for the `master` branch of Cabal is automatically uploaded here: http://haskell.github.io/cabal-website/doc/html/Cabal/.