Official upstream development repository for Cabal and cabal-install
Switch branches/tags
Clone or download
phadej Merge pull request #5802 from haskell/runParsecParser-prime
Add runParsecParser', which takes CabalSpecVersion
Latest commit 1259836 Dec 17, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Update the PR template. [ci skip] Aug 1, 2018
Cabal Merge pull request #5802 from haskell/runParsecParser-prime Dec 17, 2018
boot Introduce Distribution.Fields module namespace Dec 16, 2018
cabal-dev-scripts SDPX License List 3.3 Nov 24, 2018
cabal-install Use FieldName in FieldGrammar.FieldDescrs Dec 17, 2018
cabal-testsuite Introduce Distribution.Fields module namespace Dec 16, 2018
license-list-data Add license-list-data Nov 25, 2018
pretty-show-1.6.16 [fix ci] patch prett-show for Cabal-2.0 compat Feb 10, 2018
solver-benchmarks Version bump. Aug 1, 2018
travis Don't record ORIGIN anymore, it's being cross-referenced. Nov 25, 2018
.arcconfig Add arcconfig, so arc diff works with phabricator.haskell.org. Sep 24, 2015
.ghci Add config files for ghcid. Jun 8, 2018
.ghcid Add config files for ghcid. Jun 8, 2018
.gitattributes Add a .gitattributes file. [ci skip] Oct 17, 2018
.gitignore Use virtualenv to (help) build docs Dec 4, 2018
.mailmap Update .mailmap [ci skip] Nov 13, 2018
.mention-bot Update .mention-bot Sep 16, 2016
.projectile Add .projectile file to support emacs projectile-mode Jun 9, 2018
.travis.yml Newer alex (and happy) in CI meta Dec 16, 2018
AUTHORS Update AUTHORS. [ci skip] Nov 12, 2018
LICENSE Update the copyright year, cont. (2) Jan 11, 2017
Makefile Introduce Distribution.Fields module namespace Dec 16, 2018
README.md Travis: Use cabal-install-2.4, drop cabal-install-head. Nov 24, 2018
appveyor-retry.cmd Retry when running Appveyor to work around failures. Feb 8, 2017
appveyor.yml Disable 'cache restore' on appveyor Nov 29, 2018
cabal.project Merge pull request #5730 from haskell/remove-unix-constraiant Dec 3, 2018
cabal.project.local.travis Merge pull request #5730 from haskell/remove-unix-constraiant Dec 3, 2018
cabal.project.meta Distribution.SPDX modules Dec 24, 2017
cabal.project.travis Preprocess cabal-install.cabal Aug 20, 2018
cabal.project.travis.libonly Port Travis fixes from 2.4. Dec 3, 2018
cabal.project.validate Merge pull request #5730 from haskell/remove-unix-constraiant Dec 3, 2018
cabal.project.validate.libonly Improve validate.sh Nov 27, 2018
generics-sop-lens.hs Complete BuildInfo.Lens Aug 19, 2017
ghc-packages Rename the cabal directory to Cabal Oct 23, 2011
id_rsa_cabal_website.aes256.enc Rename a file. Jul 18, 2016
stack.yaml Bump Stack resolver (old one fails to build) May 9, 2018
travis-bootstrap.sh Add || exit $? to all subshell calls Jul 27, 2016
travis-common.sh Merge pull request #5709 from 23Skidoo/travis-use-cabal-2.4 Nov 25, 2018
travis-deploy.sh Version bump. Aug 1, 2018
travis-install.sh Newer alex (and happy) in CI meta Dec 16, 2018
travis-meta.sh Travis: Use cabal-install-2.4, drop cabal-install-head. Nov 24, 2018
travis-script.sh Port Travis fixes from 2.4. Dec 3, 2018
travis-solver-debug-flags.sh Use new-build for solver-debug-flags Travis job. Mar 31, 2018
travis-stack.sh Use downloaded version of stack in travis CI May 9, 2018
validate.sh Make hackage-tests parallel. Resolves #5736 Dec 15, 2018

README.md

Cabal Hackage version Stackage version Build Status Windows build status Documentation Status

This Cabal Git repository contains the following packages:

