Transition guide

This page has mostly been superseded by the stack guide. We may remove this content in the future, but it is kept for now.

The FAQ may be helpful for general questions. This is intended to help people familiar with using other Haskell build tools- like cabal-install, hsenv, etc- with getting started with stack. The goal of stack is to be easy to use, so hopefully there won't be any gotchas. In our experience so far, most of the confusion comes from things you don't need to do in stack. For example:

• There's no need for explicit sandboxing, all builds in stack are isolated automatically
• The install command doesn't exist. Dependencies are built for you automatically, and your packages are always registered into a local package database

From cabal-install to stack

If you already have a working cabal build, it is a good idea to perform a cabal freeze if you have not already. If you need some packages outside of the snapshot you are using (to be placed in the extra-deps field), the cabal.config file generated by the freeze can be a good place to look for exact versions.

Shared databases, not sandboxes

Since sandboxing is such a common feature in the rest of the Haskell build tool world (hsenv, cabal, cabal-dev), it may be surprising to see so little mention of it in this document. That's because the goal of sandboxing- isolating builds- is the default in stack. There are two different aspects of a build that warrant some kind of isolation:

• The package database, containing information on the compiled libraries
• The bin directory, containing generated executables

Whenever you build with stack, there are three of each at play:

• GHC's bin directory and global package database
• The snapshot's (e.g., lts-2.9)
• Your project

These are layered so that they shadow the previous ones. If you use extra-deps to install a new version of text in your project, for example, that will override whatever is installed in your snapshot. If you install a newer version of the xhtml library via your snapshot, it will shadow the xhtml that ships with GHC.

The one important difference to note versus how GHC typically behaves is that we don't make use of the "user package database" at all. This is to properly enforce isolation. If you wish to use tools like ghc or runhaskell, you should do so via stack ghc or stack exec.

The Architecture page goes into much more detail on this.

running an executable.

There is no stack run that does what cabal run does, but stack build && stack exec foo (or stack build && stack runghc app/Main.hs) accomplishes the same thing.

I prefer dependency solving to curation

stack can handle that workflow. There's a Reddit answer going into more detail, but basically:

• stack has explicit dependency solving
• When we want to kick off solving, run stack init --solver --force
• No dependency solving will occur until you next run that command

When should I use install

The install command- unlike cabal- is only used for copying executables to a generally available directory. Download, building, and registering dependencies is handled via the build command for you automatically. The idea is to be as declarative as possible: state your package dependencies in your .cabal file and stack.yaml as appropriate, and they'll be built for you as needed.

How do I force stack to use GHC-X.Y

Your stack.yaml specifies a resolver value, that states how dependencies are resolved and which version of the compiler to use. When generating with stack init, it will generally prefer an LTS Haskell release when possible (though you can control this with command line parameters). Each LTS Haskell and Stackage Nightly comes with a specific GHC version. In order to switch to a different GHC, you generally want to:

1. Modify the resolver value to an appropriate value for the GHC version you want (e.g., move from lts-2.22 to lts-3.0 to move from GHC 7.8.4 to GHC 7.10.2)
2. Run stack setup to download/locally install the necessary GHC version