2013-06-03
Actually two components:
Cabal
package, bundled with GHC)cabal
(cabal-install
package)GHC uses Cabal
mostly for parsing CABAL package descriptions (→ ghc-pkg
)
Lexicographic ordering applied: e.g. 2.1 > 1.3 and 2.1.1 > 2.1
An API breaking change requires a major version increment;
(Non-breaking) API additions require a minor version increment;
For other non-semantic changes "x.y.…" shall be incremented
If the PVP is followed, this allows a packages to be compatible with a certain range of newer package versions.
Recommended practice: use qualified or explicit imports, e.g.
import qualified Data.Text as T
import Data.Text.Encoding (decodeLatin1) -- 0.11.3+
This way, the text
dependency can be safely declared as
build-depends: text >=0.11.3 && <0.12
If it turns out, that a future text-0.12.0
won't break anything relevant to us, we can bump the upper limit to <0.13
(→ versioning avalanche hazard!)
cabal
toolcabal update
update package index
cabal install cool-package
cool-package
based on package indexcool-package
+ missing dependenciescool-package
ghc-pkg list
):
Install paths can be customized via ~/.cabal/config
~/.cabal
~/.cabal/bin/
installed executable(s) (add to $PATH
!)~/.cabal/lib/
contains compiled and .hi
interface files~/.cabal/share/
contains package data and Haddock docs~/.ghc/
contains (user-wide) package registry
ghc-pkg list --user
world-file
defined in ~/.cabal/config
cabal
collects all packages installed in world-file
world
package: cabal install world
cabal
doesn't keep track (yet) of executable-only packages
cabal install alex
will install alex
over and over againbuild-depends
on executable-only packages!cabal
cab
provides cab unregister --recursive
~/.ghc/
~/.ghc/
~/.cabal/{lib,logs,share}/
Create your project, e.g. like
./src/Data/Objects.hs
./src/Data/Objects/Internal.hs
…
Just run cabal init
, answer the questions, and if lucky you'll get a working <pkg-name>.cabal
file
A .cabal
file starts with top-level meta infos about the package.
library
target andexecutable
/test-suite
/benchmark
targets.main-is
/exposed-modules
/other-modules
or elsecabal sdist
will fail to include them..cabal
allows to define configuration flags:
#ifdef
s or including/excluding modules as a whole from compilation)build-depends
(not recommended if avoidable)cabal
will backtrack through (non-manual) flagscabal configure --flags="debug -usebytestring"
cabal install --only-dep(endencies)
installs build dependencies
configure
below!cabal configure
sets up the buildcabal build [<target>]
builds/compiles the given target (or all)
dist/build/<target>/
cabal haddock
builds Haddock documentation in dist/doc/
cabal clean -s
removes effects from cabal build
/cabal haddock
-s
is short for --save-configure
cabal install
w/o the --only-dep
builds & installs from source
cabal {install --only-dep, configure, build, haddock}
~/.cabal
and registering with ghc-pkg
cabal install
after cabal configure
resets configuration!cabal sandbox
cabal-install
<1.17: use cabal-dev
cabal-install
≥1.17: use built-in sandbox
supportcabal sandbox
How to install latest cabal-install
snapshot:
cd /tmp
git clone git://github.com/haskell/cabal.git
(cd cabal/Cabal && cabal install)
(cd cabal/cabal-install && cabal install)
rm -rf /tmp/cabal
New cabal
executable should be at ~/.cabal/bin/cabal
New feature: Per-project ./cabal.config
overrides ~/.cabal/config
cabal sandbox
Quick usage primer:
cabal sandbox init
cabal {configure,build,install,…}
cabal sandbox delete
Sandbox mode enabled if ./cabal.sandbox.config
present
cabal sandbox
Augment sandbox-local view of Hackage package index:
cabal sandbox add-source [--snapshot] <source-folder>
cabal sandbox list-sources
cabal sandbox delete-source <list-source-folder>
add-source
injects the given package into the package index, and makes it available for
cabal info
cabal list
cabal configure
cabal install
cabal sandbox
For operating on the sandboxed GHC package registry (i.e. ghc-pkg {list,…}
):
cabal sandbox hc-pkg …
cabal sandbox
is still work-in-progress and you can report issues!
Stay tuned for cabal ghci
support
Variant of executable
targets, with additional field
type: exitcode-stdio-1.0
Tests & benchmarks need to generate report somewhere to be useful
Enable via cabal configure --enable-tests --enable-benchmarks
(optional with bleeding edge cabal-install
)
Run via cabal test
or cabal bench
and pass options via --{test,benchmark}-options="…"
criterion
-based benchmarks are perfectly fine for use with cabal benchmark
cabal bench bench1 --benchmark-options="-o bench1-report.html --junit bench1.xml"
test-framework
integrates testing libraries:
test-framework-golden
test-framework-hunit
test-framework-quickcheck2
test-framework-smallcheck
snap-core
's CI)Configure with
cabal configure --enable-tests --enable-library-coverage
Now cabal test
will produce coverage reports via hpc
Currently semi-broken (can be workarounded):
Warning: Your version of HPC (0.6) does not properly handle multiple search paths. Coverage report generation may fail unexpectedly. These issues are addressed in version 0.7 or later (GHC 7.8 or later).