Difference between revisions of "Cabal-Install"

From HaskellWiki
Jump to navigation Jump to search
(unofficial cabal-install binary for Intel Linux)
(→‎The cabal-install configuration file: Simplified the part about the config file on a Windows system)
(25 intermediate revisions by 10 users not shown)
Line 1: Line 1:
  +
{{Stub}}
−
The <code>cabal-install</code> package provides the <code>cabal</code> command-line tool which simplifies the process of managing Haskell software
  
  +
  +
The cabal-install package provides the <code>cabal</code> command-line tool which simplifies the process of managing Haskell software
 
by automating the fetching, configuration, compilation and installation of Haskell libraries and programs.
  
by automating the fetching, configuration, compilation and installation of Haskell libraries and programs.
−
Those packages must be prepared using [[Cabal]] and should be present at [http://hackage.haskell.org/ Hackage].
 +
Those packages must be prepared using [[Cabal]] and should be present at [http://hackage.haskell.org/packages/archive/pkg-list.html Hackage].
  +
   
 
== Usage ==
  
== Usage ==
   
  +
=== Installing a package ===
−
Once you have the tool installed then installing other packages easy. To install Cabal packages from Hackage use:
  
  +
  +
Once you have the tool installed, installing other packages is easy.
  +
The first thing to do is to give the command:
  +
cabal update
  +
This will download the most recent list of packages; this must be done from time to time, to get the latest version of each package, when installing.
  +
  +
To install Cabal packages from [http://hackage.haskell.org/packages/archive/pkg-list.html Hackage] use:
 
cabal install foo
  
cabal install foo
   
 
Other common variations:
  
Other common variations:
−
cabal install Package in the current directory
 +
cabal install Package in the current directory
−
cabal install foo Package from the hackage server
 +
cabal install foo Package from the Hackage server
−
cabal install foo-1.0 Specific version of a package
 +
cabal install foo-1.0 Specific version of a package
−
cabal install 'foo < 2' Constrained package version
 +
cabal install 'foo < 2' Constrained package version
−
cabal install foo bar baz Several packages at once
 +
cabal install foo bar baz Several packages at once
−
cabal install foo --dry-run Show what would be installed
 +
cabal install foo --dry-run Show what would be installed
  +
cabal install foo --constraint=bar==1.0 Use version 1.0 of package bar
  +
  +
One thing to be especially aware of, is that the packages are installed locally by default, whereas the commands
  +
runhaskell Setup configure
  +
runhaskell Setup build
  +
runhaskell Setup install
  +
install globally by default.
  +
If you install a package globally, the local packages are ignored. The default for cabal-install can be modified by editing the configuration file.
  +
  +
Help about cabal-install can be obtained by giving commands like:
  +
cabal --help
  +
cabal install --help
  +
  +
  +
=== Commands ===
  +
  +
Usage:
  +
cabal COMMAND [FLAGS]
  +
or:
  +
cabal [GLOBAL FLAGS]
  +
  +
Global flags:
  +
-h --help Show the 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
  +
  +
Commands:
  +
install Installs a list of packages.
  +
update Updates list of known packages.
  +
list List packages matching a search string.
  +
info Display detailed information about a particular package.
  +
fetch Downloads packages for later installation.
  +
freeze Freeze dependencies.
  +
get Gets a package's source code.
  +
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.
  +
run Runs the compiled executable.
  +
init Interactively create a .cabal file.
  +
configure Prepare to build the package.
  +
build Compile all targets or specific targets.
  +
repl Open an interpreter session for the given target.
  +
sandbox Create/modify/delete a sandbox.
  +
haddock Generate Haddock HTML documentation.
  +
exec Run a command with the cabal environment
  +
copy Copy the files into the install locations.
  +
clean Clean up after a build.
  +
hscolour Generate HsColour colourised code, in HTML format.
  +
register Register this package with the compiler.
  +
test Run the test suite, if any (configure with UserHooks).
  +
bench Run the benchmark, if any (configure with UserHooks).
  +
help Help about commands.
  +
  +
For more information about a command use:
  +
cabal COMMAND --help
  +
  +
To install Cabal packages from Hackage, use:
  +
cabal install foo [--dry-run]
  +
If <code>--dry-run</code> is specified, the packages are not installed, but a list of packages to install is given.
   
 
Occasionally you need to update the list of available packages:
  
Occasionally you need to update the list of available packages:
 
cabal update
  
cabal update
   
  +
−
You can edit the cabal configuration file to set defaults:
  
  +
=== The cabal-install configuration file ===
  +
  +
You can edit the cabal configuration file to set defaults, for *nix based systems this is:
 
~/.cabal/config
  
~/.cabal/config
   
  +
The config file on a Windows system is
−
Or on Windows the config file lives at:
  
−
C:\Documents and Settings\username\Application Data\cabal\config
 +
%appdata%\cabal\config
  +
  +
  +
==== Things to put in the config file ====
  +
  +
To turn on --global by default:
  +
user-install: False
  +
  +
The root-cmd configuration parameter can be used to automatically run cabal-install with root privileges on *nix based systems, when needed:
  +
root-cmd: sudo
   
 
== Installation ==
  
== Installation ==
  +
  +
If you have the [http://hackage.haskell.org/platform/ Haskell Platform] installed, you already have cabal-install; no further action is needed.
  +
  +
[[File:Button-100.png|link=http://hackage.haskell.org/platform/]]
  +
   
 
=== Windows ===
  
=== Windows ===
Line 33: Line 128:
   
 
You must put the <code>cabal.exe</code> in a directory that is on your <code>%PATH%</code>, for example <code>C:\Program Files\Haskell\bin</code>.
  
You must put the <code>cabal.exe</code> in a directory that is on your <code>%PATH%</code>, for example <code>C:\Program Files\Haskell\bin</code>.
  +
   
 
=== Unix ===
  
=== Unix ===
Line 43: Line 139:
 
Note this assumes you have the zlib C library and its header files installed. Those header files are usually in a native system package like <code>zlib-devel</code> (On debian-based systems it is <code>zlib1g-dev</code>). You should also have the Haskell packages <code>parsec</code> and <code>network</code> installed. If you installed GHC via your native system package manager then you may also need to use it to install these two packages. (On debian-based systems they are called <code>libghc6-parsec-dev</code> and <code>libghc6-network-dev</code>.)
  
Note this assumes you have the zlib C library and its header files installed. Those header files are usually in a native system package like <code>zlib-devel</code> (On debian-based systems it is <code>zlib1g-dev</code>). You should also have the Haskell packages <code>parsec</code> and <code>network</code> installed. If you installed GHC via your native system package manager then you may also need to use it to install these two packages. (On debian-based systems they are called <code>libghc6-parsec-dev</code> and <code>libghc6-network-dev</code>.)
   
−
tar -zxf cabal-install-0.6.2.tar.gz
+
tar -zxf cabal-install-0.14.0.tar.gz
−
cd cabal-install-0.6.2
 +
cd cabal-install-0.14.0
 
./bootstrap.sh
  
./bootstrap.sh
   
 
If this completes successfully you will have the cabal binary in <code>~/.cabal/bin</code>. You should either add this directory to your <code>$PATH</code> or copy the cabal program to some location that is on your <code>$PATH</code>, eg <code>~/bin</code>.
  
If this completes successfully you will have the cabal binary in <code>~/.cabal/bin</code>. You should either add this directory to your <code>$PATH</code> or copy the cabal program to some location that is on your <code>$PATH</code>, eg <code>~/bin</code>.
   
−
to get the current list of package from hackage you should now run:
 +
to get the current list of package from Hackage you should now run:
   
 
cabal update
  
cabal update
Line 55: Line 151:
 
By default the cabal tool will install programs in <code>~/.cabal/bin</code>. If you decided not to put this directory on your <code>$PATH</code> then you can get cabal to symlink binaries into another directory, eg <code>~/bin</code>. To use this feature edit <code>~/.cabal/config</code> and see the <code>symlink-bindir field</code>. Note that the <code>~/.cabal/config</code> file is not created until you run a cabal command for the first time, eg <code>cabal update</code>.
  
By default the cabal tool will install programs in <code>~/.cabal/bin</code>. If you decided not to put this directory on your <code>$PATH</code> then you can get cabal to symlink binaries into another directory, eg <code>~/bin</code>. To use this feature edit <code>~/.cabal/config</code> and see the <code>symlink-bindir field</code>. Note that the <code>~/.cabal/config</code> file is not created until you run a cabal command for the first time, eg <code>cabal update</code>.
   
−
=== Linux on Intel ===
  
   
  +
== Error reporting ==
−
There is also an unofficial binary for Intel-Linux of [http://code.haskell.org/~thielema/cabal version 0.6.0].
  
  +
  +
Errors in cabal-install can be reported at
  +
[https://github.com/haskell/cabal/issues the GitHub Cabal issues page]
  +
  +
  +
== FAQ ==
  +
  +
=== I just installed packages, but now the packages are not found ===
  +
This happens when you install a package globally, and the previous packages were installed locally. Note that cabal-install install locally by default and the "runhaskell Setup" commands install globally by default.
  +
  +
=== How can I uninstall packages? ===
  +
There is no "cabal uninstall" command. You can only unregister packages with [[ghc-pkg]]:
  +
ghc-pkg unregister
  +
   
 
== See also ==
  
== See also ==
   
−
* [http://hackage.haskell.org/trac/hackage/wiki/CabalInstall cabal-install] page on the Cabal/Hackage development site.
 +
* The [https://github.com/haskell/cabal Cabal] page on GitHub.
  +
* [http://coldwa.st/e/blog/2013-08-20-Cabal-sandbox.html An Introduction to Cabal sandboxes]
  +
* [http://www.vex.net/~trebla/haskell/cabal-cabal.xhtml The Cabal of Cabal], the undocumented or obscure artifices and intrigues of Cabal.
  +
* [http://www.vex.net/~trebla/haskell/sicp.xhtml Storage and Identification of Cabalized Packages]
  +
* [[Hack-Nix]] alternative based on the [http://nixos.org Nix] package manager.
  +
* [[Capri]] a wrapper over cabal-install and [[ghc-pkg]] to operate in project-private mode; similar to [[Hack-Nix]] but does not involve any extra software..
   
 
[[Category:Tools]]
  
[[Category:Tools]]
  +
[[Category:Cabal]]

Revision as of 12:26, 22 September 2014

This article is a stub. You can help by expanding it.

The cabal-install package provides the cabal command-line tool which simplifies the process of managing Haskell software by automating the fetching, configuration, compilation and installation of Haskell libraries and programs. Those packages must be prepared using Cabal and should be present at Hackage.


Usage

Installing a package

Once you have the tool installed, installing other packages is easy. The first thing to do is to give the command: 

 cabal update

This will download the most recent list of packages; this must be done from time to time, to get the latest version of each package, when installing.

To install Cabal packages from Hackage use: 

 cabal install foo

Other common variations: 

 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
 cabal install foo bar baz                 Several packages at once
 cabal install foo --dry-run               Show what would be installed
 cabal install foo --constraint=bar==1.0   Use version 1.0 of package bar

One thing to be especially aware of, is that the packages are installed locally by default, whereas the commands 

 runhaskell Setup configure
 runhaskell Setup build
 runhaskell Setup install

install globally by default. If you install a package globally, the local packages are ignored. The default for cabal-install can be modified by editing the configuration file.

Help about cabal-install can be obtained by giving commands like: 

 cabal --help
 cabal install --help


Commands

Usage: 

  cabal COMMAND [FLAGS]

or: 

  cabal [GLOBAL FLAGS]

Global flags: 

-h --help                     Show the 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

Commands: 

 install      Installs a list of packages.
 update       Updates list of known packages.
 list         List packages matching a search string.
 info         Display detailed information about a particular package.
 fetch        Downloads packages for later installation.
 freeze       Freeze dependencies.
 get          Gets a package's source code.
 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.
 run          Runs the compiled executable.
 init         Interactively create a .cabal file.
 configure    Prepare to build the package.
 build        Compile all targets or specific targets.
 repl         Open an interpreter session for the given target.
 sandbox      Create/modify/delete a sandbox.
 haddock      Generate Haddock HTML documentation.
 exec         Run a command with the cabal environment
 copy         Copy the files into the install locations.
 clean        Clean up after a build.
 hscolour     Generate HsColour colourised code, in HTML format.
 register     Register this package with the compiler.
 test         Run the test suite, if any (configure with UserHooks).
 bench        Run the benchmark, if any (configure with UserHooks).
 help         Help about commands.

For more information about a command use: 

 cabal COMMAND --help

To install Cabal packages from Hackage, use: 

 cabal install foo [--dry-run]

If --dry-run is specified, the packages are not installed, but a list of packages to install is given.

Occasionally you need to update the list of available packages: 

 cabal update


The cabal-install configuration file

You can edit the cabal configuration file to set defaults, for *nix based systems this is: 

 ~/.cabal/config

The config file on a Windows system is 

 %appdata%\cabal\config


Things to put in the config file

To turn on --global by default: 

 user-install: False

The root-cmd configuration parameter can be used to automatically run cabal-install with root privileges on *nix based systems, when needed: 

 root-cmd: sudo

Installation

If you have the Haskell Platform installed, you already have cabal-install; no further action is needed.

Button-100.png


Windows

Get a pre-built cabal.exe from: 

 http://www.haskell.org/cabal/download.html

You must put the cabal.exe in a directory that is on your %PATH%, for example C:\Program Files\Haskell\bin.


Unix

Download the latest cabal-install tarball from: 

 http://www.haskell.org/cabal/download.html

It includes a shell script bootstrap.sh that you can run to download and install the other dependencies.

Note this assumes you have the zlib C library and its header files installed. Those header files are usually in a native system package like zlib-devel (On debian-based systems it is zlib1g-dev). You should also have the Haskell packages parsec and network installed. If you installed GHC via your native system package manager then you may also need to use it to install these two packages. (On debian-based systems they are called libghc6-parsec-dev and libghc6-network-dev.) 

 tar -zxf cabal-install-0.14.0.tar.gz 
 cd cabal-install-0.14.0
 ./bootstrap.sh

If this completes successfully you will have the cabal binary in ~/.cabal/bin. You should either add this directory to your $PATH or copy the cabal program to some location that is on your $PATH, eg ~/bin.

to get the current list of package from Hackage you should now run: 

 cabal update

By default the cabal tool will install programs in ~/.cabal/bin. If you decided not to put this directory on your $PATH then you can get cabal to symlink binaries into another directory, eg ~/bin. To use this feature edit ~/.cabal/config and see the symlink-bindir field. Note that the ~/.cabal/config file is not created until you run a cabal command for the first time, eg cabal update.


Error reporting

Errors in cabal-install can be reported at the GitHub Cabal issues page


FAQ

I just installed packages, but now the packages are not found

This happens when you install a package globally, and the previous packages were installed locally. Note that cabal-install install locally by default and the "runhaskell Setup" commands install globally by default.

How can I uninstall packages?

There is no "cabal uninstall" command. You can only unregister packages with ghc-pkg: 

 ghc-pkg unregister


See also

Retrieved from "https://wiki.haskell.org/index.php?title=Cabal-Install&oldid=58852"