doc/package-concepts.rst

   1 Package concepts
   2 ================
   3
   4 Before diving into the details of writing packages it helps to
   5 understand a bit about packages in the Haskell world and the particular
   6 approach that Cabal takes.
   7
   8 The point of packages
   9 ---------------------
  10
  11 Packages are a mechanism for organising and distributing code. Packages
  12 are particularly suited for "programming in the large", that is building
  13 big systems by using and re-using code written by different people at
  14 different times.
  15
  16 People organise code into packages based on functionality and
  17 dependencies. Social factors are also important: most packages have a
  18 single author, or a relatively small team of authors.
  19
  20 Packages are also used for distribution: the idea is that a package can
  21 be created in one place and be moved to a different computer and be
  22 usable in that different environment. There are a surprising number of
  23 details that have to be got right for this to work, and a good package
  24 system helps to simplify this process and make it reliable.
  25
  26 Packages come in two main flavours: libraries of reusable code, and
  27 complete programs. Libraries present a code interface, an API, while
  28 programs can be run directly. In the Haskell world, library packages
  29 expose a set of Haskell modules as their public interface. Cabal
  30 packages can contain a library or executables or both.
  31
  32 Some programming languages have packages as a builtin language concept.
  33 For example in Java, a package provides a local namespace for types and
  34 other definitions. In the Haskell world, packages are not a part of the
  35 language itself. Haskell programs consist of a number of modules, and
  36 packages just provide a way to partition the modules into sets of
  37 related functionality. Thus the choice of module names in Haskell is
  38 still important, even when using packages.
  39
  40 Package names and versions
  41 --------------------------
  42
  43 All packages have a name, e.g. "HUnit". Package names are assumed to be
  44 unique. Cabal package names may contain letters, numbers and hyphens,
  45 but not spaces and may also not contain a hyphened section consisting of
  46 only numbers. The namespace for Cabal packages is flat, not
  47 hierarchical.
  48
  49 Packages also have a version, e.g "1.1". This matches the typical way in
  50 which packages are developed. Strictly speaking, each version of a
  51 package is independent, but usually they are very similar. Cabal package
  52 versions follow the conventional numeric style, consisting of a sequence
  53 of digits such as "1.0.1" or "2.0". There are a range of common
  54 conventions for "versioning" packages, that is giving some meaning to
  55 the version number in terms of changes in the package, such as
  56 e.g. `SemVer <http://semver.org>`__; however, for packages intended to be
  57 distributed via Hackage Haskell's `Package Versioning Policy <https://pvp.haskell.org/>`_ applies
  58 (see also the `PVP/SemVer FAQ section <https://pvp.haskell.org/faq/#semver>`__).
  59
  60 The combination of package name and version is called the *package ID*
  61 and is written with a hyphen to separate the name and version, e.g.
  62 "HUnit-1.1".
  63
  64 For Cabal packages, the combination of the package name and version
  65 *uniquely* identifies each package. Or to put it another way: two
  66 packages with the same name and version are considered to *be* the same.
  67
  68 Strictly speaking, the package ID only identifies each Cabal *source*
  69 package; the same Cabal source package can be configured and built in
  70 different ways. There is a separate installed package ID that uniquely
  71 identifies each installed package instance. Most of the time however,
  72 users need not be aware of this detail.
  73
  74 Kinds of package: Cabal vs GHC vs system
  75 ----------------------------------------
  76
  77 It can be slightly confusing at first because there are various
  78 different notions of package floating around. Fortunately the details
  79 are not very complicated.
  80
  81 Cabal packages
  82     Cabal packages are really source packages. That is they contain
  83     Haskell (and sometimes C) source code.
  84
  85     Cabal packages can be compiled to produce GHC packages. They can
  86     also be translated into operating system packages.
  87
  88 GHC packages
  89     This is GHC's view on packages. GHC only cares about library
  90     packages, not executables. Library packages have to be registered
  91     with GHC for them to be available in GHCi or to be used when
  92     compiling other programs or packages.
  93
  94     The low-level tool ``ghc-pkg`` is used to register GHC packages and
  95     to get information on what packages are currently registered.
  96
  97     You never need to make GHC packages manually. When you build and
  98     install a Cabal package containing a library then it gets registered
  99     with GHC automatically.
 100
 101     Haskell implementations other than GHC have essentially the same
 102     concept of registered packages. For the most part, Cabal hides the
 103     slight differences.
 104
 105 Operating system packages
 106     On operating systems like Linux and Mac OS X, the system has a
 107     specific notion of a package and there are tools for installing and
 108     managing packages.
 109
 110     The Cabal package format is designed to allow Cabal packages to be
 111     translated, mostly-automatically, into operating system packages.
 112     They are usually translated 1:1, that is a single Cabal package
 113     becomes a single system package.
 114
 115     It is also possible to make Windows installers from Cabal packages,
 116     though this is typically done for a program together with all of its
 117     library dependencies, rather than packaging each library separately.
 118
 119 Unit of distribution
 120 --------------------
 121
 122 The Cabal package is the unit of distribution. This means that
 123 each Cabal package can be distributed on its own, in source or binary
 124 form. There may be dependencies between packages, but there is
 125 usually a degree of flexibility in which versions of packages can work
 126 together so distributing them independently makes sense.
 127
 128 It is perhaps easiest to see what being "the unit of distribution"
 129 means by contrast to an alternative approach. Many projects are made up
 130 of several interdependent packages and during development these might
 131 all be kept under one common directory tree and be built and tested
 132 together. When it comes to distribution however, rather than
 133 distributing them all together in a single tarball, it is required that
 134 they each be distributed independently in their own tarballs.
 135
 136 Cabal's approach is to say that if you can specify a dependency on a
 137 package then that package should be able to be distributed
 138 independently. Or to put it the other way round, if you want to
 139 distribute it as a single unit, then it should be a single package.
 140
 141 Explicit dependencies and automatic package management
 142 ------------------------------------------------------
 143
 144 Cabal takes the approach that all packages dependencies are specified
 145 explicitly and specified in a declarative way. The point is to enable
 146 automatic package management. This means tools like ``cabal`` can
 147 resolve dependencies and install a package plus all of its dependencies
 148 automatically. Alternatively, it is possible to mechanically (or mostly
 149 mechanically) translate Cabal packages into system packages and let the
 150 system package manager install dependencies automatically.
 151
 152 It is important to track dependencies accurately so that packages can
 153 reliably be moved from one system to another system and still be able to
 154 build it there. Cabal is therefore relatively strict about specifying
 155 dependencies. For example Cabal's default build system will not even let
 156 code build if it tries to import a module from a package that isn't
 157 listed in the ``.cabal`` file, even if that package is actually
 158 installed. This helps to ensure that there are no "untracked
 159 dependencies" that could cause the code to fail to build on some other
 160 system.
 161
 162 The explicit dependency approach is in contrast to the traditional
 163 "./configure" approach where instead of specifying dependencies
 164 declaratively, the ``./configure`` script checks if the dependencies are
 165 present on the system. Some manual work is required to transform a
 166 ``./configure`` based package into a Linux distribution package (or
 167 similar). This conversion work is usually done by people other than the
 168 package author(s). The practical effect of this is that only the most
 169 popular packages will benefit from automatic package management.
 170 Instead, Cabal forces the original author to specify the dependencies
 171 but the advantage is that every package can benefit from automatic
 172 package management.
 173
 174 The "./configure" approach tends to encourage packages that adapt
 175 themselves to the environment in which they are built, for example by
 176 disabling optional features so that they can continue to work when a
 177 particular dependency is not available. This approach makes sense in a
 178 world where installing additional dependencies is a tiresome manual
 179 process and so minimising dependencies is important. The automatic
 180 package management view is that packages should just declare what they
 181 need and the package manager will take responsibility for ensuring that
 182 all the dependencies are installed.
 183
 184 Sometimes of course optional features and optional dependencies do make
 185 sense. Cabal packages can have optional features and varying
 186 dependencies. These conditional dependencies are still specified in a
 187 declarative way however and remain compatible with automatic package
 188 management. The need to remain compatible with automatic package
 189 management means that Cabal's conditional dependencies system is a bit
 190 less flexible than with the "./configure" approach.
 191
 192 .. note::
 193    `GNU autoconf places restrictions on paths, including the
 194    path that the user builds a package from.
 195    <https://www.gnu.org/software/autoconf/manual/autoconf.html#File-System-Conventions>`_
 196    Package authors using ``build-type: configure`` should be aware of
 197    these restrictions; because users may be unexpectedly constrained and
 198    face mysterious errors, it is recommended that ``build-type: configure``
 199    is only used where strictly necessary.
 200
 201 Portability
 202 -----------
 203
 204 One of the purposes of Cabal is to make it easier to build packages on
 205 different platforms (operating systems and CPU architectures), with
 206 different compiler versions and indeed even with different Haskell
 207 implementations. (Yes, there are Haskell implementations other than
 208 GHC!)
 209
 210 Cabal provides abstractions of features present in different Haskell
 211 implementations and wherever possible it is best to take advantage of
 212 these to increase portability. Where necessary however it is possible to
 213 use specific features of specific implementations.
 214
 215 For example a package author can list in the package's ``.cabal`` what
 216 language extensions the code uses. This allows Cabal to figure out if
 217 the language extension is supported by the Haskell implementation that
 218 the user picks. Additionally, certain language extensions such as
 219 Template Haskell require special handling from the build system and by
 220 listing the extension it provides the build system with enough
 221 information to do the right thing.
 222
 223 Another similar example is linking with foreign libraries. Rather than
 224 specifying GHC flags directly, the package author can list the libraries
 225 that are needed and the build system will take care of using the right
 226 flags for the compiler. Additionally this makes it easier for tools to
 227 discover what system C libraries a package needs, which is useful for
 228 tracking dependencies on system libraries (e.g. when translating into
 229 Linux distribution packages).
 230
 231 In fact both of these examples fall into the category of explicitly
 232 specifying dependencies. Not all dependencies are other Cabal packages.
 233 Foreign libraries are clearly another kind of dependency. It's also
 234 possible to think of language extensions as dependencies: the package
 235 depends on a Haskell implementation that supports all those extensions.
 236
 237 Where compiler-specific options are needed however, there is an "escape
 238 hatch" available. The developer can specify implementation-specific
 239 options and more generally there is a configuration mechanism to
 240 customise many aspects of how a package is built depending on the
 241 Haskell implementation, the operating system, computer architecture and
 242 user-specified configuration flags.