What is package.yaml & stack.yaml & Setup.hs & the-project-name.cabal files?

Question

I find that, when I use the stack new the-project-name new-template command, many files is generated into a new directory. and I notice the following 4 special files:

package.yaml
stack.yaml
Setup.hs
the-project-name.cabal

These 4 files seems intending to provide meta data for package-managing software, but they looks confusing, I mean, why there are 4 of them, why not just one, and what's the difference between them?

Answer 1

Those configuration files serve different purposes. It's not clear what is better: have single all-inclusive configuration file or different files for different build tools and different goals.

the-project-name.cabal

This file contains description of your package. Like, list of modules, library dependencies, compiler options, project metadata (author's name, package version, etc.). This description is specified in special for cabal format.

package.yaml

This configuration file is used by hpack tool. It allows to specify the same things you specify in .cabal file. But in YAML format instead of custom cabal format. Also it adds some features over cabal. If you don't want to dive into hpack for now you can safely delete package.yaml file. Note, that .cabal file is generated by hpack from package.yaml file so you mustn't edit .cabal file if you're using hpack.

stack.yaml

Configuration for stack build tool. Add some extra configuration parameters. Most important: name of the LTS resolver.

Setup.hs

Used to add some build-hooks. In almost all cases you can delete this file as well. But I can give you real-life usage example of this file from our work.

We're writing service where different nodes should communicate using Protocol Buffers format. TL;DR pretty good format for describing message specifications. Those messages are written in files with extension .proto. But we actually want to work with Haskell types. There exist library proto-lens which can take files written in Protocol Buffers format, parse those files and generate Haskell modules containing data types representing those messages. This file generation should be done before project compilation. So this process is described in Setup.hs file.