Skip to content

Latest commit

 

History

History
346 lines (252 loc) · 11.5 KB

building_your_project.md

File metadata and controls

346 lines (252 loc) · 11.5 KB
Raw

4. Building your project

The stack build command is the heart of Stack. It is the engine that powers building your code, testing it, getting dependencies, and more. Much of the remainder of this getting started guide will cover its features.

!!! note

Using the `build` command twice with the same options and arguments should
generally do nothing (besides things like rerunning test suites), and
should, in general, produce a reproducible result between different runs.

Adding dependencies

A Haskell package often depends on code exposed by other Haskell packages.

Let's say we decide to modify our existing helloworld package source code to use a new library, the one provided by the text package.

We can modify src/Lib.hs so that its contents are as follows (click :material-plus-circle: to learn more):

{-# LANGUAGE OverloadedStrings #-} -- (1)!

module Lib
    ( someFunc
    ) where

import qualified Data.Text.IO as T -- (2)!

someFunc :: IO ()
someFunc = T.putStrLn "someFunc" --(3)!

  1. Enables overloaded string literals. String literals now have type (IsString a) => a.

  2. The module is exposed by the library of the text package.

  3. Data.Text.IO.putStrLn :: Text -> IO ().

If we command:

stack build

Stack will report Stack error [S-7282] during the build, with output like the following:

...
Building library for helloworld-0.1.0.0..
[1 of 2] Compiling Lib [Source file changed]

src\Lib.hs:7:1: error:
    Could not load module ‘Data.Text.IO’
    It is a member of the hidden package ‘text-2.0.2’.
    Perhaps you need to add ‘text’ to the build-depends in your .cabal file.
    Use -v (or `:set -v` in ghci) to see a list of the files searched for.
  |
7 | import qualified Data.Text.IO as T
  | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Error: [S-7282]
       Stack failed to execute the build plan.

       While executing the build plan, Stack encountered the error:

       [S-7011]
       While building package helloworld-0.1.0.0 (scroll up to its section to
       see the error) using:
       ...
       Process exited with code: ExitFailure 1

The error Could not load module ... means that the package exposing the module in question is not available.

To tell Stack that the text package is a dependency of the helloworld package, you need to update the package description file (package.yaml). Specifically, you need to add text under the dependencies key, like this:

dependencies:
- base >= 4.7 && < 5
- text # added

Now, if we command:

stack build

we should get a successful result.

The output means that the text package was downloaded, configured, built, and locally installed. Once that was done, we moved on to building our project package (helloworld). At no point did we need to ask Stack to build dependencies — it does so automatically.

Listing dependencies

Let's have Stack add a few more dependencies to our project. First, we'll include two new packages in the dependencies section for our library in our package.yaml:

dependencies:
- base >= 4.7 && < 5
- text
- filepath # added
- containers # added

After adding these two dependencies, we can again command:

stack build

to have them downloaded, configured, built, and locally installed.

To find out which versions of these packages Stack installed, we can command:

stack ls dependencies

Packages not in the snapshot

The packages text, filepath and containers have something in common: they are all provided with GHC (referred to as GHC boot packages).

Let's try a dependency on a more off-the-beaten-track package: the joke acme-missiles package.

We can further modify src/Lib.hs so that its contents are as follows:

module Lib
    ( someFunc
    ) where

import Acme.Missiles ( launchMissiles )

someFunc :: IO ()
someFunc = launchMissiles

As before, to tell Stack that the acme-missiles package is a dependency of the helloworld package, we must update the package description file (package.yaml). The relevant part of that file now looks like this:

dependencies:
- base >= 4.7 && < 5
- text
- filepath
- containers
- acme-missiles # added

However, if we command:

stack build

Stack will report Stack error [S-4804] during the build, with output like the following:

Error: [S-4804]
       Stack failed to construct a build plan.

       While constructing the build plan, Stack encountered the following
       errors. The 'Stack configuration' refers to the set of package versions
       specified by the snapshot (after any dropped packages, or pruned GHC boot
       packages; if a boot package is replaced, Stack prunes all other such
       packages that depend on it) and any extra-deps:

       In the dependencies for helloworld-0.1.0.0:
         * acme-missiles needed, but no version is in the Stack configuration
           (latest matching version is 0.3).
       The above is/are needed since helloworld is a build target.

       Some different approaches to resolving some or all of this:

         * Recommended action: try adding the following to your extra-deps in
           ...\helloworld\stack.yaml (project-level configuration):

           - acme-missiles-0.3@sha256:2ba66a092a32593880a87fb00f3213762d7bca65a6
87d45965778deb8694c5d1,613

The error message explains that Stack was unable to construct a build plan and why: the package acme-missiles was needed but no version of that package is in the set of package versions specified by the snapshot. Stack makes a suggestion to fix that.

This brings us to the next major topic in using Stack.

Extending snapshots

A snapshot specifies a version of GHC and a set of package versions chosen to work well together. However, sometimes you will want to use package versions that are not specified by the snapshot. That may be because the package is not in the snapshot or because a different version of the package is in the snapshot.

Remember above when stack new selected some LTS snapshot for us? That defined our build plan and available packages. When we tried using the text package, it just worked, because it was part of the LTS package set.

We have updated the description of the helloworld package (in package.yaml) to specify that it depends on the acme-missiles package, but acme-missiles is not a member of the set of package versions specified by the snapshot. So building failed.

To add a version of acme-missiles to the available package versions, we'll use the extra-deps key in Stack's project-level configuration file (stack.yaml). That key defines extra package versions, not present in the snapshot, that will be needed as dependencies. You can add this like so:

extra-deps:
- acme-missiles-0.3 # not in the LTS snapshot

Now, if we command:

stack build

we should get a successful result.

Stackage snapshots

With that out of the way, let's dig a little bit more into these snapshots. We mentioned the LTS snapshots, and you can get information about it at https://www.stackage.org/lts, including:

  • The appropriate value (lts-22.30, as is currently the latest LTS)
  • The GHC version used
  • A full list of all packages versions available in this snapshot
  • The ability to perform a Hoogle search on the packages in this snapshot
  • A list of all modules in a snapshot, which can be useful when trying to determine which package to add to your package.yaml file.

You can also see a list of all available snapshots. You'll notice two flavors: LTS (for "Long Term Support") and Nightly. You can read more about them on the LTS Haskell GitHub page. If you're not sure which to use, start with LTS Haskell (which Stack will lean towards by default as well).

Snapshots and GHC versions

As mentioned, a snapshot specifies a version of GHC as well as a set of package versions.

??? question "I want to use a particular version of GHC. What snapshot should I use?"

For each supported version of GHC, the Stackage
[homepage](https://www.stackage.org/) lists the most recent Stackage
snapshot. In most cases, that is the snapshot you should use.

??? question "Can I use a snapshot like ghc-9.6.6?"

Snapshot `ghc-9.6.6` specifies GHC 9.6.6 and, consequently, the GHC boot
packages that come with that compiler. However, the snapshot does not
include the many other package versions that will work with that compiler.
For a set of those package versions, see the snapshots published by the
[Stackage](https://www.stackage.org/) project.

Let us try using an older Stackage LTS Haskell snapshot. We will use the LTS 21.25 snapshot with the command:

stack --snapshot lts-21.25 build

Stackage LTS Haskell 21.25 specifies GHC 9.4.8. If that version of GHC is not already available, Stack will try to fetch it and install it before starting the rest of the build.

Specifying a snapshot

A snapshot must be specified in Stack's project-level configuration file (stack.yaml, by default). For further information, see the snapshot project-specific configuration option documentation.

As we have seen, a snapshot can also be specified on the command line. That can be useful in a Continuous Integration (CI) setting.

When passed on the command line, you also get some additional "short-cut" versions of snapshots: --snapshot nightly will use the newest Nightly snapshot available, --snapshot lts will use the newest LTS, and --snapshot lts-22 will use the newest LTS in the 22.x series. The reason these are only available on the command line and not in your stack.yaml file is that using them:

  1. Will slow down your build (since Stack then needs to download information on the latest available LTS each time it builds)
  2. Produces unreliable results (since a build run today may proceed differently tomorrow because of changes outside of your control)

Cleaning up your project

Stack creates files during the build process and stores those files in directories within a local project or package directory known as Stack work directories. Stack can be used without an understanding of the content of those directories.

if you wish, you can clean up files created during the build process for your project using the stack clean and stack purge commands.

The stack clean command

stack clean deletes the local working directories containing compiler output. By default, that means the contents of directories in .stack-work/dist, for all the .stack-work directories within a project.

Use stack clean <specific-package> to delete the output for the package specific-package only.

The stack purge command

stack purge deletes the local stack working directories, including extra-deps, git dependencies and the compiler output (including logs). It does not delete any snapshot packages, compilers or programs installed using stack install. This essentially reverts the project to a completely fresh state, as if it had never been built.

stack purge is a shortcut for stack clean --full.