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-install:integration-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 seperate
  80   from Cabal. This is an alternative to opening a PR.
  81
  82 **Running tests locally.**
  83 To run tests locally with `new-build`, you will need to know the
  84 name of the test suite you want.  Cabal and cabal-install have
  85 several.  In general, the test executable for
  86 `{Cabal,cabal-install}:$TESTNAME` will be stored at
  87 `dist-newstyle/build/{Cabal,cabal-install}-$VERSION/build/$TESTNAME/$TESTNAME`.
  88
  89 To run a single test, use `-p` which applies a regex filter to the test names.
  90
  91 * `cabal-testsuite:cabal-tests` is an executable runner for out-of-process
  92   integration tests for both the `Setup` interface, as well as
  93   `cabal-install` (if you pass the path to the executable
  94   to test via the `--with-cabal` flag).  Most user-visible changes
  95   to Cabal should come with a test in this framework.  See
  96   [cabal-testsuite/README.md](cabal-testsuite/README.md) for more
  97   information about how to run tests and write new ones.
  98
  99 * `Cabal:unit-tests` are small, quick-running unit tests
 100   on small pieces of functionality in Cabal.  If you are working
 101   on some utility functions in the Cabal library you should run this
 102   test suite.
 103
 104 * `cabal-install:unit-tests` are small, quick-running unit tests on
 105   small pieces of functionality in cabal-install.  If you are working
 106   on some utility functions in cabal-install you should run this test
 107   suite.
 108
 109 * `cabal-install:solver-quickcheck` are QuickCheck tests on
 110   cabal-install's dependency solver.  If you are working
 111   on the solver you should run this test suite.
 112
 113 * `cabal-install:integration-tests` are out-of-process integration tests on the
 114   top-level `cabal` command line interface.  The coverage is not
 115   very good but it attempts to exercise most of cabal-install.
 116
 117 * `cabal-install:integration-tests2` are integration tests on some
 118   top-level API functions inside the `cabal-install` source code.
 119   You should also run this test suite.
 120
 121 Conventions
 122 -----------
 123
 124 * Spaces, not tabs.
 125
 126 * Try to follow style conventions of a file you are modifying, and
 127   avoid gratuitous reformatting (it makes merges harder!)
 128
 129 * A lot of Cabal does not have top-level comments.  We are trying to
 130   fix this.  If you add new top-level definitions, please Haddock them;
 131   and if you spend some time understanding what a function does, help
 132   us out and add a comment.  We'll try to remind you during code review.
 133
 134 * If you do something tricky or non-obvious, add a comment.
 135
 136 * For local imports (Cabal module importing Cabal module), import lists
 137   are NOT required (although you may use them at your discretion.)  For
 138   third-party and standard library imports, please use explicit import
 139   lists.
 140
 141 * You can use basically any GHC extension supported by a GHC in our
 142   support window, except Template Haskell, which would cause
 143   bootstrapping problems in the GHC compilation process.
 144
 145 * Our GHC support window is five years for the Cabal library and three
 146   years for cabal-install: that is, the Cabal library must be
 147   buildable out-of-the-box with the dependencies that shipped with GHC
 148   for at least five years.  The Travis CI checks this, so most
 149   developers submit a PR to see if their code works on all these
 150   versions of GHC.  `cabal-install` must also be buildable on all
 151   supported GHCs, although it does not have to be buildable
 152   out-of-the-box. Instead, the `cabal-install/bootstrap.sh` script
 153   must be able to download and install all of the dependencies (this
 154   is also checked by CI). Also, self-upgrade to the latest version
 155   (i.e. `cabal install cabal-install`) must work with all versions of
 156   `cabal-install` released during the last three years.
 157
 158 * `Cabal` has its own Prelude, in `Distribution.Compat.Prelude`,
 159   that provides a compatibility layer and exports some commonly
 160   used additional functions. Use it in all new modules.
 161
 162 * As far as possible, please do not use CPP. If you must use it,
 163   try to put it in a `Compat` module, and minimize the amount of code
 164   that is enclosed by CPP.  For example, prefer:
 165   ```
 166   f :: Int -> Int
 167   #ifdef mingw32_HOST_OS
 168   f = (+1)
 169   #else
 170   f = (+2)
 171   #endif
 172   ```
 173
 174   over:
 175   ```
 176   #ifdef mingw32_HOST_OS
 177   f :: Int -> Int
 178   f = (+1)
 179   #else
 180   f :: Int -> Int
 181   f = (+2)
 182   #endif
 183   ```
 184
 185 We like [this style guide][guide].
 186
 187 [guide]: https://github.com/tibbe/haskell-style-guide/blob/master/haskell-style.md
 188
 189 Communicating
 190 -------------
 191
 192 There are a few main venues of communication:
 193
 194 * 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.
 195
 196 * For more organizational concerns, the [mailing
 197   list](http://www.haskell.org/mailman/listinfo/cabal-devel) is used.
 198
 199 * 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.
 200
 201 Releases
 202 --------
 203
 204 Notes for how to make a release are at the
 205 wiki page ["Making a release"](https://github.com/haskell/cabal/wiki/Making-a-release).
 206 Currently, @23Skidoo, @rthomas, @tibbe and @dcoutts have access to
 207 `haskell.org/cabal`, and @davean is the point of contact for getting
 208 permissions.
 209
 210 API Documentation
 211 -----------------
 212
 213 Auto-generated API documentation for the `master` branch of Cabal is automatically uploaded here: http://haskell.github.io/cabal-website/doc/html/Cabal/.