|
Command line interface to the Haskell Cabal infrastructure. |
|
|
|
See http://www.haskell.org/cabal/ for more information. |
|
|
|
Usage: cabal [GLOBAL FLAGS] [COMMAND [FLAGS]] |
|
|
|
Commands: |
|
[global] |
|
update Updates list of known packages. |
|
install Install packages. |
|
|
|
help Help about commands. |
|
info Display detailed information about a particular package. |
|
list List packages matching a search string. |
|
fetch Downloads packages for later installation. |
|
user-config Display and update the user's global cabal configuration. |
|
|
|
[package] |
|
get Download/Extract a package's source code (repository). |
|
init Create a new .cabal package file (interactively). |
|
|
|
configure Prepare to build the package. |
|
build Compile all/specific components. |
|
clean Clean up after a build. |
|
|
|
run Builds and runs an executable. |
|
repl Open an interpreter session for the given component. |
|
test Run all/specific tests in the test suite. |
|
bench Run all/specific benchmarks. |
|
|
|
check Check the package for common mistakes. |
|
sdist Generate a source distribution file (.tar.gz). |
|
upload Uploads source packages to Hackage. |
|
report Upload build reports to a remote server. |
|
|
|
freeze Freeze dependencies. |
|
haddock Generate Haddock HTML documentation. |
|
hscolour Generate HsColour colourised code, in HTML format. |
|
copy Copy the files into the install locations. |
|
register Register this package with the compiler. |
|
|
|
[sandbox] |
|
exec Give a command access to the sandbox package repository. |
|
repl Open interpreter with access to sandbox packages. |
|
|
|
For more information about a command use: |
|
cabal COMMAND --help |
|
or cabal help COMMAND |
|
|
|
To install Cabal packages from hackage use: |
|
cabal install foo [--dry-run] |
|
|
|
Occasionally you need to update the list of available packages: |
|
cabal update |
|
|
|
Global flags: |
|
-h --help Show this help text |
|
-V --version Print version information |
|
--numeric-version Print just the version number |
|
--config-file=FILE Set an alternate location for the config file |
|
--sandbox-config-file=FILE Set an alternate location for the sandbox config |
|
file (default: './cabal.sandbox.config') |
|
--require-sandbox Enable requiring the presence of a sandbox for |
|
sandbox-aware commands |
|
--no-require-sandbox Disable requiring the presence of a sandbox for |
|
sandbox-aware commands |
|
--ignore-sandbox Ignore any existing sandbox |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
|
========================== |
|
install |
|
========================== |
|
Install packages. |
|
|
|
Usage: cabal install [FLAGS] |
|
or: cabal install [FLAGS] PACKAGES |
|
|
|
Installs one or more packages. By default, the installed package will be |
|
registered in the user's package database or, if a sandbox is present in the |
|
current directory, inside the sandbox. |
|
|
|
If PACKAGES are specified, downloads and installs those packages. Otherwise, |
|
install the package in the current directory (and/or its dependencies) (there |
|
must be exactly one .cabal file in the current directory). |
|
|
|
When using a sandbox, the flags for `install` only affect the current command |
|
and have no effect on future commands. (To achieve that, `configure` must be |
|
used.) |
|
In contrast, without a sandbox, the flags to `install` are saved and affect |
|
future commands such as `build` and `repl`. See the help for `configure` for a |
|
list of commands being affected. |
|
|
|
Flags for install: |
|
-h --help Show this help text |
|
-v --verbose[=n] Control verbosity (n is 0--3, default |
|
verbosity level is 1) |
|
--builddir=DIR The directory where Cabal puts generated |
|
build files (default dist) |
|
-g --ghc compile with GHC |
|
--jhc compile with JHC |
|
--lhc compile with LHC |
|
--uhc compile with UHC |
|
--haskell-suite compile with a haskell-suite compiler |
|
-w --with-compiler=PATH give the path to a particular compiler |
|
--with-hc-pkg=PATH give the path to the package tool |
|
--prefix=DIR bake this prefix in preparation of |
|
installation |
|
--bindir=DIR installation directory for executables |
|
--libdir=DIR installation directory for libraries |
|
--libsubdir=DIR subdirectory of libdir in which libs are |
|
installed |
|
--libexecdir=DIR installation directory for program |
|
executables |
|
--datadir=DIR installation directory for read-only data |
|
--datasubdir=DIR subdirectory of datadir in which data files |
|
are installed |
|
--docdir=DIR installation directory for documentation |
|
--htmldir=DIR installation directory for HTML |
|
documentation |
|
--haddockdir=DIR installation directory for haddock |
|
interfaces |
|
--sysconfdir=DIR installation directory for configuration |
|
files |
|
--program-prefix=PREFIX prefix to be applied to installed |
|
executables |
|
--program-suffix=SUFFIX suffix to be applied to installed |
|
executables |
|
--enable-library-vanilla Enable Vanilla libraries |
|
--disable-library-vanilla Disable Vanilla libraries |
|
-p --enable-library-profiling Enable Library profiling |
|
--disable-library-profiling Disable Library profiling |
|
--enable-shared Enable Shared library |
|
--disable-shared Disable Shared library |
|
--enable-executable-dynamic Enable Executable dynamic linking |
|
--disable-executable-dynamic Disable Executable dynamic linking |
|
--enable-executable-profiling Enable Executable profiling |
|
--disable-executable-profiling Disable Executable profiling |
|
-O --enable-optimization[=n] Build with optimization (n is 0--2, default |
|
is 1) |
|
--disable-optimization Build without optimization |
|
--enable-library-for-ghci Enable compile library for use with GHCi |
|
--disable-library-for-ghci Disable compile library for use with GHCi |
|
--enable-split-objs Enable split library into smaller objects |
|
to reduce binary sizes (GHC 6.6+) |
|
--disable-split-objs Disable split library into smaller objects |
|
to reduce binary sizes (GHC 6.6+) |
|
--enable-executable-stripping Enable strip executables upon installation |
|
to reduce binary sizes |
|
--disable-executable-stripping Disable strip executables upon installation |
|
to reduce binary sizes |
|
--enable-library-stripping Enable strip libraries upon installation to |
|
reduce binary sizes |
|
--disable-library-stripping Disable strip libraries upon installation |
|
to reduce binary sizes |
|
--configure-option=OPT Extra option for configure |
|
--user Enable doing a per-user installation |
|
--global Disable doing a per-user installation |
|
--package-db=DB Use a given package database (to satisfy |
|
dependencies and register in). May be a |
|
specific file, 'global', 'user' or 'clear'. |
|
-f --flags=FLAGS Force values for the given flags in Cabal |
|
conditionals in the .cabal file. E.g., |
|
--flags="debug -usebytestrings" forces the |
|
flag "debug" to true and "usebytestrings" |
|
to false. |
|
--extra-include-dirs=PATH A list of directories to search for header |
|
files |
|
--extra-lib-dirs=PATH A list of directories to search for |
|
external libraries |
|
--extra-prog-path=PATH A list of directories to search for |
|
required programs (in addition to the |
|
normal search locations) |
|
--instantiate-with=NAME=PKG:MOD A mapping of signature names to concrete |
|
module instantiations. E.g., |
|
--instantiate-with="Map=Data.Map.Strict@containers-0.5.5.1-inplace" |
|
--enable-tests Enable dependency checking and compilation |
|
for test suites listed in the package |
|
description file. |
|
--disable-tests Disable dependency checking and compilation |
|
for test suites listed in the package |
|
description file. |
|
--enable-library-coverage Enable OBSOLETE. Please use |
|
--enable-coverage instead. |
|
--disable-library-coverage Disable OBSOLETE. Please use |
|
--enable-coverage instead. |
|
--enable-coverage Enable build package with Haskell Program |
|
Coverage enabled. (GHC only) |
|
--disable-coverage Disable build package with Haskell Program |
|
Coverage enabled. (GHC only) |
|
--enable-benchmarks Enable dependency checking and compilation |
|
for benchmarks listed in the package |
|
description file. |
|
--disable-benchmarks Disable dependency checking and compilation |
|
for benchmarks listed in the package |
|
description file. |
|
--with-PROG=PATH give the path to PROG |
|
--PROG-option=OPT give an extra option to PROG (no need to |
|
quote options containing spaces) |
|
--PROG-options=OPTS give extra options to PROG |
|
--cabal-lib-version=VERSION Select which version of the Cabal lib to |
|
use to build packages (useful for testing). |
|
--constraint=CONSTRAINT Specify constraints on a package (version, |
|
installed/source, flags) |
|
--preference=CONSTRAINT Specify preferences (soft constraints) on |
|
the version of a package |
|
--solver=SOLVER Select dependency solver to use (default: |
|
choose). Choices: topdown, modular, choose, |
|
where 'choose' chooses between 'topdown' |
|
and 'modular' based on compiler version. |
|
--allow-newer[=DEPS] Ignore upper bounds in all dependencies or |
|
DEPS |
|
--enable-documentation Enable building of documentation |
|
--disable-documentation Disable building of documentation |
|
--doc-index-file=TEMPLATE A central index of haddock API |
|
documentation (template cannot use $pkgid) |
|
--dry-run Do not install anything, only print what |
|
would be installed. |
|
--max-backjumps=NUM Maximum number of backjumps allowed while |
|
solving (default: 2000). Use a negative |
|
number to enable unlimited backtracking. |
|
Use 0 to disable backtracking completely. |
|
--reorder-goals Try to reorder goals according to certain |
|
heuristics. Slows things down on average, |
|
but may make backtracking faster for some |
|
packages. |
|
--shadow-installed-packages If multiple package instances of the same |
|
version are installed, treat all but one as |
|
shadowed. |
|
--strong-flags Do not defer flag choices (this used to be |
|
the default in cabal-install <= 1.20). |
|
--reinstall Install even if it means installing the |
|
same version again. |
|
--avoid-reinstalls Do not select versions that would |
|
destructively overwrite installed packages. |
|
--force-reinstalls Reinstall packages even if they will most |
|
likely break other installed packages. |
|
--upgrade-dependencies Pick the latest version for all |
|
dependencies, rather than trying to pick an |
|
installed version. |
|
--only-dependencies Install only the dependencies necessary to |
|
build the given packages |
|
--dependencies-only A synonym for --only-dependencies |
|
--root-cmd=COMMAND Command used to gain root privileges, when |
|
installing with --global. |
|
--symlink-bindir=DIR Add symlinks to installed executables into |
|
this directory. |
|
--build-summary=TEMPLATE Save build summaries to file (name template |
|
can use $pkgid, $compiler, $os, $arch) |
|
--build-log=TEMPLATE Log all builds to file (name template can |
|
use $pkgid, $compiler, $os, $arch) |
|
--remote-build-reporting=LEVEL Generate build reports to send to a remote |
|
server (none, anonymous or detailed). |
|
--report-planning-failure Generate build reports when the dependency |
|
solver fails. This is used by the Hackage |
|
build bot. |
|
--one-shot Do not record the packages in the world |
|
file. |
|
--run-tests Run package test suites during |
|
installation. |
|
-j --jobs[=NUM] Run NUM jobs simultaneously (or '$ncpus' if |
|
no NUM is given). |
|
--haddock-hoogle Generate a hoogle database |
|
--haddock-html Generate HTML documentation (the default) |
|
--haddock-html-location=URL Location of HTML documentation for |
|
pre-requisite packages |
|
--haddock-executables Run haddock for Executables targets |
|
--haddock-tests Run haddock for Test Suite targets |
|
--haddock-benchmarks Run haddock for Benchmark targets |
|
--haddock-all Run haddock for all targets |
|
--haddock-internal Run haddock for internal modules and |
|
include all symbols |
|
--haddock-css=PATH Use PATH as the haddock stylesheet |
|
--haddock-hyperlink-source Hyperlink the documentation to the source |
|
code (using HsColour) |
|
--haddock-hscolour-css=PATH Use PATH as the HsColour stylesheet |
|
--haddock-contents-location=URL Bake URL in as the location for the |
|
contents page |
|
|
|
The flags --with-PROG and --PROG-option(s) can be used with the following programs: |
|
alex ar c2hs cpphs gcc ghc ghc-pkg greencard haddock happy haskell-suite |
|
haskell-suite-pkg hmake hpc hsc2hs hscolour jhc ld lhc lhc-pkg pkg-config |
|
strip tar uhc |
|
|
|
Examples: |
|
cabal install Package in the current directory |
|
cabal install foo Package from the hackage server |
|
cabal install foo-1.0 Specific version of a package |
|
cabal install 'foo < 2' Constrained package version |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
|
========================== |
|
update |
|
========================== |
|
Updates list of known packages. |
|
|
|
Usage: cabal update [FLAGS] |
|
|
|
For all known remote repositories, download the package list. |
|
|
|
Flags for update: |
|
-h --help Show this help text |
|
-v --verbose[=n] Control verbosity (n is 0--3, default verbosity level is 1) |
|
|
|
Relevant global configuration keys: |
|
remote-repo |
|
remote-repo-cache |
|
local-repo |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
|
========================== |
|
list |
|
========================== |
|
List packages matching a search string. |
|
|
|
Usage: cabal list [FLAGS] |
|
or: cabal list [FLAGS] STRINGS |
|
|
|
List all packages, or all packages matching one of the search strings. |
|
|
|
If there is a sandbox in the current directory and config:ignore-sandbox is |
|
False, use the sandbox package database. Otherwise, use the package database |
|
specified with --package-db. If not specified, use the user package database. |
|
|
|
Flags for list: |
|
-h --help Show this help text |
|
-v --verbose[=n] Control verbosity (n is 0--3, default verbosity level is 1) |
|
--installed Only print installed packages |
|
--simple-output Print in a easy-to-parse format |
|
--package-db=DB Use a given package database. May be a specific file, |
|
'global', 'user' or 'clear'. |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
|
========================== |
|
info |
|
========================== |
|
Display detailed information about a particular package. |
|
|
|
Usage: cabal info [FLAGS] PACKAGES |
|
|
|
If there is a sandbox in the current directory and config:ignore-sandbox is |
|
False, use the sandbox package database. Otherwise, use the package database |
|
specified with --package-db. If not specified, use the user package database. |
|
|
|
Flags for info: |
|
-h --help Show this help text |
|
-v --verbose[=n] Control verbosity (n is 0--3, default verbosity level is 1) |
|
--package-db=DB Use a given package database. May be a specific file, |
|
'global', 'user' or 'clear'. |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
|
========================== |
|
fetch |
|
========================== |
|
Downloads packages for later installation. |
|
|
|
Usage: cabal fetch [FLAGS] PACKAGES |
|
|
|
Note that it currently is not possible to fetch the dependencies for a |
|
package in the current directory. |
|
|
|
Flags for fetch: |
|
-h --help Show this help text |
|
-v --verbose[=n] Control verbosity (n is 0--3, default verbosity |
|
level is 1) |
|
--dependencies Resolve and fetch dependencies (default) |
|
--no-dependencies Ignore dependencies |
|
--dry-run Do not install anything, only print what would |
|
be installed. |
|
--solver=SOLVER Select dependency solver to use (default: |
|
choose). Choices: topdown, modular, choose, |
|
where 'choose' chooses between 'topdown' and |
|
'modular' based on compiler version. |
|
--max-backjumps=NUM Maximum number of backjumps allowed while |
|
solving (default: 2000). Use a negative number |
|
to enable unlimited backtracking. Use 0 to |
|
disable backtracking completely. |
|
--reorder-goals Try to reorder goals according to certain |
|
heuristics. Slows things down on average, but |
|
may make backtracking faster for some packages. |
|
--shadow-installed-packages If multiple package instances of the same |
|
version are installed, treat all but one as |
|
shadowed. |
|
--strong-flags Do not defer flag choices (this used to be the |
|
default in cabal-install <= 1.20). |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
|
========================== |
|
freeze |
|
========================== |
|
Freeze dependencies. |
|
|
|
Usage: cabal freeze |
|
or: cabal freeze PACKAGES |
|
|
|
Calculates a valid set of dependencies and their exact versions. If |
|
successful, saves the result to the file `cabal.config`. |
|
|
|
The package versions specified in `cabal.config` will be used for any future |
|
installs. |
|
|
|
An existing `cabal.config` is ignored and overwritten. |
|
|
|
Flags for freeze: |
|
-h --help Show this help text |
|
-v --verbose[=n] Control verbosity (n is 0--3, default verbosity |
|
level is 1) |
|
--dry-run Do not freeze anything, only print what would |
|
be frozen |
|
--enable-tests Enable freezing of the dependencies of any |
|
tests suites in the package description file. |
|
--disable-tests Disable freezing of the dependencies of any |
|
tests suites in the package description file. |
|
--enable-benchmarks Enable freezing of the dependencies of any |
|
benchmarks suites in the package description |
|
file. |
|
--disable-benchmarks Disable freezing of the dependencies of any |
|
benchmarks suites in the package description |
|
file. |
|
--solver=SOLVER Select dependency solver to use (default: |
|
choose). Choices: topdown, modular, choose, |
|
where 'choose' chooses between 'topdown' and |
|
'modular' based on compiler version. |
|
--max-backjumps=NUM Maximum number of backjumps allowed while |
|
solving (default: 2000). Use a negative number |
|
to enable unlimited backtracking. Use 0 to |
|
disable backtracking completely. |
|
--reorder-goals Try to reorder goals according to certain |
|
heuristics. Slows things down on average, but |
|
may make backtracking faster for some packages. |
|
--shadow-installed-packages If multiple package instances of the same |
|
version are installed, treat all but one as |
|
shadowed. |
|
--strong-flags Do not defer flag choices (this used to be the |
|
default in cabal-install <= 1.20). |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
|
========================== |
|
get |
|
========================== |
|
Download/Extract a package's source code (repository). |
|
|
|
Usage: cabal get [PACKAGES] |
|
|
|
Creates a local copy of a package's source code. By default it gets the source |
|
tarball and unpacks it in a local subdirectory. Alternatively, with -s it will |
|
get the code from the source repository specified by the package. |
|
|
|
Flags for get: |
|
-h --help Show this help text |
|
-v --verbose[=n] Control verbosity (n is 0--3, default |
|
verbosity level is 1) |
|
-d --destdir=PATH Where to place the package source, |
|
defaults to the current directory. |
|
-s --source-repository[=[head|this|...]] Copy the package's source repository |
|
(ie git clone, darcs get, etc as |
|
appropriate). |
|
--pristine Unpack the original pristine tarball, |
|
rather than updating the .cabal file |
|
with the latest revision from the |
|
package archive. |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
|
========================== |
|
check |
|
========================== |
|
Check the package for common mistakes. |
|
|
|
Usage: cabal check |
|
|
|
Expects a .cabal package file in the current directory. |
|
|
|
The checks correspond to the requirements to packages on Hackage. If no errors |
|
and warnings are reported, Hackage will accept this package. |
|
|
|
Flags for check: |
|
-h --help Show this help text |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
|
========================== |
|
sdist |
|
========================== |
|
Generate a source distribution file (.tar.gz). |
|
|
|
Usage: cabal sdist [FLAGS] |
|
|
|
Flags for sdist: |
|
-h --help Show this help text |
|
-v --verbose[=n] Control verbosity (n is 0--3, default verbosity |
|
level is 1) |
|
--builddir=DIR The directory where Cabal puts generated build files |
|
(default dist) |
|
--list-sources=FILE Just write a list of the package's sources to a file |
|
--snapshot Produce a snapshot source distribution |
|
--output-directory=DIR Generate a source distribution in the given |
|
directory, without creating a tarball |
|
--targz Produce a '.tar.gz' format archive (default and |
|
required for uploading to hackage) |
|
--zip Produce a '.zip' format archive |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
|
========================== |
|
upload |
|
========================== |
|
Uploads source packages to Hackage. |
|
|
|
Usage: cabal upload [FLAGS] TARFILES |
|
|
|
Flags for upload: |
|
-h --help Show this help text |
|
-v --verbose[=n] Control verbosity (n is 0--3, default verbosity level |
|
is 1) |
|
-c --check Do not upload, just do QA checks. |
|
-u --username=USERNAME Hackage username. |
|
-p --password=PASSWORD Hackage password. |
|
|
|
You can store your Hackage login in the ~/.cabal/config file |
|
Relevant global configuration keys: |
|
username |
|
password |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
|
========================== |
|
report |
|
========================== |
|
Upload build reports to a remote server. |
|
|
|
Usage: cabal report [FLAGS] |
|
|
|
Flags for report: |
|
-h --help Show this help text |
|
-v --verbose[=n] Control verbosity (n is 0--3, default verbosity level |
|
is 1) |
|
-u --username=USERNAME Hackage username. |
|
-p --password=PASSWORD Hackage password. |
|
|
|
You can store your Hackage login in the ~/.cabal/config file |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
|
========================== |
|
run |
|
========================== |
|
Builds and runs an executable. |
|
|
|
Usage: cabal run [FLAGS] [EXECUTABLE] [-- EXECUTABLE_FLAGS] |
|
|
|
Builds and then runs the specified executable. If no executable is specified, |
|
but the package contains just one executable, that one is built and executed. |
|
|
|
Flags for run: |
|
-h --help Show this help text |
|
-v --verbose[=n] Control verbosity (n is 0--3, default verbosity level |
|
is 1) |
|
--builddir=DIR The directory where Cabal puts generated build files |
|
(default dist) |
|
-j --jobs[=NUM] Run NUM jobs simultaneously (or '$ncpus' if no NUM is |
|
given). |
|
--with-PROG=PATH give the path to PROG |
|
--PROG-option=OPT give an extra option to PROG (no need to quote options |
|
containing spaces) |
|
--PROG-options=OPTS give extra options to PROG |
|
--only Don't reinstall add-source dependencies (sandbox-only) |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
|
========================== |
|
init |
|
========================== |
|
Create a new .cabal package file (interactively). |
|
|
|
Usage: cabal init [FLAGS] |
|
|
|
Cabalise a project by creating a .cabal, Setup.hs, and optionally a LICENSE |
|
file. |
|
|
|
Calling init with no arguments (recommended) uses an interactive mode, which |
|
will try to guess as much as possible and prompt you for the rest. |
|
Command-line arguments are provided for scripting purposes. If you don't want |
|
interactive mode, be sure to pass the -n flag. |
|
|
|
Flags for init: |
|
-h --help Show this help text |
|
-n --non-interactive Non-interactive mode. |
|
-q --quiet Do not generate log messages to stdout. |
|
--no-comments Do not generate explanatory comments in the |
|
.cabal file. |
|
-m --minimal Generate a minimal .cabal file, that is, do |
|
not include extra empty fields. Also implies |
|
--no-comments. |
|
--overwrite Overwrite any existing .cabal, LICENSE, or |
|
Setup.hs files without warning. |
|
--package-dir=DIRECTORY Root directory of the package (default = |
|
current directory). |
|
-p --package-name=PACKAGE Name of the Cabal package to create. |
|
--version=VERSION Initial version of the package. |
|
--cabal-version=VERSION_RANGE Required version of the Cabal library. |
|
-l --license=LICENSE Project license. |
|
-a --author=NAME Name of the project's author. |
|
-e --email=EMAIL Email address of the maintainer. |
|
-u --homepage=URL Project homepage and/or repository. |
|
-s --synopsis=TEXT Short project synopsis. |
|
-c --category=CATEGORY Project category. |
|
-x --extra-source-file=FILE Extra source file to be distributed with |
|
tarball. |
|
--is-library Build a library. |
|
--is-executable Build an executable. |
|
--main-is=FILE Specify the main module. |
|
--language=LANGUAGE Specify the default language. |
|
-o --expose-module=MODULE Export a module from the package. |
|
--extension=EXTENSION Use a LANGUAGE extension (in the |
|
other-extensions field). |
|
-d --dependency=PACKAGE Package dependency. |
|
--source-dir=DIR Directory containing package source. |
|
--build-tool=TOOL Required external build tool. |
|
-v --verbose[=n] Control verbosity (n is 0--3, default |
|
verbosity level is 1) |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
|
========================== |
|
configure |
|
========================== |
|
Prepare to build the package. |
|
|
|
Usage: cabal configure [FLAGS] |
|
|
|
Configure how the package is built by setting package (and other) flags. |
|
|
|
The configuration affects several other commands, including build, test, |
|
bench, run, repl. |
|
|
|
Flags for configure: |
|
-h --help Show this help text |
|
-v --verbose[=n] Control verbosity (n is 0--3, default |
|
verbosity level is 1) |
|
--builddir=DIR The directory where Cabal puts generated |
|
build files (default dist) |
|
-g --ghc compile with GHC |
|
--jhc compile with JHC |
|
--lhc compile with LHC |
|
--uhc compile with UHC |
|
--haskell-suite compile with a haskell-suite compiler |
|
-w --with-compiler=PATH give the path to a particular compiler |
|
--with-hc-pkg=PATH give the path to the package tool |
|
--prefix=DIR bake this prefix in preparation of |
|
installation |
|
--bindir=DIR installation directory for executables |
|
--libdir=DIR installation directory for libraries |
|
--libsubdir=DIR subdirectory of libdir in which libs are |
|
installed |
|
--libexecdir=DIR installation directory for program |
|
executables |
|
--datadir=DIR installation directory for read-only data |
|
--datasubdir=DIR subdirectory of datadir in which data files |
|
are installed |
|
--docdir=DIR installation directory for documentation |
|
--htmldir=DIR installation directory for HTML |
|
documentation |
|
--haddockdir=DIR installation directory for haddock |
|
interfaces |
|
--sysconfdir=DIR installation directory for configuration |
|
files |
|
--program-prefix=PREFIX prefix to be applied to installed |
|
executables |
|
--program-suffix=SUFFIX suffix to be applied to installed |
|
executables |
|
--enable-library-vanilla Enable Vanilla libraries |
|
--disable-library-vanilla Disable Vanilla libraries |
|
-p --enable-library-profiling Enable Library profiling |
|
--disable-library-profiling Disable Library profiling |
|
--enable-shared Enable Shared library |
|
--disable-shared Disable Shared library |
|
--enable-executable-dynamic Enable Executable dynamic linking |
|
--disable-executable-dynamic Disable Executable dynamic linking |
|
--enable-executable-profiling Enable Executable profiling |
|
--disable-executable-profiling Disable Executable profiling |
|
-O --enable-optimization[=n] Build with optimization (n is 0--2, default |
|
is 1) |
|
--disable-optimization Build without optimization |
|
--enable-library-for-ghci Enable compile library for use with GHCi |
|
--disable-library-for-ghci Disable compile library for use with GHCi |
|
--enable-split-objs Enable split library into smaller objects |
|
to reduce binary sizes (GHC 6.6+) |
|
--disable-split-objs Disable split library into smaller objects |
|
to reduce binary sizes (GHC 6.6+) |
|
--enable-executable-stripping Enable strip executables upon installation |
|
to reduce binary sizes |
|
--disable-executable-stripping Disable strip executables upon installation |
|
to reduce binary sizes |
|
--enable-library-stripping Enable strip libraries upon installation to |
|
reduce binary sizes |
|
--disable-library-stripping Disable strip libraries upon installation |
|
to reduce binary sizes |
|
--configure-option=OPT Extra option for configure |
|
--user Enable doing a per-user installation |
|
--global Disable doing a per-user installation |
|
--package-db=DB Use a given package database (to satisfy |
|
dependencies and register in). May be a |
|
specific file, 'global', 'user' or 'clear'. |
|
-f --flags=FLAGS Force values for the given flags in Cabal |
|
conditionals in the .cabal file. E.g., |
|
--flags="debug -usebytestrings" forces the |
|
flag "debug" to true and "usebytestrings" |
|
to false. |
|
--extra-include-dirs=PATH A list of directories to search for header |
|
files |
|
--extra-lib-dirs=PATH A list of directories to search for |
|
external libraries |
|
--extra-prog-path=PATH A list of directories to search for |
|
required programs (in addition to the |
|
normal search locations) |
|
--instantiate-with=NAME=PKG:MOD A mapping of signature names to concrete |
|
module instantiations. E.g., |
|
--instantiate-with="Map=Data.Map.Strict@containers-0.5.5.1-inplace" |
|
--enable-tests Enable dependency checking and compilation |
|
for test suites listed in the package |
|
description file. |
|
--disable-tests Disable dependency checking and compilation |
|
for test suites listed in the package |
|
description file. |
|
--enable-library-coverage Enable OBSOLETE. Please use |
|
--enable-coverage instead. |
|
--disable-library-coverage Disable OBSOLETE. Please use |
|
--enable-coverage instead. |
|
--enable-coverage Enable build package with Haskell Program |
|
Coverage enabled. (GHC only) |
|
--disable-coverage Disable build package with Haskell Program |
|
Coverage enabled. (GHC only) |
|
--enable-benchmarks Enable dependency checking and compilation |
|
for benchmarks listed in the package |
|
description file. |
|
--disable-benchmarks Disable dependency checking and compilation |
|
for benchmarks listed in the package |
|
description file. |
|
--with-PROG=PATH give the path to PROG |
|
--PROG-option=OPT give an extra option to PROG (no need to |
|
quote options containing spaces) |
|
--PROG-options=OPTS give extra options to PROG |
|
--cabal-lib-version=VERSION Select which version of the Cabal lib to |
|
use to build packages (useful for testing). |
|
--constraint=CONSTRAINT Specify constraints on a package (version, |
|
installed/source, flags) |
|
--preference=CONSTRAINT Specify preferences (soft constraints) on |
|
the version of a package |
|
--solver=SOLVER Select dependency solver to use (default: |
|
choose). Choices: topdown, modular, choose, |
|
where 'choose' chooses between 'topdown' |
|
and 'modular' based on compiler version. |
|
--allow-newer[=DEPS] Ignore upper bounds in all dependencies or |
|
DEPS |
|
|
|
The flags --with-PROG and --PROG-option(s) can be used with the following programs: |
|
alex ar c2hs cpphs gcc ghc ghc-pkg greencard haddock happy haskell-suite |
|
haskell-suite-pkg hmake hpc hsc2hs hscolour jhc ld lhc lhc-pkg pkg-config |
|
strip tar uhc |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
|
========================== |
|
build |
|
========================== |
|
Compile all/specific components. |
|
|
|
Usage: cabal build [FLAGS] |
|
or: cabal build COMPONENTS [FLAGS] |
|
|
|
Components encompass executables, tests, and benchmarks. |
|
|
|
Affected by configuration options, see `configure`. |
|
|
|
Flags for build: |
|
-h --help Show this help text |
|
-v --verbose[=n] Control verbosity (n is 0--3, default verbosity level |
|
is 1) |
|
--builddir=DIR The directory where Cabal puts generated build files |
|
(default dist) |
|
-j --jobs[=NUM] Run NUM jobs simultaneously (or '$ncpus' if no NUM is |
|
given). |
|
--with-PROG=PATH give the path to PROG |
|
--PROG-option=OPT give an extra option to PROG (no need to quote options |
|
containing spaces) |
|
--PROG-options=OPTS give extra options to PROG |
|
--only Don't reinstall add-source dependencies (sandbox-only) |
|
|
|
Examples: |
|
cabal build All the components in the package |
|
cabal build foo A component (i.e. lib, exe, test suite) |
|
|
|
The flags --with-PROG and --PROG-option(s) can be used with the following programs: |
|
alex ar c2hs cpphs gcc ghc ghc-pkg greencard haddock happy haskell-suite |
|
haskell-suite-pkg hmake hpc hsc2hs hscolour jhc ld lhc lhc-pkg pkg-config |
|
strip tar uhc |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
|
========================== |
|
repl |
|
========================== |
|
Open an interpreter session for the given component. |
|
|
|
Usage: cabal repl [COMPONENT] [FLAGS] |
|
|
|
If the current directory contains no package, ignores COMPONENT parameters and |
|
opens an interactive interpreter session; if a sandbox is present, its package |
|
database will be used. |
|
|
|
Otherwise, (re)configures with the given or default flags, and loads the |
|
interpreter with the relevant modules. For executables, tests and benchmarks, |
|
loads the main module (and its dependencies); for libraries all exposed/other |
|
modules. |
|
|
|
The default component is the library itself, or the executable if that is the |
|
only component. |
|
|
|
Support for loading specific modules is planned but not implemented yet. For |
|
certain scenarios, `cabal exec -- ghci :l Foo` may be used instead. Note that |
|
`exec` will not (re)configure and you will have to specify the location of |
|
other modules, if required. |
|
|
|
Flags for repl: |
|
-h --help Show this help text |
|
-v --verbose[=n] Control verbosity (n is 0--3, default verbosity level |
|
is 1) |
|
--builddir=DIR The directory where Cabal puts generated build files |
|
(default dist) |
|
--with-PROG=PATH give the path to PROG |
|
--PROG-option=OPT give an extra option to PROG (no need to quote options |
|
containing spaces) |
|
--PROG-options=OPTS give extra options to PROG |
|
--only Don't reinstall add-source dependencies (sandbox-only) |
|
|
|
Examples: |
|
cabal repl The first component in the package |
|
cabal repl foo A named component (i.e. lib, exe, test suite) |
|
cabal repl --ghc-options="-lstdc++" Specifying flags for interpreter |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
|
========================== |
|
sandbox |
|
========================== |
|
Create/modify/delete a sandbox. |
|
|
|
Usage: cabal sandbox init [FLAGS] |
|
or: cabal sandbox delete [FLAGS] |
|
or: cabal sandbox add-source [FLAGS] PATHS |
|
or: cabal sandbox delete-source [FLAGS] PATHS |
|
or: cabal sandbox list-sources [FLAGS] |
|
or: cabal sandbox hc-pkg [FLAGS] [--] COMMAND [--] [ARGS] |
|
|
|
Sandboxes are isolated package databases that can be used to prevent |
|
dependency conflicts that arise when many different packages are installed in |
|
the same database (i.e. the user's database in the home directory). |
|
|
|
A sandbox in the current directory (created by `sandbox init`) will be used |
|
instead of the user's database for commands such as `install` and `build`. |
|
Note that (a directly invoked) GHC will not automatically be aware of |
|
sandboxes; only if called via appropriate cabal commands, e.g. `repl`, |
|
`build`, `exec`. |
|
|
|
Currently, cabal will not search for a sandbox in folders above the current |
|
one, so cabal will not see the sandbox if you are in a subfolder of a |
|
sandboxes. |
|
|
|
Subcommands: |
|
|
|
init: |
|
Initialize a sandbox in the current directory. An existing package database |
|
will not be modified, but settings (such as the location of the database) |
|
can be modified this way. |
|
delete: |
|
Remove the sandbox; deleting all the packages installed inside. |
|
add-source: |
|
Make one or more local package available in the sandbox. PATHS may be |
|
relative or absolute. Typical usecase is when you need to make a (temporary) |
|
modification to a dependency: You download the package into a different |
|
directory, make the modification, and add that directory to the sandbox with |
|
`add-source`. |
|
Unless given `--snapshot`, any add-source'd dependency that was modified |
|
since the last build will be re-installed automatically. |
|
delete-source: |
|
Remove an add-source dependency; however, this will not delete the |
|
package(s) that have been installed in the sandbox from this dependency. You |
|
can either unregister the package(s) via `cabal sandbox hc-pkg unregister` |
|
or re-create the sandbox (`sandbox delete; sandbox init`). |
|
list-sources: |
|
List the directories of local packages made available via `cabal |
|
add-source`. |
|
hc-pkg: |
|
Similar to `ghc-pkg`, but for the sandbox package database. Can be used to |
|
list specific/all packages that are installed in the sandbox. For |
|
subcommands, see the help for ghc-pkg. Affected by the compiler version |
|
specified by `configure`. |
|
|
|
Flags for sandbox: |
|
-h --help Show this help text |
|
-v --verbose[=n] Control verbosity (n is 0--3, default verbosity level is 1) |
|
--snapshot Take a snapshot instead of creating a link (only applies to |
|
'add-source') |
|
--sandbox=DIR Sandbox location (default: './.cabal-sandbox'). |
|
|
|
Relevant global configuration keys: |
|
require-sandbox |
|
ignore-sandbox |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
|
========================== |
|
haddock |
|
========================== |
|
Generate Haddock HTML documentation. |
|
|
|
Usage: cabal haddock [FLAGS] |
|
|
|
Requires the program haddock, version 2.x. |
|
|
|
Flags for haddock: |
|
-h --help Show this help text |
|
-v --verbose[=n] Control verbosity (n is 0--3, default verbosity |
|
level is 1) |
|
--builddir=DIR The directory where Cabal puts generated build |
|
files (default dist) |
|
--keep-temp-files Keep temporary files |
|
--hoogle Generate a hoogle database |
|
--html Generate HTML documentation (the default) |
|
--html-location=URL Location of HTML documentation for pre-requisite |
|
packages |
|
--executables Run haddock for Executables targets |
|
--tests Run haddock for Test Suite targets |
|
--benchmarks Run haddock for Benchmark targets |
|
--all Run haddock for all targets |
|
--internal Run haddock for internal modules and include all |
|
symbols |
|
--css=PATH Use PATH as the haddock stylesheet |
|
--hyperlink-source Hyperlink the documentation to the source code |
|
(using HsColour) |
|
--hscolour-css=PATH Use PATH as the HsColour stylesheet |
|
--contents-location=URL Bake URL in as the location for the contents page |
|
--with-ghc=PATH give the path to ghc |
|
--with-haddock=PATH give the path to haddock |
|
--PROG-option=OPT give an extra option to PROG (no need to quote |
|
options containing spaces) |
|
--ghc-options=OPTS give extra options to ghc |
|
--haddock-options=OPTS give extra options to haddock |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
|
========================== |
|
exec |
|
========================== |
|
Give a command access to the sandbox package repository. |
|
|
|
Usage: cabal exec [FLAGS] [--] COMMAND [--] [ARGS] |
|
|
|
A directly invoked GHC will not automatically be aware of any sandboxes: the |
|
GHC_PACKAGE_PATH environment variable controls what GHC uses. `cabal exec` can |
|
be used to modify this variable: COMMAND will be executed in a modified |
|
environment and thereby uses the sandbox package database. |
|
|
|
If there is no sandbox, behaves as identity (executing COMMAND). |
|
|
|
Note that other cabal commands change the environment variable appropriately |
|
already, so there is no need to wrap those in `cabal exec`. But with `cabal |
|
exec`, the user has more control and can, for example, execute custom scripts |
|
which indirectly execute GHC. |
|
|
|
See `cabal sandbox`. |
|
|
|
Flags for exec: |
|
-h --help Show this help text |
|
-v --verbose[=n] Control verbosity (n is 0--3, default verbosity level is 1) |
|
|
|
Examples: |
|
Install the executable package pandoc into a sandbox and run it: |
|
cabal sandbox init |
|
cabal install pandoc |
|
cabal exec pandoc foo.md |
|
|
|
Install the executable package hlint into the user package database |
|
and run it: |
|
cabal install --user hlint |
|
cabal exec hlint Foo.hs |
|
|
|
Execute runghc on Foo.hs with runghc configured to use the |
|
sandbox package database (if a sandbox is being used): |
|
cabal exec runghc Foo.hs |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
|
========================== |
|
copy |
|
========================== |
|
Copy the files into the install locations. |
|
|
|
Usage: cabal copy [FLAGS] |
|
|
|
Does not call register, and allows a prefix at install time. Without the |
|
--destdir flag, configure determines location. |
|
|
|
Flags for copy: |
|
-h --help Show this help text |
|
-v --verbose[=n] Control verbosity (n is 0--3, default verbosity level is 1) |
|
--builddir=DIR The directory where Cabal puts generated build files |
|
(default dist) |
|
--destdir=DIR directory to copy files to, prepended to installation |
|
directories |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
|
========================== |
|
clean |
|
========================== |
|
Clean up after a build. |
|
|
|
Usage: cabal clean [FLAGS] |
|
|
|
Removes .hi, .o, preprocessed sources, etc. |
|
|
|
Flags for clean: |
|
-h --help Show this help text |
|
-v --verbose[=n] Control verbosity (n is 0--3, default verbosity level is |
|
1) |
|
--builddir=DIR The directory where Cabal puts generated build files |
|
(default dist) |
|
-s --save-configure Do not remove the configuration file (dist/setup-config) |
|
during cleaning. Saves need to reconfigure. |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
|
========================== |
|
hscolour |
|
========================== |
|
Generate HsColour colourised code, in HTML format. |
|
|
|
Usage: cabal hscolour [FLAGS] |
|
|
|
Requires the hscolour program. |
|
|
|
Flags for hscolour: |
|
-h --help Show this help text |
|
-v --verbose[=n] Control verbosity (n is 0--3, default verbosity level is 1) |
|
--builddir=DIR The directory where Cabal puts generated build files |
|
(default dist) |
|
--executables Run hscolour for Executables targets |
|
--tests Run hscolour for Test Suite targets |
|
--benchmarks Run hscolour for Benchmark targets |
|
--all Run hscolour for all targets |
|
--css=PATH Use a cascading style sheet |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
|
========================== |
|
register |
|
========================== |
|
Register this package with the compiler. |
|
|
|
Usage: cabal register [FLAGS] |
|
|
|
Flags for register: |
|
-h --help Show this help text |
|
-v --verbose[=n] Control verbosity (n is 0--3, default verbosity |
|
level is 1) |
|
--builddir=DIR The directory where Cabal puts generated build files |
|
(default dist) |
|
--user upon registration, register this package in the |
|
user's local package database |
|
--global (default)upon registration, register this package in |
|
the system-wide package database |
|
--inplace register the package in the build location, so it |
|
can be used without being installed |
|
--gen-script instead of registering, generate a script to |
|
register later |
|
--gen-pkg-config[=PKG] instead of registering, generate a package |
|
registration file |
|
--print-ipid print the installed package ID calculated for this |
|
package |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
|
========================== |
|
test |
|
========================== |
|
Run all/specific tests in the test suite. |
|
|
|
Usage: cabal test [FLAGS] |
|
or: cabal test TESTCOMPONENTS [FLAGS] |
|
|
|
If necessary (re)configures with `--enable-tests` flag and builds the test |
|
suite. |
|
|
|
Remember that the tests' dependencies must be installed if there are |
|
additional ones; e.g. with `cabal install --only-dependencies --enable-tests`. |
|
|
|
By defining UserHooks in a custom Setup.hs, the package can define actions to |
|
be executed before and after running tests. |
|
|
|
Flags for test: |
|
-h --help Show this help text |
|
-v --verbose[=n] Control verbosity (n is 0--3, default verbosity |
|
level is 1) |
|
--builddir=DIR The directory where Cabal puts generated build |
|
files (default dist) |
|
--log=TEMPLATE Log all test suite results to file (name template |
|
can use $pkgid, $compiler, $os, $arch, |
|
$test-suite, $result) |
|
--machine-log=TEMPLATE Produce a machine-readable log file (name template |
|
can use $pkgid, $compiler, $os, $arch, $result) |
|
--show-details=FILTER 'always': always show results of individual test |
|
cases. 'never': never show results of individual |
|
test cases. 'failures': show results of failing |
|
test cases. 'streaming': show results of test |
|
cases in real time. |
|
--keep-tix-files keep .tix files for HPC between test runs |
|
--test-options=TEMPLATES give extra options to test executables (name |
|
templates can use $pkgid, $compiler, $os, $arch, |
|
$test-suite) |
|
--test-option=TEMPLATE give extra option to test executables (no need to |
|
quote options containing spaces, name template can |
|
use $pkgid, $compiler, $os, $arch, $test-suite) |
|
-j --jobs[=NUM] Run NUM jobs simultaneously (or '$ncpus' if no NUM |
|
is given). |
|
--with-PROG=PATH give the path to PROG |
|
--PROG-option=OPT give an extra option to PROG (no need to quote |
|
options containing spaces) |
|
--PROG-options=OPTS give extra options to PROG |
|
--only Don't reinstall add-source dependencies |
|
(sandbox-only) |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
|
========================== |
|
bench |
|
========================== |
|
Run all/specific benchmarks. |
|
|
|
Usage: cabal bench [FLAGS] |
|
or: cabal bench BENCHCOMPONENTS [FLAGS] |
|
|
|
If necessary (re)configures with `--enable-benchmarks` flag and builds the |
|
benchmarks. |
|
|
|
Remember that the benchmarks' dependencies must be installed if there are |
|
additional ones; e.g. with `cabal install --only-dependencies |
|
--enable-benchmarks`. |
|
|
|
By defining UserHooks in a custom Setup.hs, the package can define actions to |
|
be executed before and after running benchmarks. |
|
|
|
Flags for bench: |
|
-h --help Show this help text |
|
-v --verbose[=n] Control verbosity (n is 0--3, default |
|
verbosity level is 1) |
|
--builddir=DIR The directory where Cabal puts generated |
|
build files (default dist) |
|
--benchmark-options=TEMPLATES give extra options to benchmark executables |
|
(name templates can use $pkgid, $compiler, |
|
$os, $arch, $benchmark) |
|
--benchmark-option=TEMPLATE give extra option to benchmark executables |
|
(no need to quote options containing spaces, |
|
name template can use $pkgid, $compiler, $os, |
|
$arch, $benchmark) |
|
-j --jobs[=NUM] Run NUM jobs simultaneously (or '$ncpus' if |
|
no NUM is given). |
|
--with-PROG=PATH give the path to PROG |
|
--PROG-option=OPT give an extra option to PROG (no need to |
|
quote options containing spaces) |
|
--PROG-options=OPTS give extra options to PROG |
|
--only Don't reinstall add-source dependencies |
|
(sandbox-only) |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
|
========================== |
|
help |
|
========================== |
|
Help about commands. |
|
|
|
Usage: cabal help [FLAGS] |
|
or: cabal help COMMAND [FLAGS] |
|
|
|
Flags for help: |
|
-h --help Show this help text |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
|
========================== |
|
user-config |
|
========================== |
|
Display and update the user's global cabal configuration. |
|
|
|
Usage: cabal user-config diff |
|
or: cabal user-config update |
|
|
|
When upgrading cabal, the set of configuration keys and their default values |
|
may change. This command provides means to merge the existing config in |
|
~/.cabal/config (i.e. all bindings that are actually defined and not commented |
|
out) and the default config of the new version. |
|
|
|
diff: Shows a pseudo-diff of the user's ~/.cabal/config file and the default |
|
configuration that would be created by cabal if the config file did not exist. |
|
update: Applies the pseudo-diff to the configuration that would be created by |
|
default, and write the result back to ~/.cabal/config. |
|
|
|
Flags for user-config: |
|
-h --help Show this help text |
|
-v --verbose[=n] Control verbosity (n is 0--3, default verbosity level is 1) |
|
|
|
You can edit the cabal configuration file to set defaults: |
|
/home/username/.cabal/config |
