The Haskell Tool Stack¶
Welcome to the Haskell programming language and the Haskell Tool Stack (Stack)! Stack is a program for developing Haskell projects. It is aimed at Haskellers both new and experienced. It is cross-platform and aims to support fully users on Linux, macOS and Windows.
Stack features:
- Installing the Glasgow Haskell Compiler (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¶
Stack can be installed on most Unix-like operating systems (including macOS) and Windows.
For most Unix-like operating systems, the easiest way to install Stack is to command:
or:
Note
The script at 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
install and upgrade guide.
On 64-bit Windows, you can download and install the Windows installer.
Note
Systems with antivirus software may need to add Stack to the list of 'trusted' applications.
For other operating systems and direct downloads, see the install and upgrade guide.
Info
Stack can also be installed using the separate GHCup installer for Haskell-related tools.
How to upgrade Stack¶
If Stack is already installed, you can upgrade it to the latest version by the command:
Quick Start guide¶
For an immediate experience of using Stack to build an executable with Haskell, first you need to follow the guide to install Stack.
Step 1: Start your new project¶
To start a new project named my-project
, issue these four commands in a
terminal:
- The
stack new my-project
command will create a new directory, namedmy-project
. It contains all the files needed to start a project correctly, using a default template. - The
cd my-project
command will change the current working directory to that directory. - The
stack build
command will build the template project and create an executable namedmy-project-exe
(on Windows,my-project-exe.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. - The
stack exec my-project-exe
command will run (execute) the built executable, in Stack's environment.
For a complete list of Stack's commands and options, simply command:
For help on a particular Stack command, for example stack build
, command:
If you want to launch a run-eval-print loop (REPL) environment, then command:
Info
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:
Step 2: Next steps¶
The stack new my-project
command in step one should have created the following
files and directories (among others):
.
├── app
│ └── Main.hs
├── src
│ └── Lib.hs
├── test
│ └── Spec.hs
├── my-project.cabal
├── package.yaml
└── stack.yaml
The Haskell source code for the executable (application) is in file Main.hs
.
The executable uses a library. Its source code is in file Lib.hs
.
The contents of my-project.cabal
describes the project's package. That file is
generated by the contents of package.yaml
.
Info
If you want, you can delete the package.yaml
file and update the
my-project.cabal
file directly. Stack will then use that file.
The contents of stack.yaml
describe Stack's own project-level configuration.
You can edit the source files in the src
directory (used for the library) or
the app
directory (used for the executable (application)).
As your project develops, you may need to depend on a library provided by
another Haskell package. If you do, then add the name of that new package to the
file package.yaml
, in its dependencies:
section.
Info
When you use stack build
again, Stack will use package.yaml
to create an
updated my-project.cabal
for you.
If Stack reports that the Stack configuration has no specified version for the
new package, then follow Stack's likely recommended action to add a specific
version of that package your project's stack.yaml
file, in its 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 read Stack's introductory user's guide.
Complete guide to Stack¶
A complete user's guide to Stack is available, covering all of the most common ways to use Stack. Terms used in Stack's documentation are also explained in the glossary.
Why Stack?¶
Stack is a build tool for Haskell designed to answer the needs of Haskell users, both new and experienced. It has a strong focus on reproducible build plans, multi-package projects, and a consistent, easy-to-learn set of Stack commands. It also aims to provide the customizability and power that experienced developers need.
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 version of GHC for your project.
-
The Cabal build system. Cabal is a specification for defining Haskell packages and a library for performing builds.
Info
Cabal is also the name of another build tool, provided by the
cabal-install
package. This guide distinguishes between them by Cabal (the library) and Cabal (the tool). -
The Hackage Haskell Package Repository, a repository of Haskell packages providing thousands of open source libraries and applications to help you get your work done.
- The Stackage package collection, sets of packages from Hackage that are curated. That is, they are regularly tested for compatibility. Stack defaults to using Stackage package sets to avoid problems with incompatible dependencies.
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. It 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.
Questions, feedback, and discussion¶
- For answers to frequently asked questions about Stack, please see the FAQ.
- For general questions, comments, feedback and support, please post to the Haskell Community.
- For bugs, issues, or requests, please open an issue.
- When using Stack Overflow, please use the haskell-stack tag.
How to contribute to the maintenance or development of Stack¶
The following assumes that you already have installed a version of Stack and the Git application.
-
Clone the
stack
repository from GitHub with the command: -
Change the current working directory to the cloned
stack
directory with the command: -
Build the
stack
executable using a preexisting installation of Stack with the command: -
Once the
stack
executable has been built, check its version with the command:Make sure the version is the latest one.
-
In the GitHub repository's issue tracker, look for issues tagged with newcomer friendly and awaiting pull request labels.
If you need to check your changes quickly command:
and then, at the REPL's prompt, command:
This allows you to set a special Stack root (instead of the default Stack root)
and to target your commands at a particular stack.yaml
file instead of the one
found in the current directory.
How to uninstall¶
To uninstall Stack, it should be sufficient to delete:
- the Stack root folder (see
stack path --stack-root
, before you uninstall); - on Windows, the folder containing Stack's tools (see
stack path --programs
, before you uninstall), which is located outside of the Stack root folder; and - the
stack
executable file (seewhich stack
, on Unix-like operating systems, orwhere.exe stack
, on Windows).
You may also want to delete .stack-work
folders in any Haskell projects that
you have built using Stack. The stack uninstall
command provides information
about how to uninstall Stack.