Personal tools

Cabal-Install

From HaskellWiki

(Difference between revisions)
Jump to: navigation, search
(Installing a package: Added advice to use a sandbox)
(Commands: Updated global flags and commands)
 
Line 49: Line 49:
  
 
Global flags:
 
Global flags:
  -h --help                     Show the help text
+
  -h --help                         Show this help text
  -V --version                 Print version information
+
  -V --version                     Print version information
     --numeric-version         Print just the version number
+
     --numeric-version             Print just the version number
     --config-file=FILE         Set an alternate location for the config file
+
     --config-file=FILE             Set an alternate location for the config
     --sandbox-config-file=FILE Set an alternate location for the sandbox config
+
                                  file
                              file (default: './cabal.sandbox.config')
+
     --sandbox-config-file=FILE     Set an alternate location for the sandbox
     --require-sandbox         Enable requiring the presence of a sandbox for
+
                                  config file (default:
                              sandbox-aware commands
+
                                  './cabal.sandbox.config')
     --no-require-sandbox       Disable requiring the presence of a sandbox for
+
    --default-user-config=FILE    Set a location for a cabal.config file for
                              sandbox-aware commands
+
                                  projects without their own cabal.config
     --ignore-sandbox           Ignore any existing sandbox
+
                                  freeze file.
 +
     --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
 +
    --ignore-expiry                Ignore expiry dates on signed metadata (use
 +
                                  only in exceptional circumstances)
 +
    --http-transport=HttpTransport Set a transport for http(s) requests.
 +
                                  Accepts 'curl', 'wget', 'powershell', and
 +
                                  'plain-http'. (default: 'curl')
 +
    --enable-nix                  Enable Nix integration: run commands through
 +
                                  nix-shell if a 'shell.nix' file exists
 +
    --disable-nix                  Disable Nix integration: run commands
 +
                                  through nix-shell if a 'shell.nix' file
 +
                                  exists
  
 
Commands:
 
Commands:
  install      Installs a list of packages.
+
<pre>
   update       Updates list of known packages.
+
[global]
   list        List packages matching a search string.
+
   update           Updates list of known packages.
   info         Display detailed information about a particular package.
+
   install          Install packages.
   fetch       Downloads packages for later installation.
+
 
   freeze      Freeze dependencies.
+
  help            Help about commands.
   get         Gets a package's source code.
+
   info             Display detailed information about a particular package.
   check       Check the package for common mistakes.
+
  list            List packages matching a search string.
   sdist       Generate a source distribution file (.tar.gz).
+
   fetch           Downloads packages for later installation.
   upload       Uploads source packages to Hackage.
+
   user-config      Display and update the user's global cabal configuration.
   report       Upload build reports to a remote server.
+
 
   run          Runs the compiled executable.
+
[package]
   init         Interactively create a .cabal file.
+
   get             Download/Extract a package's source code (repository).
   configure    Prepare to build the package.
+
   init            Create a new .cabal package file (interactively).
   build        Compile all targets or specific targets.
+
 
   repl         Open an interpreter session for the given target.
+
  configure       Prepare to build the package.
   sandbox     Create/modify/delete a sandbox.
+
  build            Compile all/specific components.
  haddock      Generate Haddock HTML documentation.
+
  clean            Clean up after a build.
   exec         Run a command with the cabal environment
+
 
   copy        Copy the files into the install locations.
+
  run              Builds and runs an executable.
   clean        Clean up after a build.
+
  repl            Open an interpreter session for the given component.
   hscolour    Generate HsColour colourised code, in HTML format.
+
  test            Run all/specific tests in the test suite.
   register    Register this package with the compiler.
+
  bench            Run all/specific benchmarks.
   test        Run the test suite, if any (configure with UserHooks).
+
 
   bench        Run the benchmark, if any (configure with UserHooks).
+
  check            Check the package for common mistakes.
   help         Help about commands.
