haskell-template

Get a Haskell development environment up and running quickly, as long as Nix is available on your system¹.

This repository is a Haskell project template that is optimized for a fully reproducible and friendly development environment. It is based on:

• Nix + Flakes (via github:srid/haskell-flake) + GHC 9
• VSCode + HLS
• fourmolu autoformatting
• Relude as Prelude.
  • .hlint.yaml is from relude

Getting Started

First-time setup:

• Install Nix (>= 2.8) & enable Flakes (Using Windows? See footnote¹)
• Run nix develop -i -c haskell-language-server to sanity check your environment
• Open as single-folder workspace in Visual Studio Code
  • When prompted by VSCode, install the workspace recommended extensions
  • Ctrl+Shift+P to run command "Nix-Env: Select Environment" and then select shell.nix.
    • The extension will ask you to reload VSCode at the end. Do it.

To run the program with auto-recompile:

• Press Ctrl+Shift+B in VSCode, or run bin/run in terminal, to launch Ghcid running your program.

Open Main.hs, and expect all HLS IDE features like hover-over tooltip to work out of the box. Try changing the source, and expect Ghcid to re-compile and re-run the app in the terminal below.

---

Renaming the project:

# First, click the green "Use this template" button on GitHub to create your copy.
git clone <your-clone-url>
cd your-project
NAME=myproject

git mv haskell-template.cabal ${NAME}.cabal
nix run nixpkgs#sd -- haskell-template ${NAME} * */*
git add . && git commit -m rename

Tips

• Run nix flake update to update all flake inputs.
• Run nix --option sandbox false build .#check -L to run the flake checks.
• Run treefmt in nix shell to autoformat the project. This uses treefmt, which uses ./treefmt.toml (where fourmolu and nixpkgs-fmt are specified).
• Run bin/hoogle to start Hoogle with packages in your cabal file.
• Run bin/test to run the test suite.
• Run the application without installing: nix run github:srid/haskell-template (or nix run . from checkout)

Common workflows

Adding tests

1. Split any logic code out of Main.hs into, say, a Lib.hs.
2. Correspondingly, add other-modules: Lib to the "shared" section of your cabal file.
3. Add tests/Spec.hs (example below):

   module Main where
   
   import Lib qualified
   import Test.Hspec (describe, hspec, it, shouldContain)
   
   main :: IO ()
   main = hspec $ do
     describe "Lib.hello" $ do
       it "contains the world emoji" $ do
         toString Lib.hello `shouldContain` "🌎"
   

4. Add the tests stanza to the cabal file:

   test-suite tests
   import:         shared
   main-is:        Spec.hs
   type:           exitcode-stdio-1.0
   hs-source-dirs: tests
   build-depends:  hspec
   

5. Update hie.yaml accordingly; for example, by adding,

     - path: "tests"
       component: "test:tests"
   

6. Add bin/test and chmod a+x it:

   #!/usr/bin/env bash
   set -xe
   
   exec nix develop -i -c ghcid -c "cabal repl test:tests" -T :main
   

7. Commit your changes to Git, and test it out by running bin/test.

Adding Garnix CI

To use Garnix instead of Github Actions, you may provide a garnix.yaml like the below:

builds:
  include:
    - "packages.x86_64-linux.*"
    - "packages.aarch64-darwin.*"
    - "checks.x86_64-linux.*"
    - "checks.aarch64-darwin.*"
    - "devShells.x86_64-linux.default"
    - "devShells.aarch64-darwin.default"
  exclude:
    # https://github.com/srid/haskell-flake/issues/21
    - "checks.*.default-hls"
    - "packages.*.check"

Discussions

Got questions? Ideas? Suggestions? Post them here: https://github.com/srid/haskell-template/discussions

---

1. On Windows, you may install Nix under WSL2 and use the Remote - WSL extension to connect from the native VSCode. This runs your project under Linux while providing a near-native development experience on Windows. ↩︎