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:package-tests # build Cabal's package 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:package-tests` are out-of-process integration tests on the top-level `Setup`
  92   command line interface.  If you are hacking on the Cabal library you
  93   want to run this test suite.  It must be run from the `Cabal` subdirectory
  94   (ugh!)  This test suite can be a bit touchy; see
  95   [Cabal/tests/README.md](Cabal/tests/README.md) for more information.
  96   Build products and test logs are generated and stored in
  97   `Cabal/tests/PackageTests` under folders named `dist-test` and
  98   `dist-test.$subname`.
  99
 100   Handy command line spell to find test logs is:
 101   ```sh
 102   find . -name test.log|grep test-name
 103   ```
 104
 105   `test.sh` in the same directory as `test.log` is intended to let you rerun
 106   the test without running the actual test driver.
 107
 108
 109 * `Cabal:unit-tests` are small, quick-running unit tests
 110   on small pieces of functionality in Cabal.  If you are working
 111   on some utility functions in the Cabal library you should run this
 112   test suite.
 113
 114 * `cabal-install:unit-tests` are small, quick-running unit tests on
 115   small pieces of functionality in cabal-install.  If you are working
 116   on some utility functions in cabal-install you should run this test
 117   suite.
 118
 119 * `cabal-install:solver-quickcheck` are QuickCheck tests on
 120   cabal-install's dependency solver.  If you are working
 121   on the solver you should run this test suite.
 122
 123 * `cabal-install:integration-tests` are out-of-process integration tests on the
 124   top-level `cabal` command line interface.  The coverage is not
 125   very good but it attempts to exercise most of cabal-install.
 126
 127 * `cabal-install:integration-tests2` are integration tests on some
 128   top-level API functions inside the `cabal-install` source code.
 129   You should also run this test suite.
 130
 131 Conventions
 132 -----------
 133
 134 * Spaces, not tabs.
 135
 136 * Try to follow style conventions of a file you are modifying, and
 137   avoid gratuitous reformatting (it makes merges harder!)
 138
 139 * A lot of Cabal does not have top-level comments.  We are trying to
 140   fix this.  If you add new top-level definitions, please Haddock them;
 141   and if you spend some time understanding what a function does, help
 142   us out and add a comment.  We'll try to remind you during code review.
 143
 144 * If you do something tricky or non-obvious, add a comment.
 145
 146 * For local imports (Cabal module importing Cabal module), import lists
 147   are NOT required (although you may use them at your discretion.)  For
 148   third-party and standard library imports, please use explicit import
 149   lists.
 150
 151 * You can use basically any GHC extension supported by a GHC in our
 152   support window, except Template Haskell, which would cause
 153   bootstrapping problems in the GHC compilation process.
 154
 155 * Our GHC support window is five years for the Cabal library and three
 156   years for cabal-install: that is, the Cabal library must be
 157   buildable out-of-the-box with the dependencies that shipped with GHC
 158   for at least five years.  The Travis CI checks this, so most
 159   developers submit a PR to see if their code works on all these
 160   versions of GHC.  cabal-install must also be buildable on all
 161   supported GHCs, although it does not have to be buildable
 162   out-of-the-box. Instead, the `cabal-install/bootstrap.sh` script
 163   must be able to download and install all of the dependencies.  (This
 164   is also checked by CI!)
 165
 166 * `Cabal` has its own Prelude, in `Distribution.Compat.Prelude`,
 167   that provides a compatibility layer and exports some commonly
 168   used additional functions. Use it in all new modules.
 169
 170 We like [this style guide][guide].
 171
 172 [guide]: https://github.com/tibbe/haskell-style-guide/blob/master/haskell-style.md
 173
 174 Communicating
 175 -------------
 176
 177 There are a few main venues of communication:
 178
 179 * 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.
 180
 181 * For more organizational concerns, the [mailing
 182   list](http://www.haskell.org/mailman/listinfo/cabal-devel) is used.
 183
 184 * Many developers idle on `#hackage` on `irc.freenode.net`.  `#ghc` is
 185   also a decently good bet.
 186
 187 Releases
 188 --------
 189
 190 Notes for how to make a release are at the
 191 wiki page ["Making a release"](https://github.com/haskell/cabal/wiki/Making-a-release).
 192 Currently, @23Skidoo, @rthomas, @tibbe and @dcoutts have access to
 193 `haskell.org/cabal`, and @davean is the point of contact for getting
 194 permissions.
 195
 196 API Documentation
 197 -----------------
 198
 199 Auto-generated API documentation for the `master` branch of Cabal is automatically uploaded here: http://haskell.github.io/cabal-website/doc/html/Cabal/.