The canonical upstream repository is located at https://github.com/haskell/cabal.

Installing Cabal (by downloading the binary)

Prebuilt binary releases can be obtained from https://www.haskell.org/cabal/download.html. The cabal-install binary download for your platform should contain the cabal executable.

Installing Cabal (with cabal)

Assuming that you have a pre-existing, older version of cabal-install, run:

cabal install cabal-install

To get the latest version of cabal-install. (You may want to cabal update first.)

To install the latest version from the Git repository, clone the Git repository and then run:

(cd Cabal; cabal install)
(cd cabal-install; cabal install)

Installing Cabal (without cabal)

Assuming you don't have a pre-existing copy of cabal-install, run:

cabal-install $ ./bootstrap.sh # running ./bootstrap.sh from within in cabal-install folder.

For more details, and non-unix like systems, see the README.md in cabal-install

Building Cabal for hacking

The current recommended way of developing Cabal is to use the new-build feature which shipped in cabal-install-1.24. Assuming that you have a sufficiently recent cabal-install (see above), it is sufficient to run:

cabal new-build cabal

To build a local, development copy of cabal-install. The location of your build products will vary depending on which version of cabal-install you use to build; see the documentation section Where are my build products? to find the binary (or just run find -type f -executable -name cabal).

Here are some other useful variations on the commands:

cabal new-build Cabal # build library only
cabal new-build Cabal:unit-tests # build Cabal's unit test suite
cabal new-build cabal-tests # etc...

Dogfooding HEAD. Many of the core developers of Cabal dogfood cabal-install HEAD when doing development on Cabal. This helps us identify bugs which were missed by the test suite and easily experiment with new features.

The recommended workflow in this case is slightly different: you will maintain two Cabal source trees: your production tree (built with a released version of Cabal) which always tracks master and which you update only when you want to move to a new version of Cabal to dogfood, and your development tree (built with your production Cabal) that you actually do development on.

In more detail, suppose you have checkouts of Cabal at ~/cabal-prod and ~/cabal-dev, and you have a release copy of cabal installed at /opt/cabal/2.4/bin/cabal. First, build your production tree:

cd ~/cabal-prod
/opt/cabal/2.4/bin/cabal new-build cabal

This will produce a cabal binary (see also: Where are my build products? ). Add this binary to your PATH, and then use it to build your development copy:

cd ~/cabal-dev
cabal new-build cabal

Running tests

Using Travis and AppVeyor. If you are not in a hurry, the most convenient way to run tests on Cabal is to make a branch on GitHub and then open a pull request; our continuous integration service on Travis and AppVeyor will build and test your code. Title your PR with WIP so we know that it does not need code review.

Some tips for using Travis effectively:

  • Travis builds take a long time. Use them when you are pretty sure everything is OK; otherwise, try to run relevant tests locally first.

  • Watch over your jobs on the Travis website. If you know a build of yours is going to fail (because one job has already failed), be nice to others and cancel the rest of the jobs, so that other commits on the build queue can be processed.

  • If you want realtime notification when builds of your PRs finish, we have a Slack team. To get issued an invite, fill in your email at this sign up page.

How to debug a failing CI test. One of the annoying things about running tests on CI is when they fail, there is often no easy way to further troubleshoot the broken build. Here are some guidelines for debugging continuous integration failures:

  1. Can you tell what the problem is by looking at the logs? The cabal-testsuite tests run with -v logging by default, which is dumped to the log upon failure; you may be able to figure out what the problem is directly this way.

  2. Can you reproduce the problem by running the test locally? See the next section for how to run the various test suites on your local machine.

  3. Is the test failing only for a specific version of GHC, or a specific operating system? If so, try reproducing the problem on the specific configuration.

  4. Is the test failing on a Travis per-GHC build (for example)? In this case, if you click on "Branch", you can get access to the precise binaries that were built by Travis that are being tested. If you have an Ubuntu system, you can download the binaries and run them directly.

  5. Is the test failing on AppVeyor? Consider logging in via Remote Desktop to the build VM: https://www.appveyor.com/docs/how-to/rdp-to-build-worker/

