Cabal/doc/index.markdown

   1 % Cabal User Guide
   2
   3 Cabal is the standard package system for [Haskell] software. It helps
   4 people to configure, build and install Haskell software and to
   5 distribute it easily to other users and developers.
   6
   7 There is a command line tool called `cabal` for working with Cabal
   8 packages. It helps with installing existing packages and also helps
   9 people developing their own packages. It can be used to work with local
  10 packages or to install packages from online package archives, including
  11 automatically installing dependencies. By default it is configured to
  12 use [Hackage] which is Haskell's central package archive that contains
  13 thousands of libraries and applications in the Cabal package format.
  14
  15 # Contents #
  16
  17   * [Introduction](#introduction)
  18       - [What's in a package](#whats-in-a-package)
  19       - [A tool for working with packages](#a-tool-for-working-with-packages)
  20   * [Building, installing and managing packages](installing-packages.html)
  21   * [Creating packages](developing-packages.html)
  22   * [Reporting bugs and deficiencies](misc.html#reporting-bugs-and-deficiencies)
  23   * [Stability of Cabal interfaces](misc.html#stability-of-cabal-interfaces)
  24
  25 # Introduction #
  26
  27 Cabal is a package system for Haskell software. The point of a package
  28 system is to enable software developers and users to easily distribute,
  29 use and reuse software. A package system makes it easier for developers
  30 to get their software into the hands of users. Equally importantly, it
  31 makes it easier for software developers to be able to reuse software
  32 components written by other developers.
  33
  34 Packaging systems deal with packages and with Cabal we call them _Cabal
  35 packages_. The Cabal package is the unit of distribution. Every Cabal
  36 package has a name and a version number which are used to identify the
  37 package, e.g. `filepath-1.0`.
  38
  39 Cabal packages can depend on other Cabal packages. There are tools
  40 to enable automated package management. This means it is possible for
  41 developers and users to install a package plus all of the other Cabal
  42 packages that it depends on. It also means that it is practical to make
  43 very modular systems using lots of packages that reuse code written by
  44 many developers.
  45
  46 Cabal packages are source based and are typically (but not necessarily)
  47 portable to many platforms and Haskell implementations. The Cabal
  48 package format is designed to make it possible to translate into other
  49 formats, including binary packages for various systems.
  50
  51 When distributed, Cabal packages use the standard compressed tarball
  52 format, with the file extension `.tar.gz`, e.g. `filepath-1.0.tar.gz`.
  53
  54 Note that packages are not part of the Haskell language, rather they
  55 are a feature provided by the combination of Cabal and GHC (and several
  56 other Haskell implementations).
  57
  58
  59 ## A tool for working with packages ##
  60
  61 There is a command line tool, called "`cabal`", that users and developers
  62 can use to build and install Cabal packages. It can be used for both
  63 local packages and for packages available remotely over the network. It
  64 can automatically install Cabal packages plus any other Cabal packages
  65 they depend on.
  66
  67 Developers can use the tool with packages in local directories, e.g.
  68
  69 ~~~~~~~~~~~~~~~~
  70 cd foo/
  71 cabal install
  72 ~~~~~~~~~~~~~~~~
  73
  74 While working on a package in a local directory, developers can run the
  75 individual steps to configure and build, and also generate documentation
  76 and run test suites and benchmarks.
  77
  78 It is also possible to install several local packages at once, e.g.
  79
  80 ~~~~~~~~~~~~~~~~
  81 cabal install foo/ bar/
  82 ~~~~~~~~~~~~~~~~
  83
  84 Developers and users can use the tool to install packages from remote
  85 Cabal package archives. By default, the `cabal` tool is configured to
  86 use the central Haskell package archive called [Hackage] but it
  87 is possible to use it with any other suitable archive.
  88
  89 ~~~~~~~~~~~~~~~~
  90 cabal install xmonad
  91 ~~~~~~~~~~~~~~~~
  92
  93 This will install the `xmonad` package plus all of its dependencies.
  94
  95 In addition to packages that have been published in an archive,
  96 developers can install packages from local or remote tarball files,
  97 for example
  98
  99 ~~~~~~~~~~~~~~~~
 100 cabal install foo-1.0.tar.gz
 101 cabal install http://example.com/foo-1.0.tar.gz
 102 ~~~~~~~~~~~~~~~~
 103
 104 Cabal provides a number of ways for a user to customise how and where a
 105 package is installed. They can decide where a package will be installed,
 106 which Haskell implementation to use and whether to build optimised code
 107 or build with the ability to profile code. It is not expected that users
 108 will have to modify any of the information in the `.cabal` file.
 109
 110 For full details, see the section on [building and installing
 111 packages](installing-packages.html).
 112
 113 Note that `cabal` is not the only tool for working with Cabal packages.
 114 Due to the standardised format and a library for reading `.cabal` files,
 115 there are several other special-purpose tools.
 116
 117 ## What's in a package ##
 118
 119 A Cabal package consists of:
 120
 121   * Haskell software, including libraries, executables and tests
 122   * metadata about the package in a standard human and machine
 123     readable format (the "`.cabal`" file)
 124   * a standard interface to build the package (the "`Setup.hs`" file)
 125
 126 The `.cabal` file contains information about the package, supplied by
 127 the package author. In particular it lists the other Cabal packages
 128 that the package depends on.
 129
 130 For full details on what goes in the `.cabal` and `Setup.hs` files, and
 131 for all the other features provided by the build system, see the section
 132 on [developing packages](developing-packages.html).
 133
 134
 135 ## Cabal featureset ##
 136
 137 Cabal and its associated tools and websites covers:
 138
 139  * a software build system
 140  * software configuration
 141  * packaging for distribution
 142  * automated package management
 143     * natively using the `cabal` command line tool; or
 144     * by translation into native package formats such as RPM or deb
 145  * web and local Cabal package archives
 146     * central Hackage website with 1000's of Cabal packages
 147
 148 Some parts of the system can be used without others. In particular the
 149 built-in build system for simple packages is optional: it is possible
 150 to use custom build systems.
 151
 152 ## Similar systems ##
 153
 154 The Cabal system is roughly comparable with the system of Python Eggs,
 155 Ruby Gems or Perl distributions. Each system has a notion of
 156 distributable packages, and has tools to manage the process of
 157 distributing and installing packages.
 158
 159 Hackage is an online archive of Cabal packages. It is roughly comparable
 160 to CPAN but with rather fewer packages (around 5,000 vs 28,000).
 161
 162 Cabal is often compared with autoconf and automake and there is some
 163 overlap in functionality. The most obvious similarity is that the
 164 command line interface for actually configuring and building packages
 165 follows the same steps and has many of the same configuration
 166 paramaters.
 167
 168 ~~~~~~~~~~
 169 ./configure --prefix=...
 170 make
 171 make install
 172 ~~~~~~~~~~
 173
 174 compared to
 175
 176 ~~~~~~~~~~
 177 cabal configure --prefix=...
 178 cabal build
 179 cabal install
 180 ~~~~~~~~~~
 181
 182 Cabal's build system for simple packages is considerably less flexible
 183 than make/automake, but has builtin knowledge of how to build Haskell
 184 code and requires very little manual configuration. Cabal's simple build
 185 system is also portable to Windows, without needing a unix-like
 186 environment such as cygwin/mingwin.
 187
 188 Compared to autoconf, Cabal takes a somewhat different approach to
 189 package configuration. Cabal's approach is designed for automated
 190 package management. Instead of having a configure script that tests for
 191 whether dependencies are available, Cabal packages specify their
 192 dependencies. There is some scope for optional and conditional
 193 dependencies. By having package authors specify dependencies it makes it
 194 possible for tools to install a package and all of its dependencies
 195 automatically. It also makes it possible to translate (in a
 196 mostly-automatically way) into another package format like RPM or deb
 197 which also have automatic dependency resolution.
 198
 199 [Haskell]:  http://www.haskell.org/
 200 [Hackage]:  http://hackage.haskell.org/