README.md

   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)
   2
   3 This Cabal Git repository contains the following packages:
   4
   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))
   7
   8 The canonical upstream repository is located at
   9 https://github.com/haskell/cabal.
  10
  11 Installing Cabal
  12 ----------------
  13
  14 Assuming that you have a pre-existing, older version of `cabal-install`,
  15 run:
  16
  17 ~~~~
  18 cabal install cabal-install
  19 ~~~~
  20
  21 To get the latest version of `cabal-install`. (You may want to `cabal
  22 update` first.)
  23
  24 To install the latest version from the Git repository, clone the
  25 Git repository and then run:
  26
  27 ~~~~
  28 (cd Cabal; cabal install)
  29 (cd cabal-install; cabal install)
  30 ~~~~
  31
  32 Building Cabal for hacking
  33 --------------------------
  34
  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:
  39
  40 ~~~~
  41 cabal new-build cabal-install
  42 ~~~~
  43
  44 To build a local, development copy of cabal-install.  The binary
  45 will be located at
  46 `dist-newstyle/build/cabal-install-$VERSION/build/cabal/cabal`;
  47 you can determine the `$VERSION` of cabal-install by looking at
  48 [cabal-install/cabal-install.cabal](cabal-install/cabal-install.cabal).
  49
  50 Here are some other useful variations on the commands:
  51
  52 ~~~~
  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...
  56 ~~~~
  57
  58 Running tests
  59 -------------
  60
  61 **Using Travis and AppVeyor.**
  62 The easiest way to run tests on Cabal is to make a branch on GitHub
  63 and then open a pull request; our continuous integration service on
  64 Travis and AppVeyor will build and test your code.  Title your PR
  65 with WIP so we know that it does not need code review.  Alternately,
  66 you can enable Travis on your fork in your own username and Travis
  67 should build your local branches.
  68
  69 Some tips for using Travis effectively:
  70
  71 * Watch over your jobs on the [Travis website](http://travis-ci.org).
  72   If you know a build of yours is going to fail (because one job has
  73   already failed), be nice to others and cancel the rest of the jobs,
  74   so that other commits on the build queue can be processed.
  75
  76 * 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).
  77
  78 * If you enable Travis for the fork of Cabal in your local GitHub, you
  79   can have builds done automatically for your local branch separate
  80   from Cabal. This is an alternative to opening a PR, and has the bonus
  81   that you don't have to wait for the main queue on Haskell repository
  82   to finish.  It is recommended that you enable Travis only on PRs,
  83   and open a PR on your *local* repository, so that you can also use
  84   GitHub to push and pull branches without triggering builds.
  85
  86 **How to debug a failing CI test.**
  87 One of the annoying things about running tests on CI is when they
  88 fail, there is often no easy way to further troubleshoot the broken
  89 build.  Here are some guidelines for debugging continuous integration
  90 failures:
  91
  92 1. Can you tell what the problem is by looking at the logs?  The
  93    `cabal-testsuite` tests run with `-v` logging by default, which
  94    is dumped to the log upon failure; you may be able to figure out
  95    what the problem is directly this way.
  96
  97 2. Can you reproduce the problem by running the test locally?
  98    See the next section for how to run the various test suites
  99    on your local machine.
 100
 101 3. Is the test failing only for a specific version of GHC, or
 102    a specific operating system?  If so, try reproducing the
 103    problem on the specific configuration.
 104
 105 4. Is the test failing on a Travis per-GHC build
 106    ([for example](https://travis-ci.org/haskell-pushbot/cabal-binaries/builds/208128401))?
 107    In this case, if you click on "Branch", you can get access to
 108    the precise binaries that were built by Travis that are being
 109    tested.  If you have an Ubuntu system, you can download
 110    the binaries and run them directly.  Note that the
 111    build is not relocatable, so you must exactly reproduce
 112    the file system layout of the Travis build (in particular,
 113    the build products need to live in the directory
 114    `/home/travis/build/haskell/cabal`, and the `.cabal` directory
 115    must live in `/home/travis/.cabal`).
 116
 117 5. Is the test failing on AppVeyor?  Consider logging in via
 118    Remote Desktop to the build VM:
 119    https://www.appveyor.com/docs/how-to/rdp-to-build-worker/
 120
 121 If none of these let you reproduce, there might be some race condition
 122 or continuous integration breakage; please file a bug.
 123
 124 **Running tests locally.**
 125 To run tests locally with `new-build`, you will need to know the
 126 name of the test suite you want.  Cabal and cabal-install have
 127 several.  In general, the test executable for
 128 `{Cabal,cabal-install}:$TESTNAME` will be stored at
 129 `dist-newstyle/build/{Cabal,cabal-install}-$VERSION/build/$TESTNAME/$TESTNAME`.
 130
 131 The most important test suite is `cabal-testsuite`: most user-visible
 132 changes to Cabal should come with a test in this framework.  See
 133 [cabal-testsuite/README.md](cabal-testsuite/README.md) for more
 134 information about how to run tests and write new ones.  Quick
 135 start: use `cabal-tests` to run `Cabal` tests, and `cabal-tests
 136 --with-cabal=/path/to/cabal` to run `cabal-install` tests.
 137
 138 Among the other tests, use `-p` which applies a regex filter to the test
 139 names.
 140
 141 * `Cabal:unit-tests` are small, quick-running unit tests
 142   on small pieces of functionality in Cabal.  If you are working
 143   on some utility functions in the Cabal library you should run this
 144   test suite.
 145
 146 * `cabal-install:unit-tests` are small, quick-running unit tests on
 147   small pieces of functionality in cabal-install.  If you are working
 148   on some utility functions in cabal-install you should run this test
 149   suite.
 150
 151 * `cabal-install:solver-quickcheck` are QuickCheck tests on
 152   cabal-install's dependency solver.  If you are working
 153   on the solver you should run this test suite.
 154
 155 * `cabal-install:integration-tests2` are integration tests on some
 156   top-level API functions inside the `cabal-install` source code.
 157   You should also run this test suite.
 158
 159 Conventions
 160 -----------
 161
 162 * Spaces, not tabs.
 163
 164 * Try to follow style conventions of a file you are modifying, and
 165   avoid gratuitous reformatting (it makes merges harder!)
 166
 167 * A lot of Cabal does not have top-level comments.  We are trying to
 168   fix this.  If you add new top-level definitions, please Haddock them;
 169   and if you spend some time understanding what a function does, help
 170   us out and add a comment.  We'll try to remind you during code review.
 171
 172 * If you do something tricky or non-obvious, add a comment.
 173
 174 * For local imports (Cabal module importing Cabal module), import lists
 175   are NOT required (although you may use them at your discretion.)  For
 176   third-party and standard library imports, please use explicit import
 177   lists.
 178
 179 * You can use basically any GHC extension supported by a GHC in our
 180   support window, except Template Haskell, which would cause
 181   bootstrapping problems in the GHC compilation process.
 182
 183 * Our GHC support window is five years for the Cabal library and three
 184   years for cabal-install: that is, the Cabal library must be
 185   buildable out-of-the-box with the dependencies that shipped with GHC
 186   for at least five years.  The Travis CI checks this, so most
 187   developers submit a PR to see if their code works on all these
 188   versions of GHC.  `cabal-install` must also be buildable on all
 189   supported GHCs, although it does not have to be buildable
 190   out-of-the-box. Instead, the `cabal-install/bootstrap.sh` script
 191   must be able to download and install all of the dependencies (this
 192   is also checked by CI). Also, self-upgrade to the latest version
 193   (i.e. `cabal install cabal-install`) must work with all versions of
 194   `cabal-install` released during the last three years.
 195
 196 * `Cabal` has its own Prelude, in `Distribution.Compat.Prelude`,
 197   that provides a compatibility layer and exports some commonly
 198   used additional functions. Use it in all new modules.
 199
 200 * As far as possible, please do not use CPP. If you must use it,
 201   try to put it in a `Compat` module, and minimize the amount of code
 202   that is enclosed by CPP.  For example, prefer:
 203   ```
 204   f :: Int -> Int
 205   #ifdef mingw32_HOST_OS
 206   f = (+1)
 207   #else
 208   f = (+2)
 209   #endif
 210   ```
 211
 212   over:
 213   ```
 214   #ifdef mingw32_HOST_OS
 215   f :: Int -> Int
 216   f = (+1)
 217   #else
 218   f :: Int -> Int
 219   f = (+2)
 220   #endif
 221   ```
 222
 223 We like [this style guide][guide].
 224
 225 [guide]: https://github.com/tibbe/haskell-style-guide/blob/master/haskell-style.md
 226
 227 Communicating
 228 -------------
 229
 230 There are a few main venues of communication:
 231
 232 * 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.
 233
 234 * For more organizational concerns, the [mailing
 235   list](http://www.haskell.org/mailman/listinfo/cabal-devel) is used.
 236
 237 * 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.
 238
 239 Releases
 240 --------
 241
 242 Notes for how to make a release are at the
 243 wiki page ["Making a release"](https://github.com/haskell/cabal/wiki/Making-a-release).
 244 Currently, @23Skidoo, @rthomas, @tibbe and @dcoutts have access to
 245 `haskell.org/cabal`, and @davean is the point of contact for getting
 246 permissions.
 247
 248 API Documentation
 249 -----------------
 250
 251 Auto-generated API documentation for the `master` branch of Cabal is automatically uploaded here: http://haskell.github.io/cabal-website/doc/html/Cabal/.