Skip to content

Latest commit

 

History

History
 
 

doc

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
azure
azure
 
 
css
css
 
 
img
img
 
 
js
js
 
 
maintainers
maintainers
 
 
CONTRIBUTING.md
CONTRIBUTING.md
 
 
ChangeLog.md
ChangeLog.md
 
 
GUIDE.md
GUIDE.md
 
 
GUIDE_advanced.md
GUIDE_advanced.md
 
 
README.md
README.md
 
 
SIGNING_KEY.md
SIGNING_KEY.md
 
 
Stack_and_VS_Code.md
Stack_and_VS_Code.md
 
 
appveyor.yml
appveyor.yml
 
 
azure_ci.md
azure_ci.md
 
 
build_command.md
build_command.md
 
 
build_overview.md
build_overview.md
 
 
coverage.md
coverage.md
 
 
custom_snapshot.md
custom_snapshot.md
 
 
dependency_visualization.md
dependency_visualization.md
 
 
developing_on_windows.md
developing_on_windows.md
 
 
docker_integration.md
docker_integration.md
 
 
faq.md
faq.md
 
 
ghci.md
ghci.md
 
 
ghcjs.md
ghcjs.md
 
 
glossary.md
glossary.md
 
 
install_and_upgrade.md
install_and_upgrade.md
 
 
lock_files.md
lock_files.md
 
 
nix_integration.md
nix_integration.md
 
 
nonstandard_project_init.md
nonstandard_project_init.md
 
 
pantry.md
pantry.md
 
 
requirements.txt
requirements.txt
 
 
shell_autocompletion.md
shell_autocompletion.md
 
 
stack_yaml_vs_cabal_package_file.md
stack_yaml_vs_cabal_package_file.md
 
 
travis-complex.yml
travis-complex.yml
 
 
travis-simple.yml
travis-simple.yml
 
 
travis_ci.md
travis_ci.md
 
 
yaml_configuration.md
yaml_configuration.md
 
 

README.md

The Haskell Tool Stack

Stack is a cross-platform program for developing Haskell projects. It is aimed at Haskellers both new and experienced. It 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 on Windows.

For most Unix-like operating systems, the easiest way to install Stack is to run:

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

or:

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

On 64-bit Windows, you can download and install the Windows installer. Note that systems with antivirus software may need to add Stack to the list of 'trusted' applications.

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

The get.haskellstack.org script referred to above 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.

How to upgrade Stack

If you already have Stack installed, you can upgrade it to the latest version by the command:

stack upgrade

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.

Start your new project

To start a new project named my-project, issue these four commands in a terminal:

stack new my-project
cd my-project
stack build
stack exec my-project-exe
  • The stack new my-project command will create a new directory, named my-project, that contains all the files needed to start a project correctly, using a default template.
  • The cd my-project command will change to that directory.
  • The stack build command will build the template project and create an executable named my-project-exe. First, if necessary, Stack will download the necessary GHC compiler in an isolated location. That won't interfere with any system-level installations of GHC.
  • 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:

stack

For help on a particular Stack command, for example stack build, command:

stack build --help

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

stack ghci

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>

Workflow

The stack new my-project command above should have created the following files and directories:

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

(The stack build command will have created other directories and files.)

The Haskell code for the executable/application is in Main.hs. The source code for the library that it uses is in Lib.hs. The contents of my-project.cabal describes the project. That file is generated by the contents of package.yaml.

To manage your library:

  1. Edit source files in the src directory. The app directory should preferably contain only files related to executables.

  2. Your developing project may need to depend on a library provided by another Haskell package.

    • Add the name of that new package to the file package.yaml, in its dependencies: section.
    • Run stack build again. Stack will use package.yaml to create an updated my-project.cabal for you.

  3. If desired, you can delete the package.yaml file and update the my-project.cabal file directly. Stack will then use that file.

  4. If you get an error message that tells you that the Stack configuration has no specified version of your added package, follow Stack's likely recommandation to add a specific version of that package in the 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 the Stack User Guide.

Complete guide to Stack

A complete user 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 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 Haskell Package Repository, a repository providing thousands of 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.

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.

  1. Clone the stack repository from GitHub with the command: git clone https://github.com/commercialhaskell/stack.git.
  2. Enter into the cloned stack directory with command cd stack.
  3. Build the stack executable using a pre-existing installation of Stack with command stack build.
  4. Once the stack executable has been built, check its version with the command stack exec -- stack --version. Make sure the version is the latest.
  5. In the GitHub respository's issue tracker, look for issues tagged with newcomer friendly and awaiting pull request labels.

If you need to check your changes quickly run stack ghci and then this command at the REPL's prompt:

:main --stack-root=<path_to_root> --stack-yaml=<path_to_stack.yaml> <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:

  1. the Stack root folder (see stack path --stack-root, before you uninstall);
  2. 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
  3. 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 folders in any Haskell projects that you have built using Stack. The stack uninstall command provides information about how to uninstall Stack.