The Hpack package format is based on YAML. Packages are described in a file named package.yaml.

Hpack is designed to remove redundancies from your package descriptions.

There is reference documentation below, but introductory documentation is still lacking. For the time being, take a look at the slides from my talk about Hpack at the Singapore Haskell meetup: http://typeful.net/talks/hpack

• Given this package.yaml running hpack will generate hpack.cabal
• Given this package.yaml running hpack will generate getopt-generics.cabal
• Given this package.yaml running hpack will generate sensei.cabal
• Given this package.yaml running hpack will generate base-orphans.cabal

One easy way of getting started is to use hpack-convert to convert an existing cabal file into a package.yaml.

These fields are merged with all library, executable, test, and benchmark components.

Conditionals with no else branch:

• Must have a condition field
• May have any number of other fields

For example,

when:
  - condition: os(darwin)
    extra-lib-dirs: lib/darwin

becomes

if os(darwin)
  extra-lib-dirs:
    lib/darwin

Conditionals with an else branch:

• Must have a condition field
• Must have a then field, itself an object containing any number of other fields
• Must have a else field, itself an object containing any number of other fields
• All other top-level fields are ignored

For example,

when:
  - condition: flag(fast)
    then:
      ghc-options: -O2
    else:
      ghc-options: -O0

becomes

if flag(fast)
  ghc-options: -O2
else
  ghc-options: -O0

At place where you can specify a list of files you can also use glob patterns. Glob patters and ordinary file names can be freely mixed, e.g.:

extra-source-files:
  - static/*.js
  - static/site.css

Glob patterns are expanded according to the following rules:

• ? and * are expanded according to POSIX (they match arbitrary characters, except for directory separators)
• ** is expanded in a zsh-like fashion (matching across directory separators)
• ?, * and ** do not match a . at the beginning of a file/directory

It is possible to use YAML anchors (&), aliases (*) and merge keys (<<) to define fields and reference them later.

executables:
  my-exe-1: &my-exe
    main: my-exe-1.hs
    dependencies: [base, my-lib]
    ghc-options: [-threaded]
  my-exe-2:
    <<: *my-exe
    main: my-exe-2.hs

Warnings for unknown fields will not be emitted for top-level fields starting with an underscore, so you can declare global aliases too:

_exe-ghc-options: &exe-ghc-options
  - -threaded
  - -rtsopts

executables:
  my-exe-1:
    ghc-options: *exe-ghc-options

It is also possible to use the !include directive:

# ...

tests:
  hlint: !include "../common/hlint.yaml"

hlint.yaml:

source-dirs: test
main: hlint.hs
dependencies: [base, hlint]

This can also be used to provide entire libraries of snippets:

_common/lib: !include "../common/lib.yaml"

name: example1
version: '0.1.0.0'
synopsis: Example
<<: *legal

<<: *defaults

library:
  source-dirs: src

tests:
  hlint: *test_hlint

lib.yaml:

- &legal
  maintainer: Some One <[email protected]>
  copyright: (c) 2017 Some One
  license: BSD3

- &defaults
  dependencies:
    - base
    - containers
  ghc-options:
    - -Wall
    - -Werror

- &test_hlint
  source-dirs: test
  main: hlint.hs
  dependencies: [hlint]

To run hpack automatically on modifications to package.yaml add the following to your ~/.vimrc:

autocmd BufWritePost package.yaml silent !hpack --silent

Stack has built-in support for Hpack. If you are using Stack you can use package.yaml instead of a .cabal file. No additional steps are required.