@hackage hpack0.16.0

An alternative format for Haskell packages

hpack: An alternative format for Haskell packages

Examples

Documentation

Getting started

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

Quick-reference

Top-level fields

Hpack Cabal Default Notes Example
name name
version version 0.0.0
synopsis synopsis
description description
category category
stability stability
homepage homepage If github given, <repo>#readme
bug-reports bug-reports If github given, <repo>/issues
author author May be a list
maintainer maintainer May be a list
copyright copyright May be a list
license license
license-file license-file LICENSE if file exists
tested-with tested-with
build-type build-type Simple Must be Simple, Configure, Make, or Custom
cabal-version >= 1.10 or >= 1.21 >= 1.21 if library component has reexported-modules field
extra-source-files extra-source-files Accepts glob patterns
data-files data-files Accepts glob patterns
github source-repository head Accepts user/repo or user/repo/subdir github: foo/bar
git source-repository head No effect if github given git: https://my.repo.com/foo
flags flag <name> Map from flag name to flag (see Flags)
library library See Library fields
executables executable <name> Map from executable name to executable (see Executable fields)
tests test-suite <name> Map from test name to test (see Test fields)
benchmarks benchmark <name> Map from benchmark name to benchmark (see Benchmark fields)

Global top-level fields

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

Hpack Cabal Default Notes
source-dirs hs-source-dirs
default-extensions default-extensions
other-extension other-extensions
ghc-options ghc-options
ghc-prof-options ghc-prof-options
cpp-options cpp-options
cc-options cc-options
c-sources c-sources
extra-lib-dirs extra-lib-dirs
extra-libraries extra-libraries
include-dirs include-dirs
install-includes install-includes
ld-options ld-options
buildable buildable May be overridden by later stanza
dependencies build-depends
build-tools build-tools
when Accepts a list of conditionals (see Conditionals)

Library fields

Hpack Cabal Default Notes
exposed exposed
exposed-modules exposed-modules All modules in source-dirs less other-modules
other-modules other-modules All modules in source-dirs less exposed-modules
reexported-modules reexported-modules
default-language Haskell2010

Executable fields

Hpack Cabal Default Notes
main main-is
other-modules other-modules
default-language Haskell2010

Test fields

Hpack Cabal Default Notes
type exitcode-stdio-1.0
main main-is
other-modules other-modules
default-language Haskell2010

Benchmark fields

Hpack Cabal Default Notes
type exitcode-stdio-1.0
main main-is
other-modules other-modules
default-language Haskell2010

Flags

Hpack Cabal Default Notes
description description Optional
manual manual Required (unlike Cabal)
default default Required (unlike Cabal)

Conditionals

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

File globbing

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

Slides

Vim integration

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

autocmd BufWritePost package.yaml silent !hpack --silent