Difference between revisions of "Cabal-Install"
Jump to navigation
Jump to search
Tomjaguarpaw (talk | contribs) m (Highlight warning notice in red) |
(Remove outdated stuff) |
||
| Line 1: | Line 1: | ||
{{Stub}} |
{{Stub}} |
||
| − | The cabal-install 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. |
| + | Those packages must be prepared using [[Cabal]] and should be present at [http://hackage.haskell.org/ Hackage]. |
||
| − | 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/packages/archive/pkg-list.html Hackage]. |
||
| + | See https://cabal.readthedocs.io/ for more info. |
||
| − | <div style="color: red">{{box|'''As of 2020-03-15 this page is out of date. Cabal-install 3.0 switched to the v2-* class of commands, while this guide still refers to the v1-ones. See https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html for more info.'''}}</div> |
||
| − | |||
| − | == 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. |
||
| − | |||
| − | 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 [http://hackage.haskell.org/packages/archive/pkg-list.html 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 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: |
||
| − | <pre> |
||
| − | [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. |
||
| − | </pre> |
||
| − | |||
| − | 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: |
||
| − | 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 [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 === |
||
| − | |||
| − | Get a pre-built <code>cabal.exe</code> from: |
||
| − | http://www.haskell.org/cabal/download.html |
||
| − | |||
| − | 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 === |
||
| − | |||
| − | Download the latest cabal-install tarball from: |
||
| − | http://www.haskell.org/cabal/download.html |
||
| − | |||
| − | It includes a shell script <code>bootstrap.sh</code> 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 <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.14.0.tar.gz |
||
| − | cd cabal-install-0.14.0 |
||
| − | ./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>. |
||
| − | |||
| − | to get the current list of package from Hackage you should now run: |
||
| − | |||
| − | cabal update |
||
| − | |||
| − | 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>. |
||
| − | |||
| − | |||
| − | == Error reporting == |
||
| − | |||
| − | 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 == |
||
| − | |||
| − | * 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]] |
||
Latest revision as of 10:10, 10 March 2021
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.
See https://cabal.readthedocs.io/ for more info.