/stack-sample-project

reference stack project and cheat sheet

Primary LanguageHaskell

Stack Project Template and Cheat Sheet

This project aims to provide a stack project that works as a template for many common use cases, including sample code for basic things. It’s inspired by Pbrisbins haskell project checklist.

Current Status: WIP.

Structure

stack.yaml

The basic configuration file for the entire project is ./stack.yaml, defining the basic resolver and structure.

  • extra-deps will (later) be used to specify versions that don’t exist or are not compatible with stackage
  • the nix section should contain all the packages that are required for linking
  • packages defines the locations of what would be modules in a maven or gradle world.
resolver: lts-11.10
packages:
  - '.'
extra-deps: []
nix:
  enable:
    true
  packages: [ zlib ]

package.yaml

We a include ./package.yaml file that defines the structure of the individual structure of the module:

  • library, executables, tests
  • dependencies: globally and per entry
    • only your tests depend on the test framework
    • only your executable depends on the option parser library
    • …

Stack Cheat Sheet

Tests

  • ghci session w/ loaded tests (tasty) module: stack ghci :tasty

Debugging

Using the debug package, it’s possible to annotate functions and analyse their behavior.

Enable the following extensions, import Debug module and annotate your function:

{-# LANGUAGE TemplateHaskell, ViewPatterns, PartialTypeSignatures #-}

module ...

import Debug

debug [d|
  fun1debug :: [a] -> [a]
  fun1debug []     = []
  fun1debug (x:xs) = fun1debug xs ++ [x]
  |]

Trigger function execution (e.g. via ghci), and afterwards run debugView:

> fun1debug "some string to reverse"
"esrever ot gnirts emos"
> debugView
/run/user/1000/debug6626-0.html: xdg-open: command not found
Failed to start a web browser, open: /run/user/1000/debug6626-0.html
In future you may wish to use 'debugSaveTrace.

Open the html page in your editor of choice.

Project Goals

Create an annotated stack project with the following properties:

  • [ ] multi-module build
  • [ ] code generation: proto-lens
    • [ ] use the generated code in the same module
    • [ ] use the generated code in another module
  • [X] tests
  • [ ] benchmarks
  • [X] nix support (not a nix-based build, just stack nix support)
  • [ ] dependency outside of stackage

Use the following frameworks / libraries:

  • [X] tasty: test execution framework
  • [ ] hedgehog: property based testing (integrate via tasty-hedgehog)
  • [X] criterion

Provide sample code:

  • [-] tests
    • [X] tasty-hunit
    • [X] hspec
    • [ ] quickcheck
    • [ ] hedgehog
  • [X] benchmarks

acceptance criteria:

  • [ ] documentation of the structure, describing each non-obvious entry