doc/how-to-use-backpack.rst

   1 .. _Backpack:
   2
   3 How to use Backpack modules
   4 ===========================
   5
   6 Cabal and GHC jointly support Backpack, an extension to Haskell's module
   7 system which makes it possible to parametrize a package over some
   8 modules, which can be instantiated later arbitrarily by a user.  This
   9 means you can write a library to be agnostic over some data
  10 representation, and then instantiate it several times with different
  11 data representations.  Like C++ templates, instantiated packages are
  12 recompiled for each instantiation, which means you do not pay any
  13 runtime cost for parametrizing packages in this way.  Backpack modules
  14 are somewhat experimental; while fully supported by cabal-install, they are currently
  15 `not supported by Stack <https://github.com/commercialhaskell/stack/issues/2540>`__.
  16
  17 A Backpack package is defined by use of the
  18 :pkg-field:`library:signatures` field, or by (transitive) dependency on
  19 a package that defines some requirements.  To define a parametrized
  20 package, define a signature file (file extension ``hsig``) that
  21 specifies the signature of the module you want to parametrize over, and
  22 add it to your Cabal file in the :pkg-field:`library:signatures` field.
  23
  24 .. code-block:: haskell
  25     :caption: .hsig
  26
  27     signature Str where
  28
  29     data Str
  30
  31     concat :: [Str] -> Str
  32
  33 .. code-block:: cabal
  34     :caption: parametrized.cabal
  35
  36     cabal-version: 2.2
  37     name: parametrized
  38
  39     library
  40       build-depends: base
  41       signatures: Str
  42       exposed-modules: MyModule
  43
  44 You can define any number of regular modules (e.g., ``MyModule``) that
  45 import signatures and use them as regular modules.
  46
  47 If you are familiar with ML modules, you might now expect there to be
  48 some way to apply the parametrized package with an implementation of
  49 the ``Str`` module to get a concrete instantiation of the package.
  50 Backpack operates slightly differently with a concept of *mix-in
  51 linking*, where you provide an implementation of ``Str`` simply by
  52 bringing another module into scope with the same name as the
  53 requirement.  For example, if you had a package ``str-impl`` that provided a
  54 module named ``Str``, instantiating ``parametrized`` is as simple as
  55 just depending on both ``str-impl`` and ``parametrized``:
  56
  57 .. code-block:: cabal
  58     :caption: combined.cabal
  59
  60     cabal-version: 2.2
  61     name: combined
  62
  63     library
  64       build-depends: base, str-impl, parametrized
  65
  66 Note that due to technical limitations, you cannot directly define
  67 ``Str`` in the ``combined`` library; it must be placed in its own
  68 library (you can use :ref:`Sublibraries <sublibs>` to conveniently
  69 define a sub-library).
  70
  71 However, a more common situation is that your names don't match up
  72 exactly.  The :pkg-field:`library:mixins` field can be used to rename
  73 signatures and modules to line up names as necessary.  If you have
  74 a requirement ``Str`` and an implementation ``Data.Text``, you can
  75 line up the names in one of two ways:
  76
  77 * Rename the requirement to match the implementation:
  78   ``mixins: parametrized requires (Str as Data.Text)``
  79 * Rename the implementation to match the requirement:
  80   ``mixins: text (Data.Text as Str)``
  81
  82 The :pkg-field:`library:mixins` field can also be used to disambiguate
  83 between multiple instantiations of the same package; for each
  84 instantiation of the package, give it a separate entry in mixins with
  85 the requirements and provided modules renamed to be distinct.
  86
  87 .. code-block:: cabal
  88     :caption: .cabal
  89
  90     cabal-version: 2.2
  91     name: double-combined
  92
  93     library
  94       build-depends: base, text, bytestring, parametrized
  95       mixins:
  96         parametrized (MyModule as MyModule.Text) requires (Str as Data.Text),
  97         parametrized (MyModule as MyModule.BS) requires (Str as Data.ByteString)
  98
  99 Intensive use of Backpack sometimes involves creating lots of small
 100 parametrized libraries; :ref:`Sublibraries <sublibs>` can be used
 101 to define all of these libraries in a single package without having to
 102 create many separate Cabal packages.  You may also find it useful to use
 103 :pkg-field:`library:reexported-modules` to reexport instantiated
 104 libraries to Backpack-unware users (e.g., Backpack can be used entirely
 105 as an implementation detail.)
 106
 107 Backpack imposes a limitation on Template Haskell that goes beyond the usual TH
 108 stage restriction: it's not possible to splice TH code imported from a
 109 compilation unit that is still "indefinite", that is, a unit for which some
 110 module signatures still haven't been matched with implementations. The reason
 111 is that indefinite units are typechecked, but not compiled, so there's no
 112 actual TH code to run while splicing. Splicing TH code from a definite
 113 compilation unit into an indefinite one works normally.
 114
 115 For more information about Backpack, check out the
 116 `GHC wiki page <https://gitlab.haskell.org/ghc/ghc/-/wikis/backpack>`__.
 117