Maintainer's Corner

Readme for cabal-bounds-1.0.4

cabal-bounds

A command line program for managing the bounds/versions of the dependencies in a cabal file.

cabal-bounds is able to do these things with the bounds of the dependencies in the cabal file:

drop them

update them by the library versions of the current cabal build

update them by the library versions of a haskell platform release

update them by the library versions specified by a file

dump the libraries/dependencies and their lower bound versions from the cabal file(s) into a file

Example: Initialize Bounds

If you have started a new project, created a cabal file, added dependencies to it,
build it, and now want to set the lower and upper bounds of the dependencies
according to the currently used versions of the build, then you can just call:

$> cabal-bounds update

This call will update the bounds of the dependencies of the cabal file in the working directory.

Example: Raise the Upper Bounds

If you have several cabalized projects, then it can be quite time consuming to keep the
bounds of your dependencies up to date. Especially if you're following the package versioning policy,
then you want to raise your upper bounds from time to time, to allow the building with newer
versions of the dependencies.

cabal-bounds tries to automate this update process to some degree. So a typical update process might look like:

# update the version infos of all libraries
$> cabal update
# drops the upper bound of all dependencies of the cabal file in the working directory
$> cabal-bounds drop --upper
# create a cabal sandbox for building your project, this ensures that you're really using
# the newest available versions of the dependencies, otherwise you would be constraint
# to the already installed versions
$> cabal sandbox init
# build your project
$> cabal install
# update the upper bound of all dependencies of the cabal file in the working directory
$> cabal-bounds update --upper

Example: Update Bounds by Haskell Platform

Ensuring that your project builds with the current haskell platform - or
perhaps the last two ones - can make it, especially for beginners, a lot easier to build your project.

cabal-bounds supports the updating of the bounds by the library versions of a specific haskell platform release.

To update the bounds to the haskell platform 2013.2.0.0:

$> cabal-bounds update --haskell-platform=2013.2.0.0

There're two additional symbolic names for specifying a haskell platform release: current and previous.

So one use case might be to initialize the bounds to library versions used by a haskell platform release,
test if your project builds and works with these, and then raise the upper bounds to the newest available versions:

# intialize the bounds to the previous haskell platform release
$> cabal-bounds update --haskell-platform=previous
# build and test the project
# initialize the lower bounds of libraries not present in the haskell platform
$> cabal-bounds update --lower --missing
# drop the upper bounds to test your project with the newest available library versions
$> cabal-bounds drop --upper
# build and test the project
# set the upper bounds to the ones used in the current build
$> cabal-bounds update --upper

Example: Update Bounds by File

It's also possible to update the bounds by library versions specified in a file:

$> cabal-bounds update --fromfile=libs.hs

The libs.hs file has to be of the format:

[ ("libA", [0,2,1]), ("libB", [2,1]), ("libC", [1]) ]

If you specify a library file and a haskell platform release at once, then first the
haskell platform libraries and versions are considered and then the library file.

The library file can be created by the dump command:

$> cabal-bounds dump --output=libs.hs

The dump command will dump dependencies with their lower bound version. The command can take multiple cabal files.
If the same dependencies is present in multiple files, then the lowest lower bound version is taken.

Example: Bound Changes

The => shows what the result is of the operation for every dependency. Left is the dependency before
calling the command, right the one after calling.