+
   sdist           Generate a source distribution file (.tar.gz).
 +
   upload           Uploads source packages or documentation to Hackage.
 +
   report           Upload build reports to a remote server.
 +
 
 +
   freeze          Freeze dependencies.
 +
   gen-bounds      Generate dependency bounds.
 +
  outdated         Check for outdated dependencies
 +
  doctest          Run doctest tests.
 +
  haddock          Generate Haddock HTML documentation.
 +
   hscolour        Generate HsColour colourised code, in HTML format.
 +
   copy            Copy the files of all/specific components to install locations.
 +
   register         Register this package with the compiler.
 +
   reconfigure     Reconfigure the package if necessary.
 +
 
 +
[sandbox]
 +
  sandbox          Create/modify/delete a sandbox.
 +
   exec             Give a command access to the sandbox package repository.
 +
   repl            Open interpreter with access to sandbox packages.
 +
 
 +
[new-style projects (beta)]
 +
   new-build       Compile targets within the project.
 +
   new-configure    Add extra project configuration
 +
   new-repl        Open an interactive session for the given component.
 +
   new-run          Run an executable.
 +
  new-test        Run test-suites
 +
   new-bench        Run benchmarks
 +
  new-freeze      Freeze dependencies.
 +
   new-haddock      Build Haddock documentation
 +
 
 +
[other]
 +
  new-update      Updates list of known packages.
 +
  new-install      Install packages.
 +
  new-exec         Give a command access to the store.
 +
</pre>
  
 
For more information about a command use:
 
For more information about a command use:
Line 98: Line 146:
 
Occasionally you need to update the list of available packages:
 
Occasionally you need to update the list of available packages:
 
   cabal update
 
   cabal update
 
  
 
=== The cabal-install configuration file ===
 
=== The cabal-install configuration file ===

Latest revision as of 14:26, 19 March 2018

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.


Contents

[edit] 1 Usage

[edit] 1.1 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.

It is advisable to use a sandbox, to prevent version incompatibility with earlier installed packages. To initiate a sandbox, give command:

 cabal sandbox init

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

[edit] 1.2 Commands

Usage:

  cabal COMMAND [FLAGS]

or:

  cabal [GLOBAL FLAGS]

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')
   --default-user-config=FILE     Set a location for a cabal.config file for
                                  projects without their own cabal.config
                                  freeze file.
   --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
   --ignore-expiry                Ignore expiry dates on signed metadata (use
                                  only in exceptional circumstances)
   --http-transport=HttpTransport Set a transport for http(s) requests.
                                  Accepts 'curl', 'wget', 'powershell', and
                                  'plain-http'. (default: 'curl')
   --enable-nix                   Enable Nix integration: run commands through
                                  nix-shell if a 'shell.nix' file exists
   --disable-nix                  Disable Nix integration: run commands
                                  through nix-shell if a 'shell.nix' file
                                  exists

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 or documentation to Hackage.
  report           Upload build reports to a remote server.

  freeze           Freeze dependencies.
  gen-bounds       Generate dependency bounds.
  outdated         Check for outdated dependencies
  doctest          Run doctest tests.
  haddock          Generate Haddock HTML documentation.
  hscolour         Generate HsColour colourised code, in HTML format.
  copy             Copy the files of all/specific components to install locations.
  register         Register this package with the compiler.
  reconfigure      Reconfigure the package if necessary.

 [sandbox]
  sandbox          Create/modify/delete a sandbox.
  exec             Give a command access to the sandbox package repository.
  repl             Open interpreter with access to sandbox packages.

 [new-style projects (beta)]
  new-build        Compile targets within the project.
  new-configure    Add extra project configuration
  new-repl         Open an interactive session for the given component.
  new-run          Run an executable.
  new-test         Run test-suites
  new-bench        Run benchmarks
  new-freeze       Freeze dependencies.
  new-haddock      Build Haddock documentation

 [other]
  new-update       Updates list of known packages.
  new-install      Install packages.
  new-exec         Give a command access to the store.

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

[edit] 1.3 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


[edit] 1.3.1 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

[edit] 2 Installation

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

Button-100.png


[edit] 2.1 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.


[edit] 2.2 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.


[edit] 3 Error reporting

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


[edit] 4 FAQ

[edit] 4.1 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.

[edit] 4.2 How can I uninstall packages?

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

 ghc-pkg unregister


[edit] 5 See also