cabal-install

The command-line interface for Cabal and Hackage. http://www.haskell.org/cabal/

LTS Haskell 8.12:1.24.0.2
Stackage Nightly 2017-04-27:1.24.0.2
Latest on Hackage:1.24.0.2

The cabal-install package

See the Cabal web site for more information.

The cabal-install package provides a command line tool named cabal. It uses the Cabal library and provides a user interface to the Cabal/Hackage build automation and package management system. It can build and install both local and remote packages, including dependencies.

Installing the cabal command-line tool

The cabal-install package requires a number of other packages, most of which come with a standard GHC installation. It requires the network package, which is sometimes packaged separately by Linux distributions; for example, on Debian or Ubuntu, it is located in the "libghc6-network-dev" package.

cabal requires a few other Haskell packages that are not always installed. The exact list is specified in the .cabal file or in the bootstrap.sh file. All these packages are available from Hackage.

Note that on some Unix systems you may need to install an additional zlib development package using your system package manager; for example, on Debian or Ubuntu, it is located in the "zlib1g-dev" package; on Fedora, it is located in the "zlib-devel" package. It is required because the Haskell zlib package uses the system zlib C library and header files.

The cabal-install package is now part of the Haskell Platform, so you do not usually need to install it separately. However, if you are starting from a minimal GHC installation, you need to install cabal-install manually. Since it is an ordinary Cabal package, cabal-install can be built the standard way; to facilitate this, the process has been partially automated. It is described below.

Quick start on Unix-like systems

As a convenience for users on Unix-like systems, there is a bootstrap.sh script that will download and install each of cabal-install's dependencies in turn.

$ ./bootstrap.sh

It will download and install the dependencies. The script will install the library packages (vanilla, profiling and shared) into $HOME/.cabal/ and the cabal program into $HOME/.cabal/bin/. If you don't want to install profiling and shared versions of the libraries, use

$ EXTRA_CONFIGURE_OPTS="" ./bootstrap.sh

You then have the choice either to place $HOME/.cabal/bin on your $PATH or move the cabal program to somewhere on your $PATH. Next, you can get the latest list of packages by running:

$ cabal update

This will also create a default configuration file, if it does not already exist, at $HOME/.cabal/config.

By default, cabal will install programs to $HOME/.cabal/bin. If you do not want to add this directory to your $PATH, you can change the setting in the config file; for example, you could use the following:

symlink-bindir: $HOME/bin

Quick start on Windows systems

For Windows users, a precompiled program (cabal.exe) is provided. Download and put it somewhere on your %PATH% (for example, C:\Program Files\Haskell\bin.)

Next, you can get the latest list of packages by running:

$ cabal update

This will also create a default configuration file (if it does not already exist) at C:\Documents and Settings\%USERNAME%\Application Data\cabal\config.

Using cabal

There are two sets of commands: commands for working with a local project build tree and those for working with packages distributed from Hackage.

For the list of the full set of commands and flags for each command, run:

$ cabal help

Commands for developers for local build trees

The commands for local project build trees are almost the same as the runghc Setup command-line interface you may already be familiar with. In particular, it has the following commands:

  • cabal configure
  • cabal build
  • cabal haddock
  • cabal clean
  • cabal sdist

The install command is somewhat different; it is an all-in-one operation. If you run cabal install in your build tree, it will configure, build, and install. It takes all the flags that configure takes such as --global and --prefix.

In addition, cabal will download and install any dependencies that are not already installed. It can also rebuild packages to ensure a consistent set of dependencies.

Commands for released Hackage packages

$ cabal update

This command gets the latest list of packages from the Hackage server. On occasion, this command must be run manually--for instance, if you want to install a newly released package.

$ cabal install xmonad

This command installs one or more named packages, and all their dependencies, from Hackage. By default, it installs the latest available version; however, you may specify exact versions or version ranges. For example, cabal install alex-2.2 or cabal install parsec < 3.

$ cabal list xml

This does a search of the installed and available packages. It does a case-insensitive substring match on the package name.

Changes

