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 the Glasgow Haskell Compiler (GHC), which can also be used interactively.
Stack features include:
- Installing GHC automatically.
- Installing packages needed for your project.
- Building your project.
- Testing your project.
- Benchmarking your project.
- Using GHC interactively.
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.
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.
=== "Directly"
Stack can be installed directly on various operating systems.
=== "Linux"
For most Linux distributions, on x86_64 or AArch64 machine
architectures, the easiest way to install Stack is to command either:
~~~text
curl -sSL https://get.haskellstack.org/ | sh
~~~
or:
~~~text
wget -qO- https://get.haskellstack.org/ | sh
~~~
These commands download a script file and run it using `sh`.
??? question "Will the installation script need root access?"
The script at [get.haskellstack.org](https://get.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 to
[setting up](install_and_upgrade.md).
=== "macOS"
From late 2020, Apple began a transition from Mac computers with Intel
processors (Intel-based Mac) to
[Mac computers with Apple silicon](https://support.apple.com/en-gb/HT211814).
=== "Intel-based"
For most Intel-based Mac computers, the easiest way to install Stack
is to command either:
~~~text
curl -sSL https://get.haskellstack.org/ | sh
~~~
or:
~~~text
wget -qO- https://get.haskellstack.org/ | sh
~~~
These commands download a script file and run it using `sh`.
??? question "Will the installation script need root access?"
The script at
[get.haskellstack.org](https://get.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 to
[setting up](install_and_upgrade.md).
=== "Apple silicon"
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:
~~~text
curl -sSL https://get.haskellstack.org/ | sh
~~~
or:
~~~text
wget -qO- https://get.haskellstack.org/ | sh
~~~
These commands download a script file and run it using `sh`.
??? question "Will the installation script need root access?"
The script at
[get.haskellstack.org](https://get.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 to
[setting up](install_and_upgrade.md).
=== "Windows"
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_64"
On 64-bit Windows, the easiest way to install Stack is to download
and install the
[Windows installer](https://get.haskellstack.org/stable/windows-x86_64-installer.exe).
!!! info
By default, the Windows installer will set the
[Stack root](topics/stack_root.md) to `C:\sr`.
!!! note
Systems with antivirus software may need to add Stack to the
list of 'trusted' applications.
??? warning "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 the
[`local-programs-path`](configure/yaml/non-project.md#local-programs-path)
non-project specific configuration option documentation.
=== "Windows on Arm"
The GHC project does not yet provide a version of GHC that runs on
Windows on Arm.
=== "Other/direct downloads"
For other operating systems and direct downloads see the guide to
[setting up](install_and_upgrade.md).
=== "GHCup"
The separate [GHCup](https://www.haskell.org/ghcup/) project provides a tool
that can be used to install Stack and other Haskell-related tools, including
GHC and
[Haskell Language Server](https://github.com/haskell/haskell-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.
??? question "How do I upgrade Stack?"
Follow the advice under [setting up](install_and_upgrade.md#upgrade-stack).
??? question "How do I remove Stack?"
For information about how to uninstall Stack, command:
~~~text
stack uninstall
~~~
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 (see
`stack 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.
Once Stack is installed, you can get an immediate experience of using it to build an executable with Haskell.
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
:material-plus-circle: to learn more about each command):
stack new my-project # (1)!
cd my-project # (2)!
stack build # (3)!
stack exec my-project-exe # (4)!-
Create a new directory named
my-project. It contains all the files needed to start a project correctly, using a default template. -
Change the current working directory to
my-project. -
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 download MSYS2. MSYS2 is a project that provides popular tools for developers on Windows.)
-
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:
stack
For help on a particular Stack command, including flags and options specific to
that command, for example stack build, command:
stack build --help
If you want to launch a run-eval-print loop (REPL) environment, then command:
stack repl # (1)!stack ghcican be used instead ofstack 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:
stack install <package-name>
The stack new my-project command in step one should have created the following
files and directories, among others. Click :material-plus-circle: to learn more
about each file:
.
├── app
│ └── Main.hs # (1)!
├── src
│ └── Lib.hs # (2)!
├── test
│ └── Spec.hs # (3)!
├── my-project.cabal # (4)!
├── package.yaml # (5)!
└── stack.yaml # (6)!-
The Haskell source code for the executable (application).
As your project develops you can add further source code files to the
appdirectory. -
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. -
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. -
A file describing the package in the Cabal format, including other packages on which depends. Stack generates it from the contents of the
package.yamlfile.If the
package.yamlfile is deleted, Stack will use the Cabal file. -
A file describing the package in the Hpack format. Stack generates the
my-project.cabalfile 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. -
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 to getting started.
A complete guide to Stack is available, covering the most common ways to use Stack, its commands, its configuration, specific topics, and frequently asked questions. Terms used in Stack's documentation are also explained in the glossary.
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:
-
:fontawesome-solid-gears:{ .lg .middle } Glasgow Haskell Compiler
The premier Haskell compiler. Stack will manage your GHC installations and automatically select the appropriate version of GHC for your project.
-
:fontawesome-solid-trowel-bricks:{ .lg .middle } Cabal build system
A specification for defining Haskell packages and a library for performing builds.1
-
:octicons-database-24:{ .lg .middle } Hackage
A repository of Haskell packages providing thousands of open source libraries and applications to help you get your work done.
-
:fontawesome-solid-cubes-stacked:{ .lg .middle } Stackage
Sets of packages from Hackage that are chosen to work well together and with a specific version of GHC.
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.
For answers to frequently asked questions about Stack, please see the FAQ.
For general questions please post to the Haskell Community forum.
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.
Footnotes
-
Cabal is also the name of a tool used for building Haskell code, provided by the
cabal-installpackage. This guide distinguishes between them by Cabal (the library) and Cabal (the tool). ↩