Skip to content

14. Stack configuration

Whenever you run something with Stack, it needs a project-level configuration file. The algorithm Stack uses to find such a file is:

  1. Check for a --stack-yaml option on the command line
  2. Check for a STACK_YAML environment variable
  3. Check the current directory and all ancestor directories for a stack.yaml file

The first two provide a convenient method for using an alternate configuration. For example: stack build --stack-yaml stack-ghc-9.2.3.yaml can be used by your CI system to check your code against GHC 9.2.3. Setting the STACK_YAML environment variable can be convenient if you're going to be running commands like stack ghc in other directories, but you want to use the configuration you defined in a specific project.

If Stack does not find a project level configuration file in any of the three specified locations, the implicit global logic kicks in. You've probably noticed that phrase a few times in the output from commands above. Implicit global is essentially a hack to allow Stack to be useful in a non-project setting. When no implicit global configuration file exists, Stack creates one for you with the latest LTS snapshot. This allows you to do things like:

  • compile individual files easily with stack ghc
  • build executables without starting a project, e.g. stack install pandoc

Keep in mind that there's nothing magical about this implicit global configuration. It has no effect on projects at all. Every package you install with it is put into isolated databases just like everywhere else. The only magic is that it's the catch-all project whenever you're running Stack somewhere else.

Package description vs project-level configuration

Now that we've covered a lot of ways to use Stack, this quick summary of package description files versus Stack's project-level configuration file will hopefully make sense and be a good reminder for future uses of Stack:

  • Package description

    Each package has a package description file in the Cabal format (a Cabal file named after the package.

    A package may have a package description file in the Hpack format (package.yaml). If one exists, Stack will use it to generate the Cabal file.

    Specifies which other Haskell packages are dependencies of the package.

    Specifies the components, modules, and Cabal flags provided by the package.

  • Project-level configuration

    Each project has a project-level configuration file (named stack.yaml, by default).

    A project can have one or more project packages.

    Specifies which package versions are available to be used.

    Can override the Cabal flag settings for individual packages.