-*-change-log-*-
1.24.0.2 Mikhail Glushenkov <mikhail.glushenkov@gmail.com> December 2016
* Adapted to the revert of a PVP-noncompliant API change in
Cabal 1.24.2.0 (#4123).
* Bumped the directory upper bound to < 1.4 (#4158).

1.24.0.1 Ryan Thomas <ryan@ryant.org> October 2016
* Fixed issue with passing '--enable-profiling' when invoking
Setup scripts built with older versions of Cabal (#3873).
* Fixed various behaviour differences between network transports
(#3429).
* Updated to depend on the latest hackage-security that fixes
various issues on Windows.
* Fixed 'new-build' to exit with a non-zero exit code on failure
(#3506).
* Store secure repo index data as 01-index.* (#3862).
* Added new hackage-security root keys for distribution with
cabal-install.
* Fix an issue where 'cabal install' sometimes had to be run twice
for packages with build-type: Custom and a custom-setup stanza
(#3723).
* 'cabal sdist' no longer ignores '--builddir' when the package's
build-type is Custom (#3794).

1.24.0.0 Ryan Thomas <ryan@ryant.org> May 2016
* If there are multiple remote repos, 'cabal update' now updates
them in parallel (#2503).
* New 'cabal upload' option '-P'/'--password-command' for reading
Hackage password from arbitrary program output (#2506).
* Better warning for 'cabal run' (#2510).
* 'cabal init' now warns if the chosen package name is already
registered in the source package index (#2436).
* New 'cabal install' option: '--offline' (#2578).
* Accept 'builddir' field in cabal.config (#2484)
* Read 'builddir' option from 'CABAL_BUILDDIR' environment variable.
* Remote repos may now be configured to use https URLs. This uses
either curl or wget or, on Windows, PowerShell, under the hood (#2687).
* Install target URLs can now use https e.g. 'cabal install
https://example.com/foo-1.0.tar.gz'.
* Automatically use https for cabal upload for the main
hackage.haskell.org (other repos will use whatever they are
configured to use).
* Support for dependencies of custom Setup.hs scripts
(see http://www.well-typed.com/blog/2015/07/cabal-setup-deps/).
* 'cabal' program itself now can be used as an external setup
method. This fixes an issue when Cabal version mismatch caused
unnecessary reconfigures (#2633).
* Improved error message for unsatisfiable package constraints
(#2727).
* Fixed a space leak in 'cabal update' (#2826).
* 'cabal exec' and 'sandbox hc-pkg' now use the configured
compiler (#2859).
* New 'cabal haddock' option: '--for-hackage' (#2852).
* Added a warning when the solver cannot find a dependency (#2853).
* New 'cabal upload' option: '--doc': upload documentation to
hackage (#2890).
* Improved error handling for 'sandbox delete-source' (#2943).
* Solver support for extension and language flavours (#2873).
* Support for secure repos using hackage-security (#2983).
* Added a log file message similar to one printed by 'make' when
building in another directory (#2642).
* Added new subcommand 'init' to 'cabal user-config'. This
subcommand creates a cabal configuration file in either the
default location or as specified by --config-file (#2553).
* The man page for 'cabal-install' is now automatically generated
(#2877).
* The '--allow-newer' option now works as expected when specified
multiple times (#2588).
* New config file field: 'extra-framework-dirs' (extra locations
to find OS X frameworks in). Can be also specified as an argument
for 'install' and 'configure' commands (#3158).
* It's now possible to limit the scope of '--allow-newer' to
single packages in the install plan (#2756).
* Full '--allow-newer' syntax is now supported in the config file
(that is, 'allow-newer: base, ghc-prim, some-package:vector')
(#3171).
* Improved performance of '--reorder-goals' (#3208).
* Fixed space leaks in modular solver (#2916, #2914).
* Made the solver aware of pkg-config constraints (#3023).
* Added a new command: 'gen-bounds' (#3223). See
http://softwaresimply.blogspot.se/2015/08/cabal-gen-bounds-easy-generation-of.html.
* Tech preview of new nix-style isolated project-based builds.
Currently provides the commands (new-)build/repl/configure.

1.22.0.0 Johan Tibell <johan.tibell@gmail.com> January 2015
* New command: user-config (#2159).
* Implement 'cabal repl --only' (#2016).
* Fix an issue when 'cabal repl' was doing unnecessary compilation
(#1715).
* Prompt the user to specify source directory in 'cabal init'
(#1989).
* Remove the self-upgrade check (#2090).
* Don't redownload already downloaded packages when bootstrapping
(#2133).
* Support sandboxes in 'bootstrap.sh' (#2137).
* Install profiling and shared libs by default in 'bootstrap.sh'
(#2009).

1.20.0.3 Johan Tibell <johan.tibell@gmail.com> June 2014
* Don't attempt to rename dist if it is already named correctly
* Treat all flags of a package as interdependent.
* Allow template-haskell to be upgradable again

1.20.0.2 Johan Tibell <johan.tibell@gmail.com> May 2014
* Increase max-backjumps to 2000.
* Fix solver bug which led to missed install plans.
* Fix streaming test output.
* Tweak solver heuristics to avoid reinstalls.

1.20.0.1 Johan Tibell <johan.tibell@gmail.com> May 2014
* Fix cabal repl search path bug on Windows
* Include OS and arch in cabal-install user agent
* Revert --constraint flag behavior in configure to 1.18 behavior

1.20.0.0 Johan Tibell <johan.tibell@gmail.com> April 2014
* Build only selected executables
* Add -j flag to build/test/bench/run
* Improve install log file
* Don't symlink executables when in a sandbox
* Add --package-db flag to 'list' and 'info'
* Make upload more efficient
* Add --require-sandbox option
* Add experimental Cabal file format command
* Add haddock section to config file
* Add --main-is flag to init

0.14.0 Andres Loeh <andres@well-typed.com> April 2012
* Works with ghc-7.4
* Completely new modular dependency solver (default in most cases)
* Some tweaks to old topdown dependency solver
* Install plans are now checked for reinstalls that break packages
* Flags --constraint and --preference work for nonexisting packages
* New constraint forms for source and installed packages
* New constraint form for package-specific use flags
* New constraint form for package-specific stanza flags
* Test suite dependencies are pulled in on demand
* No longer install packages on --enable-tests when tests fail
* New "cabal bench" command
* Various "cabal init" tweaks

0.10.0 Duncan Coutts <duncan@community.haskell.org> February 2011
* New package targets: local dirs, local and remote tarballs
* Initial support for a "world" package target
* Partial fix for situation where user packages mask global ones
* Removed cabal upgrade, new --upgrade-dependencies flag
* New cabal install --only-dependencies flag
* New cabal fetch --no-dependencies and --dry-run flags
* Improved output for cabal info
* Simpler and faster bash command line completion
* Fix for broken proxies that decompress wrongly
* Fix for cabal unpack to preserve executable permissions
* Adjusted the output for the -v verbosity level in a few places

0.8.2 Duncan Coutts <duncan@community.haskell.org> March 2010
* Fix for cabal update on Windows
* On windows switch to per-user installs (rather than global)
* Handle intra-package dependencies in dependency planning
* Minor tweaks to cabal init feature
* Fix various -Wall warnings
* Fix for cabal sdist --snapshot

0.8.0 Duncan Coutts <duncan@haskell.org> Dec 2009
* Works with ghc-6.12
* New "cabal init" command for making initial project .cabal file
* New feature to maintain an index of haddock documentation

0.6.4 Duncan Coutts <duncan@haskell.org> Nov 2009
* Improve the algorithm for selecting the base package version
* Hackage errors now reported by "cabal upload [--check]"
* Improved format of messages from "cabal check"
* Config file can now be selected by an env var
* Updated tar reading/writing code
* Improve instructions in the README and bootstrap output
* Fix bootstrap.sh on Solaris 9
* Fix bootstrap for systems where network uses parsec 3
* Fix building with ghc-6.6

0.6.2 Duncan Coutts <duncan@haskell.org> Feb 2009
* The upgrade command has been disabled in this release
* The configure and install commands now have consistent behaviour
* Reduce the tendancy to re-install already existing packages
* The --constraint= flag now works for the install command
* New --preference= flag for soft constraints / version preferences
* Improved bootstrap.sh script, smarter and better error checking
* New cabal info command to display detailed info on packages
* New cabal unpack command to download and untar a package
* HTTP-4000 package required, should fix bugs with http proxies
* Now works with authenticated proxies.
* On Windows can now override the proxy setting using an env var
* Fix compatability with config files generated by older versions
* Warn if the hackage package list is very old
* More helpful --help output, mention config file and examples
* Better documentation in ~/.cabal/config file
* Improved command line interface for logging and build reporting
* Minor improvements to some messages

0.6.0 Duncan Coutts <duncan@haskell.org> Oct 2008
* Constraint solver can now cope with base 3 and base 4
* Allow use of package version preferences from hackage index
* More detailed output from cabal install --dry-run -v
* Improved bootstrap.sh

0.5.2 Duncan Coutts <duncan@haskell.org> Aug 2008
* Suport building haddock documentaion
* Self-reinstall now works on Windows
* Allow adding symlinks to excutables into a separate bindir
* New self-documenting config file
* New install --reinstall flag
* More helpful status messages in a couple places
* Upload failures now report full text error message from the server
* Support for local package repositories
* New build logging and reporting
* New command to upload build reports to (a compatible) server
* Allow tilde in hackage server URIs
* Internal code improvements
* Many other minor improvements and bug fixes

0.5.1 Duncan Coutts <duncan@haskell.org> June 2008
* Restore minimal hugs support in dependency resolver
* Fix for disabled http proxies on Windows
* Revert to global installs on Windows by default

0.5.0 Duncan Coutts <duncan@haskell.org> June 2008
* New package dependency resolver, solving diamond dep problem
* Integrate cabal-setup functionality
* Integrate cabal-upload functionality
* New cabal update and check commands
* Improved behavior for install and upgrade commands
* Full Windows support
* New command line handling
* Bash command line completion
* Allow case insensitive package names on command line
* New --dry-run flag for install, upgrade and fetch commands
* New --root-cmd flag to allow installing as root
* New --cabal-lib-version flag to select different Cabal lib versions
* Support for HTTP proxies
* Improved cabal list output
* Build other non-dependent packages even when some fail
* Report a summary of all build failures at the end
* Partial support for hugs
* Partial implementation of build reporting and logging
* More consistent logging and verbosity
* Significant internal code restructuring

0.4 Duncan Coutts <duncan@haskell.org> Oct 2007
* Renamed executable from 'cabal-install' to 'cabal'
* Partial Windows compatability
* Do per-user installs by default
* cabal install now installs the package in the current directory
* Allow multiple remote servers
* Use zlib lib and internal tar code and rather than external tar
* Reorganised configuration files
* Significant code restructuring
* Cope with packages with conditional dependencies

0.3 and older versions by Lemmih, Paolo Martini and others 2006-2007
* Switch from smart-server, dumb-client model to the reverse
* New .tar.gz based index format
* New remote and local package archive format
comments powered byDisqus