Official upstream development repository for Cabal and cabal-install
Haskell Shell Other
Latest commit e0dd63c Sep 25, 2016 @hvr hvr committed on GitHub Use hash-consing to optimise index cache (#3897)
Without this optimisation, `cabal info somethingnonexisting` results in

     960,397,120 bytes allocated in the heap
     739,652,560 bytes copied during GC
      67,757,128 bytes maximum residency (24 sample(s))
       2,234,096 bytes maximum slop
             147 MB total memory in use (0 MB lost due to fragmentation)

with this optimisation:

   1,000,825,744 bytes allocated in the heap
     656,112,432 bytes copied during GC
      44,476,616 bytes maximum residency (24 sample(s))
       2,302,864 bytes maximum slop
             109 MB total memory in use (0 MB lost due to fragmentation)

So the total memory in use is significantly lower. The total runtime is
also slightly reduced, from

  INIT    time    0.001s  (  0.001s elapsed)
  MUT     time    0.683s  (  1.050s elapsed)
  GC      time    0.946s  (  0.946s elapsed)
  EXIT    time    0.005s  (  0.005s elapsed)
  Total   time    1.637s  (  2.002s elapsed)

to

  INIT    time    0.001s  (  0.001s elapsed)
  MUT     time    0.664s  (  0.988s elapsed)
  GC      time    0.797s  (  0.797s elapsed)
  EXIT    time    0.004s  (  0.004s elapsed)
  Total   time    1.467s  (  1.789s elapsed)


Note that there's currently ~80k cache entries, but only ~10k unique package names
and ~6k unique versions. So hash-consing helps reduce the amount of heap objects 
for both value types by one order of magnitude, which among other benefits also
reduces GC overhead.
Permalink
Failed to load latest commit information.
Cabal Initial minimal documentation for `--index-state` Sep 24, 2016
cabal-install Use hash-consing to optimise index cache (#3897) Sep 25, 2016
.arcconfig Add arcconfig, so arc diff works with phabricator.haskell.org. Sep 24, 2015
.gitignore Docs: added cabal domain for sphinx Sep 16, 2016
.mailmap Update AUTHORS. Sep 18, 2016
.mention-bot Update .mention-bot Sep 16, 2016
.travis.yml Whitelist branches for travis to build Sep 20, 2016
AUTHORS Update AUTHORS. Sep 18, 2016
LICENSE Update LICENSE May 9, 2016
README.md Update the GHC compatibility policy. Sep 16, 2016
appveyor.yml Update hackage index before running integration tests Sep 14, 2016
cabal.project Experiment with using -fno-ignore-asserts in more places Sep 9, 2016
cabal.project.travis Revert "Try top-level -Werror." Aug 6, 2016
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 stack.yaml/nix: add required build and test tools Sep 1, 2016
travis-bootstrap.sh Add || exit $? to all subshell calls Jul 27, 2016
travis-common.sh Add || exit $? to all subshell calls Jul 27, 2016
travis-deploy.sh More haddocks uploading fixes. Jul 22, 2016
travis-install.sh Rewrite Travis CI script. Jul 21, 2016
travis-meta.sh Add || exit $? to all subshell calls Jul 27, 2016
travis-script.sh CI: Only test Cabal lib on GHC 7.4. Sep 16, 2016
update-cabal-files.sh Add useful update-cabal-files utility script. Apr 10, 2016

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

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)

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-install

To build a local, development copy of cabal-install. The binary will be located at dist-newstyle/build/cabal-install-$VERSION/build/cabal/cabal; you can determine the $VERSION of cabal-install by looking at cabal-install/cabal-install.cabal.

Here are some other useful variations on the commands:

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

Running tests

Using Travis and AppVeyor. The easiest 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. Alternately, you can enable Travis on your fork in your own username and Travis should build your local branches.

Some tips for using Travis effectively:

  • 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.

  • If you enable Travis for the fork of Cabal in your local GitHub, you can have builds done automatically for your local branch seperate from Cabal. This is an alternative to opening a PR.

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. In general, the test executable for {Cabal,cabal-install}:$TESTNAME will be stored at dist-newstyle/build/{Cabal,cabal-install}-$VERSION/build/$TESTNAME/$TESTNAME.

To run a single test, use -p which applies a regex filter to the test names.

  • Cabal:package-tests are out-of-process integration tests on the top-level Setup command line interface. If you are hacking on the Cabal library you want to run this test suite. It must be run from the Cabal subdirectory (ugh!) This test suite can be a bit touchy; see Cabal/tests/README.md for more information. Build products and test logs are generated and stored in Cabal/tests/PackageTests under folders named dist-test and dist-test.$subname.

    Handy command line spell to find test logs is:

    find . -name test.log|grep test-name

    test.sh in the same directory as test.log is intended to let you rerun the test without running the actual test driver.

  • 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-tests are out-of-process integration tests on the top-level cabal command line interface. The coverage is not very good but it attempts to exercise most of cabal-install.

  • cabal-install:integration-tests2 are integration tests on some top-level API functions inside the cabal-install source code. You should also run this test suite.

Conventions

  • Spaces, not tabs.

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

  • 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.

  • 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 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!)

  • 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.

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. #ghc 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/.