doc/intro.rst

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