If none of these let you reproduce, there might be some race condition or continuous integration breakage; please file a bug.

Running tests locally. To run tests locally with new-build, you will need to know the name of the test suite you want. Cabal and cabal-install have several. Also, you'll want to read Where are my build products?

The most important test suite is cabal-testsuite: most user-visible changes to Cabal should come with a test in this framework. See cabal-testsuite/README.md for more information about how to run tests and write new ones. Quick start: use cabal-tests to run Cabal tests, and cabal-tests --with-cabal=/path/to/cabal to run cabal-install tests (don't forget --with-cabal! Your cabal-install tests won't run without it).

There are also other test suites:

  • Cabal:unit-tests are small, quick-running unit tests on small pieces of functionality in Cabal. If you are working on some utility functions in the Cabal library you should run this test suite.

  • cabal-install:unit-tests are small, quick-running unit tests on small pieces of functionality in cabal-install. If you are working on some utility functions in cabal-install you should run this test suite.

  • cabal-install:solver-quickcheck are QuickCheck tests on cabal-install's dependency solver. If you are working on the solver you should run this test suite.

  • cabal-install:integration-tests2 are integration tests on some top-level API functions inside the cabal-install source code.

For these test executables, -p which applies a regex filter to the test names.

Conventions

  • Spaces, not tabs.

  • Try to follow style conventions of a file you are modifying, and avoid gratuitous reformatting (it makes merges harder!)

  • Format your commit messages in the standard way.

  • A lot of Cabal does not have top-level comments. We are trying to fix this. If you add new top-level definitions, please Haddock them; and if you spend some time understanding what a function does, help us out and add a comment. We'll try to remind you during code review.

  • If you do something tricky or non-obvious, add a comment.

  • If your commit only touches comments, you can use [ci skip] anywhere in the body of the commit message to avoid needlessly triggering the build bots.

  • For local imports (Cabal module importing Cabal module), import lists are NOT required (although you may use them at your discretion.) For third-party and standard library imports, please use either qualified imports or explicit import lists.

  • You can use basically any GHC extension supported by a GHC in our support window, except Template Haskell, which would cause bootstrapping problems in the GHC compilation process.

  • Our GHC support window is five years for the Cabal library and three years for cabal-install: that is, the Cabal library must be buildable out-of-the-box with the dependencies that shipped with GHC for at least five years. The Travis CI checks this, so most developers submit a PR to see if their code works on all these versions of GHC. cabal-install must also be buildable on all supported GHCs, although it does not have to be buildable out-of-the-box. Instead, the cabal-install/bootstrap.sh script must be able to download and install all of the dependencies (this is also checked by CI). Also, self-upgrade to the latest version (i.e. cabal install cabal-install) must work with all versions of cabal-install released during the last three years.

  • Cabal has its own Prelude, in Distribution.Compat.Prelude, that provides a compatibility layer and exports some commonly used additional functions. Use it in all new modules.

  • As far as possible, please do not use CPP. If you must use it, try to put it in a Compat module, and minimize the amount of code that is enclosed by CPP. For example, prefer:

    f :: Int -> Int
    #ifdef mingw32_HOST_OS
    f = (+1)
    #else
    f = (+2)
    #endif
    

    over:

    #ifdef mingw32_HOST_OS
    f :: Int -> Int
    f = (+1)
    #else
    f :: Int -> Int
    f = (+2)
    #endif
    

We like this style guide.

Communicating

There are a few main venues of communication:

  • Most developers subscribe to receive messages from all issues; issues can be used to open discussion. If you know someone who should hear about a message, CC them explicitly using the @username GitHub syntax.

  • For more organizational concerns, the mailing list is used.

  • Many developers idle on #hackage on irc.freenode.net (archives). #ghc (archives) is also a decently good bet.

Releases

Notes for how to make a release are at the wiki page "Making a release". Currently, @23Skidoo, @rthomas, @tibbe and @dcoutts have access to haskell.org/cabal, and @davean is the point of contact for getting permissions.

API Documentation

Auto-generated API documentation for the master branch of Cabal is automatically uploaded here: http://haskell.github.io/cabal-website/doc/html/Cabal/.