Installation & Usage¶

Installation¶

You can either use this GitHub template repository as a GitHub template for a Haskell project and manually change all occurrences of TestHaskell, Release-Candidate and my name. Or use BigTemplate.hsfiles to generate a local project from this repository, using stack new:

stack new PROJECT_NAME https://raw.githubusercontent.com/Release-Candidate/HaskellTemplate/main/BigTemplate.hsfiles

This template needs the following (usual) parameters to be defined:

• author-email
• author-name
• github-username
• copyright

It also understands the parameter

• license-name - to set the name of the licenses to something else but MIT.

This parameters can be set in a global or user config.yaml file for Stack or passed as command line arguments like this:

stack new PROJECT_NAME https://raw.githubusercontent.com/Release-Candidate/HaskellTemplate/main/BigTemplate.hsfiles -p "author-email:EMAIL" -p "author-name:NAME" -p "github-username:GITUSER" -p "license-name:BSD" -p "copyright:(C) ..."

Information on how to install Stack you find below.

As soon as the project ist checked in to Git, you must set the executable bit of all shell scripts, because they are not executable when generated from the templates. Run the script

• ./make_sh_executable.bat - for Windows
• ./make_sh_executable.sh - for Unix

This script recursively calls

git add --chmod=+x SHELL_SCRIPT

for all shell scripts in the directory.

Before you can use the configured Tools of this project, you have to download and install the needed tools.

Pipenv and MkDocs¶

To generate the documentation using MkDocs (see Changing and Generating Documentation), a virtual Python environment is needed. So, first you need to install Python, if you don’t have it installed already - either from your distributions repository, using the XCode or Homebrew version, or getting it from Python.org.

In the file Pipfile there is a stanza saying

[requires]
python_version = "3.9"

That’s just because I used 3.9 when generating that
documentation, and Pipenv is picky about the version mentioned
there. Just edit that to match your installed
Python version.
Install pipenv using the package
manager pip

pip install pipenv

Now you’re ready to download and install the needed packages using pipenv

pipenv install --dev

After that you should be able to use the executable mkdocs in the local virtual Python environment in your project root using pipenv run:

pipenv run mkdocs --version

Haskell Stack¶

TestHaskell uses Stack as a build tool and to manage dependencies. You can install it using your distribution’s package manager, Homebrew on Macs or Chocolatey on Windows. On Linux I advise you to use the install script with Curl

curl -sSL https://get.haskellstack.org/ | sh

or Wget:

wget -qO- https://get.haskellstack.org/ | sh

because the Stack packages are old (<2.0) and you’d need to install using stack upgrade anyway. The Homebrew and Chocolatey packages are up-to-date.

You do not need to install GHC, the Haskell compiler, or Cabal, Stack does that for us in the next step.

If Stack is working, which you can test with

stack --version

it’s time to install all needed tools for the project. There are two scripts

• ./install_build_tools.bat on Windows
• ./install_build_tools.sh on a unixish OS like Linux or Mac OS X

that do that for us. The scripts call the following commands:

pipenv install --dev
stack build --copy-compiler-tool hlint
stack build --copy-compiler-tool hoogle
stack build --copy-compiler-tool implicit-hie
stack build --copy-compiler-tool ghcid
stack build --copy-compiler-tool haskell-dap
stack build --copy-compiler-tool ghci-dap
stack build --copy-compiler-tool haskell-debug-adapter
stack build --copy-compiler-tool ormolu
stack build --copy-compiler-tool weeder
stack exec gen-hie > hie.yaml

so afterwards we can use HLint, Hoogle, gen-hie, GHCi, Debug Adapter, Ormolu and Weeder.

Download¶

[This is for the project template, not the Stack template]
Download the latest release at GitHub: Release at GitHub