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 It contains metadata (package name and version, author name, license, etc.) and sections
  62 to define package components. Components can be used to split large codebases into smaller,
  63 more managable building blocks.
  64 A component can be of one of several types (executable, library, etc.) and describes,
  65 among other things, the location of source files and its dependencies.
  66 The ``myapp.cabal`` file above defines a single component named ``myapp`` of the executable type.
  67 Inside the ``executable`` section, the ``build-depends`` field lists the dependencies of this component.
  68
  69
  70 The ``app/Main.hs`` file is where your executable's code lives:
  71
  72 .. code-block:: haskell
  73
  74     module Main where
  75
  76     main :: IO ()
  77     main = putStrLn "Hello, Haskell!"
  78
  79
  80 To run the executable, switch into the application directory with ``cd myapp`` and  run
  81
  82 .. code-block:: console
  83
  84      $ cabal run myapp
  85      ...
  86      Hello, Haskell!
  87
  88 This command automatically determines if the executable needs to be (re)built
  89 before running the executable. With only one executable component in the package,
  90 ``cabal run`` (without a component name) is smart enough to infer it, so the name can be omitted.
  91
  92 If you just want to build the executable without running it, run:
  93
  94 .. code-block:: console
  95
  96     $ cabal build
  97     Resolving dependencies...
  98     ...
  99     Building executable 'myapp' for myapp-0.1.0.0..
 100     [1 of 1] Compiling Main             ( app/Main.hs, /home/.../myapp/dist-newstyle/build/.../myapp-tmp/Main.o )
 101     Linking /home/.../myapp/dist-newstyle/build/.../myapp
 102
 103
 104 Adding dependencies
 105 ^^^^^^^^^^^^^^^^^^^
 106
 107 Next we'll add an external dependency to our application. `Hackage
 108 <https://hackage.haskell.org/>`__ is the Haskell community's central `package`
 109 archive of open source software.
 110
 111 In our application, we'll use a package called `haskell-say
 112 <https://hackage.haskell.org/package/haskell-say>`__ to print text to the
 113 terminal with some embellishment.
 114
 115 .. TIP::
 116    If you installed ``cabal`` a while ago but haven't used it recently you may
 117    need to update the package index, you can do this by running ``cabal
 118    update``.
 119
 120 In our ``myapp.cabal`` file, we will update the ``build-depends`` field of
 121 the executable section to include ``haskell-say``:
 122
 123 .. code-block:: cabal
 124
 125    executable myapp
 126        import: warnings
 127        main-is: Main.hs
 128        build-depends:
 129            base ^>=4.19.0.0,
 130            haskell-say ^>=1.0.0.0
 131        hs-source-dirs: app
 132        default-language: Haskell2010
 133
 134
 135 .. NOTE::
 136    ``^>=1.0.0.0`` means use version 1.0.0.0 of the library or any more recent
 137    minor release with the same major version. To put it simply, this means
 138    use the latest version of the library that starts with ``1.0``.
 139
 140 Next we'll update ``app/Main.hs`` to use the ``HaskellSay`` library:
 141
 142 .. code-block:: haskell
 143
 144    module Main where
 145
 146    import HaskellSay (haskellSay)
 147
 148    main :: IO ()
 149    main = haskellSay "Hello, Haskell!"
 150
 151 ``import HaskellSay (haskellSay)`` brings the ``haskellSay`` function from the
 152 module named ``HaskellSay`` into scope. The ``HaskellSay`` module is defined in
 153 the ``haskell-say`` package that we added as a dependency above.
 154
 155 Now you can build and re-run your code to see the new output:
 156
 157 .. code-block:: console
 158
 159    $ cabal run myapp
 160        ________________________________________________________
 161       /                                                        \
 162      | Hello, Haskell!                                          |
 163       \____       _____________________________________________/
 164            \    /
 165             \  /
 166              \/
 167        _____   _____
 168        \    \  \    \
 169         \    \  \    \
 170          \    \  \    \
 171           \    \  \    \  \-----------|
 172            \    \  \    \  \          |
 173             \    \  \    \  \---------|
 174             /    /  /     \
 175            /    /  /       \  \-------|
 176           /    /  /    ^    \  \      |
 177          /    /  /    / \    \  \ ----|
 178         /    /  /    /   \    \
 179        /____/  /____/     \____\
 180
 181 Running a single-file Haskell script
 182 ------------------------------------
 183
 184 Cabal also supports running single-file Haskell scripts like
 185 the following file named ``myscript``:
 186
 187 .. code-block:: haskell
 188
 189     #!/usr/bin/env cabal
 190     {- cabal:
 191     build-depends:
 192       base ^>=4.19.0.0,
 193       haskell-say ^>=1.0.0.0
 194     -}
 195
 196     import HaskellSay (haskellSay)
 197
 198     main :: IO ()
 199     main = haskellSay "Hello, Haskell!"
 200
 201 The necessary sections of a ``.cabal`` file are placed
 202 directly into the script as a comment.
 203
 204 Use the familiar ``cabal run`` command to execute this script:
 205
 206 .. code-block:: console
 207
 208     $ cabal run myscript
 209
 210 On Unix-like systems, a Haskell script starting with ``#!/usr/bin/env cabal``, like the one above,
 211 can be run directly after setting the execute permission (+x):
 212
 213 .. code-block:: console
 214
 215     $ chmod +x myscript
 216     $ ./myscript
 217        ________________________________________________________
 218       /                                                        \
 219      | Hello, Haskell!                                          |
 220       \____        ____________________________________________/
 221            \ ... /
 222
 223 See more in the documentation for :ref:`cabal run`.
 224
 225 What Next?
 226 ----------
 227
 228 Now that you know how to set up a simple Haskell package using Cabal, check out
 229 some of the resources on the Haskell website's `documentation page
 230 <https://www.haskell.org/documentation/>`__ or read more about packages and
 231 Cabal on the :doc:`What Cabal does <cabal-context>` page.