doc/getting-started.rst

   1 Getting Started with Haskell and Cabal
   2 ======================================
   3
   4 Installing the Haskell toolchain
   5 --------------------------------
   6
   7 To install the Haskell toolchain follow the `ghcup instructions
   8 <https://www.haskell.org/ghcup/>`__.
   9
  10
  11 Creating a new application
  12 --------------------------
  13
  14 Let's start by creating a simple Haskell application from scratch where we'll
  15 learn about a Haskell package's directory structure, how to run the executable,
  16 and how to add external dependencies.
  17
  18
  19 Initializing the application
  20 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  21
  22 Start by initialising our ``myfirstapp`` project, these instructions work in
  23 unix shells and PowerShell (if you're on Windows).
  24
  25 .. code-block:: console
  26
  27     $ cabal init myfirstapp -n
  28
  29 .. note:: ``myfirstapp`` stands for the directory (or path) where the project
  30           will reside in, if omitted, ``cabal init`` will do its proceedings
  31           in the directory it's called in.
  32
  33 .. note:: ``-n`` stands for ``--non-interactive``, which means that cabal will try to guess
  34           how to set up the project for you and use the default settings, which will serve us
  35           well for the purpose of this tutorial.
  36           When setting up your projects in the future, you will likely want to omit ``-n``
  37           and do just ``cabal init``, so that cabal will interactively ask you
  38           for the details on how the project should be set up
  39           (while still offering reasonable defaults on every step).
  40           Also, you can run ``cabal init --help`` to get more info on how ``cabal init`` can be used.
  41
  42 This will generate the following files:
  43
  44 .. code-block:: console
  45
  46     $ tree
  47     .
  48     └── myfirstapp
  49         ├── app
  50         │   └── Main.hs
  51         ├── CHANGELOG.md
  52         └── myfirstapp.cabal
  53
  54 ``app/Main.hs`` is where your package's code lives.
  55
  56 ``myfirstapp.cabal`` is Cabal's metadata file which describes your package,
  57 how it is built and its dependencies. We'll be updating this file in a
  58 little bit when we add an external dependency to our package.
  59
  60
  61 Running the application
  62 ^^^^^^^^^^^^^^^^^^^^^^^
  63
  64 When we ran ``cabal init myfirstapp -n`` above, it generated a package with a single
  65 executable named same as the package (in this case ``myfirstapp``) that prints
  66 ``"Hello, Haskell!"`` to the terminal. To run the executable enter the project's
  67 directory and run it, by inputting the following commands:
  68
  69 .. code-block:: console
  70
  71     cd myfirstapp
  72     cabal run myfirstapp
  73
  74 You should see the following output in the terminal:
  75
  76 .. code-block:: console
  77
  78      $ cabal run myfirstapp
  79      ...
  80      Hello, Haskell!
  81
  82 Notice that we didn't need to run a `build` command before we ran ``cabal run``.
  83 This is because ``cabal run`` automatically determines if the code needs to be (re)built
  84 before running the executable.
  85 If you just want to build a target without running it, you can do so with ``cabal build``:
  86
  87 ``cabal build myfirstapp``
  88
  89
  90 Adding dependencies
  91 ^^^^^^^^^^^^^^^^^^^
  92
  93 Next we'll add an external dependency to our application. `Hackage
  94 <https://hackage.haskell.org/>`__ is the Haskell community's central `package`
  95 archive of open source software.
  96
  97 In our application, we'll use a package called `haskell-say
  98 <https://hackage.haskell.org/package/haskell-say>`__ to print text to the
  99 terminal with some embellishment.
 100
 101 .. TIP::
 102    If you installed ``cabal`` a while ago but haven't used it recently you may
 103    need to update the package index, you can do this by running ``cabal
 104    update``.
 105
 106 In our ``myfirstapp.cabal`` file we'll update the ``build-depends`` attribute of
 107 the ``executable myfirstapp`` section to include ``haskell-say``:
 108
 109 .. code-block:: cabal
 110
 111    executable myfirstapp
 112        import: warnings
 113        main-is: Main.hs
 114        build-depends:
 115            base ^>=4.14.3.0,
 116            haskell-say ^>=1.0.0.0
 117        hs-source-dirs: app
 118        default-language: Haskell2010
 119
 120
 121 .. NOTE::
 122    ``^>=1.0.0.0`` means use version 1.0.0.0 of the library or any more recent
 123    minor release with the same major version. To put it simply, this means
 124    use the latest version of the library that starts with ``1.0``.
 125
 126 Next we'll update ``app/Main.hs`` to use the ``HaskellSay`` library:
 127
 128 .. code-block:: haskell
 129
 130    module Main where
 131
 132    import HaskellSay (haskellSay)
 133
 134    main :: IO ()
 135    main =
 136      haskellSay "Hello, Haskell! You're using a function from another package!"
 137
 138 ``import HaskellSay (haskellSay)`` brings the ``haskellSay`` function from the
 139 module named ``HaskellSay`` into scope. The ``HaskellSay`` module is defined in
 140 the ``haskell-say`` package that we added as a dependency above.
 141
 142 Now you can build and re-run your code to see the new output:
 143
 144 .. code-block:: console
 145
 146    $ cabal run
 147        ________________________________________________________
 148       /                                                        \
 149      | Hello, Haskell! You're using a function from another     |
 150      | package!                                                 |
 151       \____       _____________________________________________/
 152            \    /
 153             \  /
 154              \/
 155        _____   _____
 156        \    \  \    \
 157         \    \  \    \
 158          \    \  \    \
 159           \    \  \    \  \-----------|
 160            \    \  \    \  \          |
 161             \    \  \    \  \---------|
 162             /    /  /     \
 163            /    /  /       \  \-------|
 164           /    /  /    ^    \  \      |
 165          /    /  /    / \    \  \ ----|
 166         /    /  /    /   \    \
 167        /____/  /____/     \____\
 168
 169 Run a single-file Haskell script
 170 --------------------------------
 171
 172 Cabal also enables us to run single-file Haskell scripts
 173 without creating a project directory or ``.cabal`` file.
 174 The cabal directives are placed in the file within a comment.
 175
 176 .. code-block:: haskell
 177
 178     #!/usr/bin/env cabal
 179     {- cabal:
 180     build-depends: base, split
 181     -}
 182
 183     import Data.List.Split (chunksOf)
 184
 185     main :: IO ()
 186     main = getLine >>= print . chunksOf 3
 187
 188 This can be run using ``cabal run myscript``.
 189 On Unix-like systems this can be run directly with execute permission.
 190
 191 .. code-block:: console
 192
 193     $ cabal run myscript
 194
 195     $ chmod +x myscript
 196     $ ./myscript
 197
 198 Project metadata can also be included:
 199
 200 .. code-block:: haskell
 201
 202     {- project:
 203     with-compiler: ghc-8.10.7
 204     -}
 205
 206 See more in the documentation for :ref:`cabal run`.
 207
 208 What Next?
 209 ----------
 210
 211 Now that you know how to set up a simple Haskell package using Cabal, check out
 212 some of the resources on the Haskell website's `documentation page
 213 <https://www.haskell.org/documentation/>`__ or read more about packages and
 214 Cabal on the :doc:`introduction <intro>` page.