The cabal-install package

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

2.2.0.0 Mikhail Glushenkov <mikhail.glushenkov@gmail.com> March 2018 * '--with-PROG' and '--PROG-options' are applied to all packages and not local packages only (#5019). * Completed the 'new-update' command (#4809), which respects nix-style cabal.project(.local) files and allows to update from multiple repositories when using overlays. * Completed the 'new-run' command (#4477). The functionality is the same of the old 'run' command but using nix-style builds. Additionally, it can run executables across packages in a project. Tests and benchmarks are also treated as executables, providing a quick way to pass them arguments. * Completed the 'new-bench' command (#3638). Same as above. * Completed the 'new-exec' command (#3638). Same as above. * Added a preliminary 'new-install' command (#4558, nonlocal exes part) which allows to quickly install executables from Hackage. * Set symlink-bindir (used by new-install) to .cabal/bin by default on .cabal/config initialization (#5188). * 'cabal update' now supports '--index-state' which can be used to roll back the index to an earlier state. * '--allow-{newer,older}' syntax has been enhanced. Dependency relaxation can be now limited to a specific release of a package, plus there's a new syntax for relaxing only caret-style (i.e. '^>=') dependencies (#4575, #4669). * New config file field: 'cxx-options' to specify which options to be passed to the compiler when compiling C++ sources specified by the 'cxx-sources' field. (#3700) * New config file field: 'cxx-sources' to specify C++ files to be compiled separately from C source files. Useful in conjunction with the 'cxx-options' flag to pass different compiler options to C and C++ source files. (#3700) * Use [lfxtb] letters to differentiate component kind instead of opaque "c" in dist-dir layout. * 'cabal configure' now supports '--enable-static', which can be used to build static libaries with GHC via GHC's `-staticlib` flag. * 'cabal user-config now supports '--augment' which can append additional lines to a new or updated cabal config file. * Added support for '--enable-tests' and '--enable-benchmarks' to 'cabal fetch' (#4948). * Misspelled package-names on CLI will no longer be silently case-corrected (#4778). * 'cabal new-configure' now backs up the old 'cabal.project.local' file if it exists (#4460). * On macOS, `new-build` will now place dynamic libraries into `store/lib` and aggressively shorten their names in an effort to stay within the load command size limits of macOSs mach-o linker. * 'new-build' now checks for the existence of executables for build-tools and build-tool-depends dependencies in the solver (#4884). * Fixed a spurious warning telling the user to run 'cabal update' when it wasn't necessary (#4444). * Packages installed in sandboxes via 'add-source' now have their timestamps updated correctly and so will not be reinstalled unncecessarily if the main install command fails (#1375). * Add Windows device path support for copyFile, renameFile. Allows cabal new-build to use temporary store path of up to 32k length (#3972, #4914, #4515). * When a flag value is specified multiple times on the command line, the last one is now preferred, so e.g. '-f+dev -f-dev' is now equivalent to '-f-dev' (#4452). * Removed support for building cabal-install with GHC < 7.10 (#4870). * New 'package *' section in 'cabal.project' files that applies options to all packages, not just those local to the project. * Paths_ autogen modules now compile when `RebindableSyntax` or `OverloadedStrings` is used in `default-extensions`. [stack#3789](https://github.com/commercialhaskell/stack/issues/3789) * getDataDir` and other `Paths_autogen` functions now work correctly when compiling a custom `Setup.hs` script using `new-build` (#5164).

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

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