doc/getting-started.rst

   1 Getting Started
   2 ===============
   3
   4 Installing Cabal
   5 ----------------
   6
   7 The easiest and recommended way to install the ``cabal`` command-line tool
   8 on Linux, macOS, FreeBSD or Windows is through `ghcup <https://www.haskell.org/ghcup/>`__.
   9 It installs the “Haskell toolchain”, which includes Cabal,
  10 the Haskell compiler `GHC <https://www.haskell.org/ghc/>`__
  11 and optionally other useful Haskell tools.
  12
  13 Creating a new application
  14 --------------------------
  15
  16 We create a minimal Haskell application to get a quick overview
  17 of the ``cabal`` command-line tool:
  18
  19 1. How to initialize a Haskell package.
  20 2. How files are organized inside a package.
  21 3. How to compile Haskell files and run a resulting executable.
  22 4. How to manage external dependencies.
  23
  24 Initializing an application
  25 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  26
  27 To initialize a new Haskell application, run
  28
  29 .. code-block:: console
  30
  31     $ cabal init myapp --non-interactive
  32
  33 in a terminal. This generates the following files in a new ``myapp`` directory:
  34
  35 .. code-block:: console
  36
  37     $ tree
  38     .
  39     └── myapp
  40         ├── app
  41         │   └── Main.hs
  42         ├── CHANGELOG.md
  43         └── myapp.cabal
  44
  45 The ``myapp.cabal`` file is a package description file, commonly referred to as a “Cabal file”:
  46
  47 .. code-block:: cabal
  48
  49     cabal-version:      3.0
  50     name:               myapp
  51     version:            0.1.0.0
  52     -- ...
  53
  54     executable myapp
  55         import:           warnings
  56         main-is:          Main.hs
  57         build-depends:    base ^>=4.19.0.0
  58         hs-source-dirs:   app
  59         default-language: Haskell2010
  60
  61 .. warning::
  62
  63     The version bounds on base, a boot library distributed with GHC
  64     [#boot-packages]_, are tied to the GHC version visible when ``cabal init``
  65     is run. If run with a later version of GHC you might see a difference in the
  66     version bounds.
  67
  68     .. code-block:: diff
  69
  70         - build-depends:    base ^>=4.19.0.0
  71         + build-depends:    base ^>=4.20.0.0
  72
  73 It contains metadata (package name and version, author name, license, etc.) and sections
  74 to define package components. Components can be used to split large codebases into smaller,
  75 more managable building blocks.
  76 A component can be of one of several types (executable, library, etc.) and describes,
  77 among other things, the location of source files and its dependencies.
  78 The ``myapp.cabal`` file above defines a single component named ``myapp`` of the executable type.
  79 Inside the ``executable`` section, the ``build-depends`` field lists the dependencies of this component.
  80
  81
  82 The ``app/Main.hs`` file is where your executable's code lives:
  83
  84 .. code-block:: haskell
  85
  86     module Main where
  87
  88     main :: IO ()
  89     main = putStrLn "Hello, Haskell!"
  90
  91
  92 To run the executable, switch into the application directory with ``cd myapp`` and run
  93
  94 .. code-block:: console
  95
  96      $ cabal run myapp
  97      ...
  98      Hello, Haskell!
  99
 100 This command automatically determines if the executable needs to be (re)built
 101 before running the executable. With only one executable component in the package,
 102 ``cabal run`` (without a component name) is smart enough to infer it, so the name can be omitted.
 103
 104 If you just want to build the executable without running it, run:
 105
 106 .. code-block:: console
 107
 108     $ cabal build
 109     Resolving dependencies...
 110     ...
 111     Building executable 'myapp' for myapp-0.1.0.0..
 112     [1 of 1] Compiling Main             ( app/Main.hs, /home/.../myapp/dist-newstyle/build/.../myapp-tmp/Main.o )
 113     Linking /home/.../myapp/dist-newstyle/build/.../myapp
 114
 115
 116 Adding dependencies
 117 ^^^^^^^^^^^^^^^^^^^
 118
 119 Next we'll add an external dependency to our application. `Hackage
 120 <https://hackage.haskell.org/>`__ is the Haskell community's central `package`
 121 archive of open source software.
 122
 123 In our application, we'll use a package called `haskell-say
 124 <https://hackage.haskell.org/package/haskell-say>`__ to print text to the
 125 terminal with some embellishment.
 126
 127 .. TIP::
 128    If you installed ``cabal`` a while ago but haven't used it recently you may
 129    need to update the package index, you can do this by running ``cabal
 130    update``.
 131
 132 In our ``myapp.cabal`` file, we will update the ``build-depends`` field of
 133 the executable section to include ``haskell-say``:
 134
 135 .. code-block:: cabal
 136
 137    executable myapp
 138        import: warnings
 139        main-is: Main.hs
 140        build-depends:
 141            base ^>=4.19.0.0,
 142            haskell-say ^>=1.0.0.0
 143        hs-source-dirs: app
 144        default-language: Haskell2010
 145
 146
 147 .. NOTE::
 148    ``^>=1.0.0.0`` means use version 1.0.0.0 of the library or any more recent
 149    minor release with the same major version. To put it simply, this means
 150    use the latest version of the library that starts with ``1.0``.
 151
 152 Next we'll update ``app/Main.hs`` to use the ``HaskellSay`` library:
 153
 154 .. code-block:: haskell
 155
 156    module Main where
 157
 158    import HaskellSay (haskellSay)
 159
 160    main :: IO ()
 161    main = haskellSay "Hello, Haskell!"
 162
 163 ``import HaskellSay (haskellSay)`` brings the ``haskellSay`` function from the
 164 module named ``HaskellSay`` into scope. The ``HaskellSay`` module is defined in
 165 the ``haskell-say`` package that we added as a dependency above.
 166
 167 Now you can build and re-run your code to see the new output:
 168
 169 .. code-block:: console
 170
 171    $ cabal run myapp
 172        ________________________________________________________
 173       /                                                        \
 174      | Hello, Haskell!                                          |
 175       \____       _____________________________________________/
 176            \    /
 177             \  /
 178              \/
 179        _____   _____
 180        \    \  \    \
 181         \    \  \    \
 182          \    \  \    \
 183           \    \  \    \  \-----------|
 184            \    \  \    \  \          |
 185             \    \  \    \  \---------|
 186             /    /  /     \
 187            /    /  /       \  \-------|
 188           /    /  /    ^    \  \      |
 189          /    /  /    / \    \  \ ----|
 190         /    /  /    /   \    \
 191        /____/  /____/     \____\
 192
 193 Running a single-file Haskell script
 194 ------------------------------------
 195
 196 Cabal also supports running single-file Haskell scripts like
 197 the following file named ``myscript``:
 198
 199 .. code-block:: haskell
 200
 201     #!/usr/bin/env cabal
 202     {- cabal:
 203     build-depends:
 204       base,
 205       haskell-say ^>=1.0.0.0
 206     -}
 207
 208     import HaskellSay (haskellSay)
 209
 210     main :: IO ()
 211     main = haskellSay "Hello, Haskell!"
 212
 213 .. note::
 214
 215     Widening or dropping version bound constraints on *packages included with
 216     the compiler* [#boot-packages]_, like ``base``, may allow single-file
 217     scripts to run with a wider range of compiler versions.
 218
 219     .. code-block:: diff
 220
 221         build-depends:
 222         -   base ^>=4.19.0.0,
 223         +   base,
 224
 225 The necessary sections of a ``.cabal`` file are placed
 226 directly into the script as a comment.
 227
 228 The necessary sections of a package description that would otherwise be in a
 229 ``.cabal`` file are placed directly into the script as a comment.
 230
 231 Use the familiar ``cabal run`` command to execute this script:
 232
 233 .. code-block:: console
 234
 235     $ cabal run myscript
 236
 237 On Unix-like systems, a Haskell script starting with ``#!/usr/bin/env cabal``, like the one above,
 238 can be run directly after setting the execute permission (+x):
 239
 240 .. code-block:: console
 241
 242     $ chmod +x myscript
 243     $ ./myscript
 244        ________________________________________________________
 245       /                                                        \
 246      | Hello, Haskell!                                          |
 247       \____        ____________________________________________/
 248            \ ... /
 249
 250 See more in the documentation for :ref:`cabal run`.
 251
 252 .. warning::
 253
 254     Single-file scripts cannot also be part of a package, as an executable or
 255     listed as a module. Trying to run a module that is included in a package
 256     will error with `Cabal-7070`_.
 257
 258 What Next?
 259 ----------
 260
 261 Now that you know how to set up a simple Haskell package using Cabal, check out
 262 some of the resources on the Haskell website's `documentation page
 263 <https://www.haskell.org/documentation/>`__ or read more about packages and
 264 Cabal on the :doc:`What Cabal does <cabal-context>` page.
 265
 266 .. _Cabal-7070: https://errors.haskell.org/messages/Cabal-7070/
 267
 268 .. [#boot-packages] Packages included with the compiler are also called boot
 269    packages. Each GHC compiler version has accompanying `release notes`_ that
 270    list these included packages.
 271
 272 .. _release notes: https://downloads.haskell.org/ghc/latest/docs/users_guide/release-notes.html