Language Guide: Haskell

This guide will help you get started with a basic Haskell application on CircleCI 2.0. If you’re in a rush, feel free to copy the sample configuration below into a .circleci/config.yml in your project’s root directory and start building.

• Sample Configuration
• Config Walkthrough

Overview

You can view an example Haskell project that build with CircleCI at the following link:

• Demo Haskell Project on Github

In the project you will find a commented CircleCI configuration file .circleci/config.yml.

Sample Configuration

version: 2.1
jobs:
  build:
    docker:
      - image: fpco/stack-build:lts
    steps:
      - checkout
      - restore_cache:
          # Read about caching dependencies: https://circleci.com/docs/2.0/caching/
          name: Restore Cached Dependencies
          keys:
            - cci-demo-haskell-v1-{{ checksum "package.yaml" }}
      - run:
          name: Resolve/Update Dependencies
          command: stack setup
      - run:
          name: Run tests
          command: stack test
      - run:
          name: Install executable
          command: stack install
      - save_cache:
          name: Cache Dependencies
          key: cci-demo-haskell-v1-{{ checksum "package.yaml" }}
          paths:
            - ".stack-work"
      - store_artifacts:
          # Upload test summary for display in Artifacts: https://circleci.com/docs/2.0/artifacts/ 
          path: ~/.local/bin/circleci-demo-haskell-exe
          destination: circleci-demo-haskell-exe

Config Walkthrough

Every config.yml starts with the version key. This key is used to issue warnings about breaking changes.

version: 2.1

Next, we have a jobs key. Each job represents a phase in your workflow. Our sample app only needs a build job, so all our steps and commands will live under that key.

A run is comprised of one or more jobs. Because this run does not use workflows, it must have a build job.

The steps of a job occur in a virtual environment called an executor.

In this example, the docker executor is used to specify a custom Docker image. The first image listed becomes the job’s primary container.

All commands for a job execute in this container.

jobs:
  build:
    docker:
      - image: fpco/stack-build:lts

We are now set to run the Haskell build tool stack in our environment. The remainder of our config.yml file all falls under the steps key.

Our first step is to run checkout to pull our repository’s code down and set it up in our environment.

Next we check if there are any dependencies that can be restored, enabling our build to speed up. Following that, we run stack setup to pull in the Haskell compiler as specified in the stack.yaml config.

    steps:
      - checkout
      - restore_cache:
          name: Restore Cached Dependencies
          keys:
            - cci-demo-haskell-v1-{{ checksum "package.yaml" }}
      - run:
          name: Resolve/Update Dependencies
          command: stack setup
      - save_cache:
          name: Cache Dependencies
          key: cci-demo-haskell-v1-{{ checksum "package.yaml" }}
          paths:
            - ~/.stack
            - ~/.stack-work

Note: It’s also possible to use a cabal build file for caching dependencies. stack, however, is commonly recommended especially for those new to the Haskell ecosystem. Because this demo app leverages stack.yaml and package.yaml, we use the latter as the cache key for our dependencies. You can read more about the differences between stack and cabal on The Haskell Tool Stack docs.

Finally, we can run our application build commands. We’ll run our tests first and then move on to install our executable. Running stack install will create a binary and move it to ~/.local/bin.

      - run:
          name: Run tests
          command: stack test
      - run:
          name: Install executable
          command: stack install

Finally, we can take the built executable and store it as an artifact.

      - store_artifacts:
          # Upload buildresults for display in Artifacts: https://circleci.com/docs/2.0/artifacts/ 
          path: ~/.local/bin/circleci-demo-haskell-exe 
          destination: circleci-demo-haskell-exe

Excellent! You are now setup on CircleCI with a Haskell app.

See Also

See the Deploy document for example deploy target configurations.

The app described in this guide illustrates the simplest possible setup for a Haskell web app. Real-world projects will be more complex and you may find you need to customize and tweak settings from those illustrated here (such as the docker image or configuration you use, or which Haskell build tools you use). Have fun!