The Haskell Tool Stack

Stack is a cross-platform program for developing Haskell projects. It is aimed at Haskellers both new and experienced.

It features:

• Installing GHC automatically, in an isolated location.
• Installing packages needed for your project.
• Building your project.
• Testing your project.
• Benchmarking your project.

How to install

Stack can be installed on most Unix-like (Un*x) operating systems, including macOS, and on Windows.

For most Un*x operating systems, the easiest way to install is to run:

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

or:

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

On Windows, you can download and install the Windows 64-bit Installer.

For other operating systems and direct downloads, check out the install and upgrade guide.

Note that the get.haskellstack.org script will ask for root access using sudo in order to use your platform's package manager to install dependencies and to install to /usr/local/bin. If you prefer more control, follow the manual installation instructions in the install and upgrade guide.

How to upgrade

If you already have stack installed, upgrade it to the latest version by running:

stack upgrade

Quick Start Guide

First you need to install it (see previous section).

Start your new project:

stack new my-project
cd my-project
stack setup
stack build
stack exec my-project-exe

• The stack new command will create a new directory containing all the needed files to start a project correctly.
• The stack setup will download the compiler if necessary in an isolated location (default ~/.stack) that won't interfere with any system-level installations. (For information on installation paths, please use the stack path command.).
• The stack build command will build the minimal project.
• stack exec my-project-exe will execute the command.
• If you just want to install an executable using stack, then all you have to do is stack install <package-name>.

If you want to launch a REPL:

stack ghci

Run stack for a complete list of commands.

Workflow

The stack new command should have created the following files:

.
├── app
│   └── Main.hs
├── ChangeLog.md
├── LICENSE
├── my-project.cabal
├── package.yaml
├── README.md
├── Setup.hs
├── src
│   └── Lib.hs
├── stack.yaml
└── test
    └── Spec.hs

    3 directories, 10 files

So to manage your library:

1. Edit files in the src/ directory.

   The app directory should preferably contain only files related to executables.

2. If you need to include another library (for example the package text):

   • Add the package text to the file package.yaml in the section dependencies: ....
   • Run stack build another time.
   • stack build will update my-project.cabal for you. If desired you can update the .cabal file manually and stack will use .cabal instead of package.yaml.

3. If you get an error that tells you your package isn't in the LTS. Just try to add a new version in the stack.yaml file in the extra-deps section.

That was a really fast introduction on how to start to code in Haskell using stack. If you want to go further, we highly recommend you to read the stack guide.

How to contribute

This assumes that you have already installed a version of stack, and have git installed.

1. Clone stack from git with git clone https://github.com/commercialhaskell/stack.git.
2. Enter into the stack folder with cd stack.
3. Build stack using a pre-existing stack install with stack setup && stack build.
4. Once stack finishes building, check the stack version with stack exec stack -- --version. Make sure the version is the latest.
5. Look for issues tagged with newcomer friendly and awaiting pull request labels.

Build from source as a one-liner:

git clone https://github.com/commercialhaskell/stack.git && \
cd stack && \
stack setup && \
stack build

If you need to check your changes quickly run:

stack ghci
λ: :main --stack-root /path/to/root/ --stack-yaml /path/to/stack.yaml COMMAND

This allows you to set a special stack root (instead of ~/.stack/ or, on Windows, %LOCALAPPDATA%\Programs\stack) and to target your commands at a particular stack.yaml instead of the one found in the current directory.

Complete guide to stack

This repository also contains a complete user guide to using stack, covering all of the most common use cases.

Questions, Feedback, Discussion

• For frequently asked questions about detailed or specific use-cases, please see the FAQ.
• For general questions, comments, feedback and support, please write to the stack mailing list.
• For bugs, issues, or requests, please open an issue.
• When using Stack Overflow, please use the haskell-stack tag.

Why Stack?

Stack is a build tool for Haskell designed to answer the needs of Haskell users new and experienced alike. It has a strong focus on reproducible build plans, multi-package projects, and a consistent, easy-to-learn interface, while providing the customizability and power experienced developers need. As a build tool, Stack does not stand alone. It is built on the great work provided by:

• The Glasgow Haskell Compiler (GHC), the premier Haskell compiler. Stack will manage your GHC installations and automatically select the appropriate compiler version for your project.
• The Cabal build system, a specification for defining Haskell packages, together with a library for performing builds.
• The Hackage package repository, providing more than ten thousand open source libraries and applications to help you get your work done.
• The Stackage package collection, a curated set of packages from Hackage which are regularly tested for compatibility. Stack defaults to using Stackage package sets to avoid dependency problems.

Stack is provided by a team of volunteers and companies under the auspices of the Commercial Haskell group. The project was spearheaded by FP Complete to answer the needs of commercial Haskell users, and has since become a thriving open source project meeting the needs of Haskell users of all stripes.

If you'd like to get involved with Stack, check out the newcomer friendly label on the Github issue tracker.

How to uninstall

Removing ~/.stack and /usr/local/bin/stack should be sufficient. You may want to delete .stack-work folders in any Haskell projects that you have built.