Difference between new-template.cabal and stack.yaml

Question

I want to use reactive-banana in my new Haskell project. I never used cabal-install or stack before. I created a directory and initialized project files in it using stack new. I see now 2 files in the directory: new-template.cabal and stack.yaml.

How do I set dependencies and make sure they are downloaded and compiled?

At first I tried to add - reactive-banana-0.8.0.2 in stack.yaml under extra-deps:, but both stack build and stack solver didn't download it. Then I augmented a part called library in new-template.cabal to this:

library
  hs-source-dirs:      src
  exposed-modules:     Lib
  build-depends:       base >= 4.7 && < 5
                     , reactive-banana >= 0.8
  default-language:    Haskell2010

Every time I tried to run stack build, it crashed with an error and suggestion to add some package to stack.yaml under extra-deps:, and this happened three times until finally all packages installed, and I could import them in stack ghci REPL.

So my question is, what is the idiomatic way to use stack? Which of these 2 files should I use to specify dependencies and other project metadata? What is the sample workflow of an average Haskell developer with stack?

Answer 1

When using stack I generally don't put any versions bounds in my .cabal file. I let the resolver and extra-deps setting in the stack.yaml file determine which versions of packages to select.

Here is a stack.yaml file which brings in reactive-banana-0.8.1.2:

flags: {}
packages:
- '.'
extra-deps:
- reactive-banana-0.8.1.2
- psqueues-0.2.0.2
resolver: lts-2.17

In my .cabal file I just have:

  build-depends:       base >= 4.7 && < 5, reactive-banana

The reactive-banana version is pinned by the stack.yaml file.

If you want to use GHC 7.10 change the resolver to something like nightly-2015-06-17.

I determine the extra-deps iteratively, by just running stack build and adding whatever dependencies are missing to the stack.yaml file until all dependencies are satisfied.

You will only need to do this with packages which are not in Stackage - like reactive-banana. A great many of commonly used packages are in Stackage and their versions will be determined by the resolver setting.