doc/how-to-package-haskell-code.rst

   1 How to package Haskell code
   2 ===========================
   3
   4 .. TIP::
   5     If this is your first time using `cabal` you should check out the :doc:`Getting Started guide <getting-started>`.
   6
   7 Starting from scratch, we're going to walk you through creating a simple
   8 Haskell application.
   9
  10 **TL;DR;** ``mkdir proglet && cd proglet && cabal init --simple --exe && cabal run proglet``
  11
  12
  13 Introduction
  14 ------------
  15
  16 Every application needs a name, we'll call ours "proglet" and start by
  17 creating an empty directory.
  18
  19 .. highlight:: console
  20
  21 ::
  22
  23     $ mkdir proglet
  24     $ cd proglet/
  25
  26
  27 .. _init quickstart:
  28
  29 Using ``cabal init``
  30 --------------------
  31
  32 The ``cabal init`` command creates the necessary files for a Cabal package,
  33 it has both an ``--interactive`` (default) and ``--non-interactive``
  34 mode. The interactive mode will walk you through many of the package
  35 options and metadata, the non-interactive mode will simply pick reasonable
  36 defaults which is sufficient if you're just trying something out.
  37
  38 .. highlight:: console
  39
  40 ::
  41
  42     $ cabal init --non-interactive
  43     # You can also use -n which is the short version of --non-interactive
  44
  45 If you want, you can also try out the interactive mode, for now chose
  46 "Executable" when asked what type of package you want to build.
  47
  48 .. highlight:: console
  49
  50 ::
  51
  52     $ cabal init
  53     ...
  54     What does the package build:
  55        1) Executable
  56        2) Library
  57        3) Library and Executable
  58        4) Test suite
  59     Your choice?
  60
  61 One of the important questions is whether the package contains a library
  62 and/or an executable. Libraries are collections of Haskell modules that
  63 can be re-used by other Haskell libraries and programs, while executables
  64 are standalone programs. Test suites can both depend on a library or be
  65 standalone.
  66
  67 For the moment these are the only choices. For more complex packages
  68 (e.g. a library and multiple executables) the ``.cabal``
  69 file can be edited afterwards.
  70
  71 After you make your selection (executable; library; library
  72 and executable; or: test suite) cabal asks us a number of questions starting with
  73 which version of the cabal specification to use, our package's name
  74 (for example, "proglet"), and our package's version.
  75
  76 ::
  77
  78     Generating CHANGELOG.md...
  79     Generating Main.hs...
  80     Generating proglet.cabal...
  81
  82 Use the ``ls`` command to see the created files:
  83
  84 ::
  85
  86    $ ls
  87    CHANGELOG.md  Main.hs  proglet.cabal
  88
  89
  90 Running the program
  91 -------------------
  92
  93 Now that we have our Haskell code and the extra files that Cabal needs, we
  94 can build and run our application.
  95
  96 ::
  97
  98    $ cabal build
  99    Resolving dependencies...
 100    ...
 101    Linking /path/to/proglet ...
 102
 103    $ cabal run proglet
 104    ...
 105    Hello, Haskell!
 106
 107 Since we have an executable we can use ``cabal run proglet`` which will build
 108 our executable (and re-build it if we've made any changes) and then run the
 109 binary. The ``cabal run`` command works for any ``component-name`` (tests for
 110 example), not just the main executable.
 111
 112
 113 About the Cabal package structure
 114 ---------------------------------
 115
 116 It is assumed that all the files that make up a package live under a common
 117 root directory (apart from external dependencies). This simple example has
 118 all the package files in one directory, but most packages use one or more
 119 subdirectories.
 120
 121 Cabal needs one extra file in the package's root directory:
 122
 123 -  ``proglet.cabal``: contains package metadata and build information.
 124
 125
 126 Editing the .cabal file
 127 -----------------------
 128
 129 .. highlight:: cabal
 130
 131 Load up the ``.cabal`` file in a text editor. The first part of the
 132 ``.cabal`` file has the package metadata and towards the end of the file
 133 you will find the :pkg-section:`executable` or :pkg-section:`library`
 134 section.
 135
 136 You will see that the fields that have yet to be filled in are commented
 137 out. Cabal files use "``--``" Haskell-style comment syntax.
 138
 139 .. NOTE::
 140    Comments are only allowed on lines on their own. Trailing comments on
 141    other lines are not allowed because they could be confused with program
 142    options.
 143
 144
 145 ::
 146
 147     executable proglet
 148       main-is: Main.hs
 149       -- other-modules:
 150       -- other-extensions:
 151       build-depends: base >=4.11 && <4.12
 152       -- hs-source-dirs:
 153       default-language: Haskell2010
 154
 155
 156 If you selected earlier to create a library package then your ``.cabal``
 157 file will have a section that looks like this:
 158
 159 ::
 160
 161     library
 162       exposed-modules: MyLib
 163       -- other-modules:
 164       -- build-depends:
 165       build-depends: base >=4.11 && <4.12
 166       -- hs-source-dirs:
 167       default-language: Haskell2010
 168
 169
 170 The build information fields listed (but commented out) are just the few
 171 most important and common fields. There are many others that are covered
 172 later in this chapter.
 173
 174 Most of the build information fields are the same between libraries and
 175 executables. The difference is that libraries have a number of "exposed"
 176 modules that make up the public interface of the library, while
 177 executables have a file containing a ``Main`` module.
 178
 179 The name of a library always matches the name of the package, so it is
 180 not specified in the library section. Executables often follow the name
 181 of the package too, but this is not required and the name is given
 182 explicitly.
 183
 184
 185 Modules included in the package
 186 -------------------------------
 187
 188 For an executable, ``cabal init`` creates the ``Main.hs`` file which
 189 contains your program's ``Main`` module. It will also fill in the
 190 :pkg-field:`executable:main-is` field with the file name of your program's
 191 ``Main`` module, including the ``.hs`` (or ``.lhs``) extension. Other
 192 modules included in the executable should be listed in the
 193 :pkg-field:`other-modules` field.
 194
 195 For a library, ``cabal init`` looks in the project directory for files
 196 that look like Haskell modules and adds all the modules to the
 197 :pkg-field:`library:exposed-modules` field. For modules that do not form part
 198 of your package's public interface, you can move those modules to the
 199 :pkg-field:`other-modules` field. Either way, all modules in the library need
 200 to be listed.
 201
 202
 203 Modules imported from other packages
 204 ------------------------------------
 205
 206 While your library or executable may include a number of modules, it
 207 almost certainly also imports a number of external modules from the
 208 standard libraries or other pre-packaged libraries. (These other
 209 libraries are of course just Cabal packages that contain one or more libraries.)
 210
 211 You have to list all of the library packages that your library or
 212 executable imports modules from. Or to put it another way: you have to
 213 list all the other packages that your package depends on.
 214
 215 For example, suppose the example ``Proglet`` module imports the module
 216 ``Data.Map``. The ``Data.Map`` module comes from the ``containers``
 217 package, so we must list it:
 218
 219 ::
 220
 221     library
 222       exposed-modules:     Proglet
 223       other-modules:
 224       build-depends:       containers, base >=4.11 && <4.12
 225
 226 In addition, almost every package also depends on the ``base`` library
 227 package because it exports the standard ``Prelude`` module plus other
 228 basic modules like ``Data.List``.
 229
 230 You will notice that we have listed ``base >=4.11 && <4.12``. This gives a
 231 constraint on the version of the base package that our package will work
 232 with. The most common kinds of constraints are:
 233
 234 -  ``pkgname >=n``
 235 -  ``pkgname ^>=n``
 236 -  ``pkgname >=n && <m``
 237 -  ``pkgname ==n.*``
 238
 239 The last is just shorthand, for example ``base ==4.*`` means exactly
 240 the same thing as ``base >=4 && <5``. Please refer to the documentation
 241 on the :pkg-field:`build-depends` field for more information.
 242
 243 Also, you can factor out shared ``build-depends`` (and other fields such
 244 as ``ghc-options``) into a ``common`` stanza which you can ``import`` in
 245 your libraries and executable sections. For example:
 246
 247 ::
 248
 249     common shared-properties
 250       default-language: Haskell2010
 251       build-depends:
 252         base == 4.*
 253       ghc-options:
 254         -Wall
 255
 256     library
 257       import: shared-properties
 258       exposed-modules:
 259         Proglet
 260
 261 Note that the ``import`` **must** be the first thing in the stanza. For more
 262 information see the :ref:`common-stanzas` section.
 263
 264 .. _building-packages:
 265
 266 Building the package
 267 --------------------
 268
 269 For simple packages that's it! We can now try building the package,
 270 which also downloads and builds all required dependencies:
 271
 272 .. code-block:: console
 273
 274     $ cabal build
 275
 276 If the package contains an executable, you can run it with:
 277
 278 .. code-block:: console
 279
 280    $ cabal run
 281
 282 and the executable can also be installed for convenience:
 283
 284 .. code-block:: console
 285
 286     $ cabal install
 287
 288 When installed, the executable program lands in a special directory
 289 for binaries that may or may not already be on your system's ``PATH``.
 290 If it is, the executable can be run by typing its filename on commandline.
 291 For installing libraries see the :ref:`adding-libraries` section.