The Haskell Tool Stack (original) (raw)

Welcome to the Haskell programming language and the Haskell Tool Stack (Stack)! Stack is a program for developing Haskell projects. It is aimed at new and experienced users of Haskell and seeks to support them fully on Linux, macOS and Windows.

Haskell code is compiled by theGlasgow Haskell Compiler (GHC), which can also be used interactively.

Stack features include:

Stack is used at the command line. You will need terminal software for your system (which will likely come with its operating system) and a program to edit code files. There are a number of freely-available and popular code editors that have Haskell extensions.

How to install Stack

Stack can be installed on most Unix-like operating systems (including macOS) and Windows. It will require at least about 5 GB of disk space, for use with one version of GHC.

Stack can be installed directly or by using the GHCup tool.

DirectlyGHCup

Stack can be installed directly on various operating systems.

LinuxmacOSWindowsOther/direct downloads

For most Linux distributions, on x86_64 or AArch64 machine architectures, the easiest way to install Stack is to command either:

[](#%5F%5Fcodelineno-0-1)curl -sSL https://get.haskellstack.org/ | sh

or:

[](#%5F%5Fcodelineno-1-1)wget -qO- https://get.haskellstack.org/ | sh

These commands download a script file and run it using sh.

Will the installation script need root access?

The script at get.haskellstack.orgwill ask for root access using sudo. It needs such access 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 guide tosetting up.

From late 2020, Apple began a transition from Mac computers with Intel processors (Intel-based Mac) toMac computers with Apple silicon.

Intel-basedApple silicon

For most Intel-based Mac computers, the easiest way to install Stack is to command either:

[](#%5F%5Fcodelineno-2-1)curl -sSL https://get.haskellstack.org/ | sh

or:

[](#%5F%5Fcodelineno-3-1)wget -qO- https://get.haskellstack.org/ | sh

These commands download a script file and run it using sh.

Will the installation script need root access?

The script atget.haskellstack.org will ask for root access using sudo. It needs such access 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 guide tosetting up.

Mac computers with Apple silicon have an M series chip. These chips use an architecture known as ARM64 or AArch64.

For Mac computers with Apple silicon, the easiest way to install Stack is to command either:

[](#%5F%5Fcodelineno-4-1)curl -sSL https://get.haskellstack.org/ | sh

or:

[](#%5F%5Fcodelineno-5-1)wget -qO- https://get.haskellstack.org/ | sh

These commands download a script file and run it using sh.

Will the installation script need root access?

The script atget.haskellstack.org will ask for root access using sudo. It needs such access 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 guide tosetting up.

Most machines using the Windows operating system have a x86_64 architecture. More recently, Microsoft has provided Windows on Arm that runs on other processors.

x86_64Windows on Arm

On 64-bit Windows, the easiest way to install Stack is to download and install theWindows installer.

Info

By default, the Windows installer will set theStack root to C:\sr.

Note

Systems with antivirus software may need to add Stack to the list of 'trusted' applications.

I have a Windows username with a space in it

GHC 9.4.1 and later have a bug which means they do not work if the path to the ghc executable has a space character in it. The default location for Stack's 'programs' directory will have a space in the path if the value of the USERNAME environment variable includes a space.

A solution is to configure Stack to use a different location for its 'programs' directory. For further information, see thelocal-programs-pathnon-project specific configuration option documentation.

The GHC project does not yet provide a version of GHC that runs on Windows on Arm.

For other operating systems and direct downloads see the guide tosetting up.

The separate GHCup project provides a tool that can be used to install Stack and other Haskell-related tools, including GHC andHaskell Language Server(HLS). HLS is a program that is used by Haskell extensions for popular code editors.

GHCup provides Stack for some combinations of machine architecture and operating system not provided elsewhere.

By default, the script to install GHCup (which can be run more than once) also configures Stack so that if Stack needs a version of GHC, GHCup takes over obtaining and installing that version.

How do I upgrade Stack?

Follow the advice under setting up.

How do I remove Stack?

For information about how to uninstall Stack, command:

To uninstall Stack, it should be sufficient to delete:

  1. the Stack root directory (see stack path --stack-root, before you uninstall);
  2. if different, the directory containing Stack's global configuration file (see stack path --global-config, before you uninstall);
  3. on Windows, the directory containing Stack's tools (seestack path --programs, before you uninstall), which is usually located outside of the Stack root directory; and
  4. the stack executable file (see which stack, on Unix-like operating systems, or where.exe stack, on Windows).

You may also want to delete .stack-work directories in any Haskell projects that you have built using Stack.

Quick Start guide

Once Stack is installed, you can get an immediate experience of using it to build an executable with Haskell.

Step 1: Start your new project

A complex project can have more than one package and each package can have more than one executable (program). However, to start a new single-package project named my-project, issue these four commands in a terminal (click to learn more about each command):

[](#%5F%5Fcodelineno-7-1)stack new my-project # (1)! [](#%5F%5Fcodelineno-7-2)cd my-project # (2)! [](#%5F%5Fcodelineno-7-3)stack build # (3)! [](#%5F%5Fcodelineno-7-4)stack exec my-project-exe # (4)!

  1. Create a new directory named my-project. It contains all the files needed to start a project correctly, using a default template.
  2. Change the current working directory to my-project.
  3. Build the template project and create an executable named my-project-exe.
    First, if necessary, Stack will download a version of GHC in an isolated location. That won't interfere with other GHC installations on your system. (On Windows, if necessary, Stack will also downloadMSYS2. MSYS2 is a project that provides popular tools for developers on Windows.)
  4. Run (execute) the built executable, in Stack's environment.

For a complete list of Stack's commands, and flags and options common to those commands, simply command:

For help on a particular Stack command, including flags and options specific to that command, for example stack build, command:

If you want to launch a run-eval-print loop (REPL) environment, then command:

  1. stack ghci can be used instead of stack repl. GHCi is GHC's REPL tool.

People organise Haskell code into packages. If you want to use Stack to install an executable provided by a Haskell package, then all you have to do is command:

[](#%5F%5Fcodelineno-11-1)stack install <package-name>

Step 2: Next steps

The stack new my-project command in step one should have created the following files and directories, among others. Click to learn more about each file:

[](#%5F%5Fcodelineno-12-1). [](#%5F%5Fcodelineno-12-2)├── app [](#%5F%5Fcodelineno-12-3)│   └── Main.hs # (1)! [](#%5F%5Fcodelineno-12-4)├── src [](#%5F%5Fcodelineno-12-5)│   └── Lib.hs # (2)! [](#%5F%5Fcodelineno-12-6)├── test [](#%5F%5Fcodelineno-12-7)│ └── Spec.hs # (3)! [](#%5F%5Fcodelineno-12-8)├── my-project.cabal # (4)! [](#%5F%5Fcodelineno-12-9)├── package.yaml # (5)! [](#%5F%5Fcodelineno-12-10)└── stack.yaml # (6)!

  1. The Haskell source code for the executable (application).
    As your project develops you can add further source code files to the appdirectory.
  2. The executable uses a library. The Haskell source code for the library.
    As your project develops you can add further source code files to the srcdirectory.
  3. The package has a test suite executable. The Haskell source code for the test suite.
    As your project develops you can add further source code files to the testdirectory.
  4. A file describing the package in the Cabal format, including other packages on which depends. Stack generates it from the contents of the package.yaml file.
    If the package.yaml file is deleted, Stack will use the Cabal file.
  5. A file describing the package in the Hpack format. Stack generates themy-project.cabal file from its contents.
    If you want, you can delete the file and update the Cabal file directly.
    As your project develops, you may need to depend on a library provided by another Haskell package. If you do, add the name of that new package to the dependencies: section.
  6. Stack's project-level configuration. This specifies a snapshot that, in turn, specifies a version of GHC and a set of package versions chosen to work well together. It also identifies the local packages in the project.
    If you add a new package as a dependency in the package description, and Stack reports that the Stack configuration has no specified version for it, then follow Stack's likely recommended action to add a specific version to 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 recommend you read Stack's guide togetting started.

Complete guide to Stack

A complete guide to Stack is available, covering the most common ways touse Stack, its commands, itsconfiguration, specific topics, andfrequently asked questions. Terms used in Stack's documentation are also explained in the glossary.

Why Stack?

Stack has a strong focus on plans for building that are reproducible; projects that have more than one package; and a consistent, easy-to-learn set of Stack commands. It also aims to provide the ability to customise and power that experienced developers need.

Stack does not stand alone. It is built on the great work provided by:

Learn more * Cabal build system
A specification for defining Haskell packages and a library for performing builds.1

Learn more * Hackage
A repository of Haskell packages providing thousands of open source libraries and applications to help you get your work done.

Learn more * Stackage
Sets of packages from Hackage that are chosen to work well together and with a specific version of GHC.

Learn more

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

Questions?

For answers to frequently asked questions about Stack, please see theFAQ.

For general questions please post to theHaskell Community forum.

Get involved¶

Follow the advice under get involved for feedback and discussion about Stack, or if you want to know how to contribute to its maintenance or development.