18

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?

Shersh
  • 9,019
  • 3
  • 33
  • 61
luochen1990
  • 3,689
  • 1
  • 22
  • 37

1 Answers1

19

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.

Shersh
  • 9,019
  • 3
  • 33
  • 61
  • 1
    Great answer. One extra source of info on stack.yaml vs package.yaml: https://docs.haskellstack.org/en/stable/stack_yaml_vs_cabal_package_file/ – Michael Snoyman Jun 16 '18 at 21:14
  • @Shersh, do you have any more examples of the usage of `Setup.hs`? We also use proto-lens and that sounds like a great way to use it, but I'm still not 100% sure what you put in that file/how it generates modules, etc. – jkeuhlen Jun 18 '18 at 14:40
  • 2
    @jkeuhlen You can see usage example in this GitHub repository: https://github.com/holmusk/three-layer – Shersh Jun 19 '18 at 01:51