Cabal- A framework for packaging Haskell software

CopyrightIsaac Jones 2003-2005
Safe HaskellNone




This defines the data structure for the .cabal file format. There are several parts to this structure. It has top level info and then Library, Executable, TestSuite, and Benchmark sections each of which have associated BuildInfo data that's used to build the library, exe, test, or benchmark. To further complicate things there is both a PackageDescription and a GenericPackageDescription. This distinction relates to cabal configurations. When we initially read a .cabal file we get a GenericPackageDescription which has all the conditional sections. Before actually building a package we have to decide on each conditional. Once we've done that we get a PackageDescription. It was done this way initially to avoid breaking too much stuff when the feature was introduced. It could probably do with being rationalised at some point to make it simpler.


Package descriptions

data PackageDescription

This data type is the internal representation of the file pkg.cabal. It contains two kinds of information about the package: information which is needed for all packages, such as the package name and version, and information which is needed for the simple build system only, such as the compiler options and library name.




package :: PackageIdentifier
license :: License
licenseFiles :: [FilePath]
copyright :: String
maintainer :: String
author :: String
stability :: String
testedWith :: [(CompilerFlavor, VersionRange)]
homepage :: String
pkgUrl :: String
bugReports :: String
sourceRepos :: [SourceRepo]
synopsis :: String

A one-line summary of this package

description :: String

A more verbose description of this package

category :: String
customFieldsPD :: [(String, String)]

Custom fields starting with x-, stored in a simple assoc-list.

buildDepends :: [Dependency]

YOU PROBABLY DON'T WANT TO USE THIS FIELD. This field is special! Depending on how far along processing the PackageDescription we are, the contents of this field are either nonsense, or the collected dependencies of *all* the components in this package. buildDepends is initialized by finalizePackageDescription and flattenPackageDescription; prior to that, dependency info is stored in the CondTree built around a GenericPackageDescription. When this resolution is done, dependency info is written to the inner BuildInfo and this field. This is all horrible, and #2066 tracks progress to get rid of this field.

specVersionRaw :: Either Version VersionRange

The version of the Cabal spec that this package description uses. For historical reasons this is specified with a version range but only ranges of the form >= v make sense. We are in the process of transitioning to specifying just a single version, not a range.

buildType :: Maybe BuildType
setupBuildInfo :: Maybe SetupBuildInfo
library :: Maybe Library
executables :: [Executable]
testSuites :: [TestSuite]
benchmarks :: [Benchmark]
dataFiles :: [FilePath]
dataDir :: FilePath
extraSrcFiles :: [FilePath]
extraTmpFiles :: [FilePath]
extraDocFiles :: [FilePath]

specVersion :: PackageDescription -> Version

The version of the Cabal spec that this package should be interpreted against.

Historically we used a version range but we are switching to using a single version. Currently we accept either. This function converts into a single version by ignoring upper bounds in the version range.

descCabalVersion :: PackageDescription -> VersionRange

Deprecated: Use specVersion instead

The range of versions of the Cabal tools that this package is intended to work with.

This function is deprecated and should not be used for new purposes, only to support old packages that rely on the old interpretation.

data BuildType

The type of build system used by this package.



calls Distribution.Simple.defaultMain


calls Distribution.Simple.defaultMainWithHooks defaultUserHooks, which invokes configure to generate additional build information used by later phases.


calls Distribution.Make.defaultMain


uses user-supplied Setup.hs or Setup.lhs (default)

UnknownBuildType String

a package that uses an unknown build type cannot actually be built. Doing it this way rather than just giving a parse error means we get better error messages and allows you to inspect the rest of the package description.


Eq BuildType 
Data BuildType 
Read BuildType 
Show BuildType 
Generic BuildType 
Binary BuildType 
Text BuildType 
type Rep BuildType 


data ModuleRenaming

Renaming applied to the modules provided by a package. The boolean indicates whether or not to also include all of the original names of modules. Thus, ModuleRenaming False [] is "don't expose any modules, and ModuleRenaming True [(Data.Bool, Bool)] is, "expose all modules, but also expose Data.Bool as Bool".


ModuleRenaming Bool [(ModuleName, ModuleName)] 


data Library




exposedModules :: [ModuleName]
reexportedModules :: [ModuleReexport]
requiredSignatures :: [ModuleName]

What sigs need implementations?

exposedSignatures :: [ModuleName]

What sigs are visible to users?

libExposed :: Bool

Is the lib to be exposed by default?

libBuildInfo :: BuildInfo


Eq Library 
Data Library 
Read Library 
Show Library 
Generic Library 
Monoid Library 
Binary Library 
Semigroup Library 
type Rep Library 

withLib :: PackageDescription -> (Library -> IO ()) -> IO ()

If the package description has a library section, call the given function with the library build info as argument.

hasLibs :: PackageDescription -> Bool

does this package have any libraries?

libModules :: Library -> [ModuleName]

Get all the module names from the library (exposed and internal modules) which need to be compiled. (This does not include reexports, which do not need to be compiled.)


data Executable




exeName :: String
modulePath :: FilePath
buildInfo :: BuildInfo


withExe :: PackageDescription -> (Executable -> IO ()) -> IO ()

Perform the action on each buildable Executable in the package description.

hasExes :: PackageDescription -> Bool

does this package have any executables?

exeModules :: Executable -> [ModuleName]

Get all the module names from an exe


data TestSuite

A "test-suite" stanza in a cabal file.




data TestSuiteInterface

The test suite interfaces that are currently defined. Each test suite must specify which interface it supports.

More interfaces may be defined in future, either new revisions or totally new interfaces.


TestSuiteExeV10 Version FilePath

Test interface "exitcode-stdio-1.0". The test-suite takes the form of an executable. It returns a zero exit code for success, non-zero for failure. The stdout and stderr channels may be logged. It takes no command line parameters and nothing on stdin.

TestSuiteLibV09 Version ModuleName

Test interface "detailed-0.9". The test-suite takes the form of a library containing a designated module that exports "tests :: [Test]".

TestSuiteUnsupported TestType

A test suite that does not conform to one of the above interfaces for the given reason (e.g. unknown test type).

data TestType

The "test-type" field in the test suite stanza.


TestTypeExe Version

"type: exitcode-stdio-x.y"

TestTypeLib Version

"type: detailed-x.y"

TestTypeUnknown String Version

Some unknown test type e.g. "type: foo"


Eq TestType 
Data TestType 
Read TestType 
Show TestType 
Generic TestType 
Binary TestType 
Text TestType 
type Rep TestType 

hasTests :: PackageDescription -> Bool

Does this package have any test suites?

withTest :: PackageDescription -> (TestSuite -> IO ()) -> IO ()

Perform an action on each buildable TestSuite in a package.

testModules :: TestSuite -> [ModuleName]

Get all the module names from a test suite.

enabledTests :: PackageDescription -> [TestSuite]

Get all the enabled test suites from a package.


data Benchmark

A "benchmark" stanza in a cabal file.


data BenchmarkInterface

The benchmark interfaces that are currently defined. Each benchmark must specify which interface it supports.

More interfaces may be defined in future, either new revisions or totally new interfaces.


BenchmarkExeV10 Version FilePath

Benchmark interface "exitcode-stdio-1.0". The benchmark takes the form of an executable. It returns a zero exit code for success, non-zero for failure. The stdout and stderr channels may be logged. It takes no command line parameters and nothing on stdin.

BenchmarkUnsupported BenchmarkType

A benchmark that does not conform to one of the above interfaces for the given reason (e.g. unknown benchmark type).

data BenchmarkType

The "benchmark-type" field in the benchmark stanza.


BenchmarkTypeExe Version

"type: exitcode-stdio-x.y"

BenchmarkTypeUnknown String Version

Some unknown benchmark type e.g. "type: foo"

hasBenchmarks :: PackageDescription -> Bool

Does this package have any benchmarks?

withBenchmark :: PackageDescription -> (Benchmark -> IO ()) -> IO ()

Perform an action on each buildable Benchmark in a package.

benchmarkModules :: Benchmark -> [ModuleName]

Get all the module names from a benchmark.

enabledBenchmarks :: PackageDescription -> [Benchmark]

Get all the enabled benchmarks from a package.

Build information

data BuildInfo




buildable :: Bool

component is buildable here

buildTools :: [Dependency]

tools needed to build this bit

cppOptions :: [String]

options for pre-processing Haskell code

ccOptions :: [String]

options for C compiler

ldOptions :: [String]

options for linker

pkgconfigDepends :: [Dependency]

pkg-config packages that are used

frameworks :: [String]

support frameworks for Mac OS X

extraFrameworkDirs :: [String]

extra locations to find frameworks.

cSources :: [FilePath]
jsSources :: [FilePath]
hsSourceDirs :: [FilePath]

where to look for the Haskell module hierarchy

otherModules :: [ModuleName]

non-exposed or non-main modules

defaultLanguage :: Maybe Language

language used when not explicitly specified

otherLanguages :: [Language]

other languages used within the package

defaultExtensions :: [Extension]

language extensions used by all modules

otherExtensions :: [Extension]

other language extensions used within the package

oldExtensions :: [Extension]

the old extensions field, treated same as defaultExtensions

extraLibs :: [String]

what libraries to link with when compiling a program that uses your package

extraGHCiLibs :: [String]

if present, overrides extraLibs when package is loaded with GHCi.

extraLibDirs :: [String]
includeDirs :: [FilePath]

directories to find .h files

includes :: [FilePath]

The .h files to be found in includeDirs

installIncludes :: [FilePath]

.h files to install with the package

options :: [(CompilerFlavor, [String])]
profOptions :: [(CompilerFlavor, [String])]
sharedOptions :: [(CompilerFlavor, [String])]
customFieldsBI :: [(String, String)]

Custom fields starting with x-, stored in a simple assoc-list.

targetBuildDepends :: [Dependency]

Dependencies specific to a library or executable target

targetBuildRenaming :: Map PackageName ModuleRenaming


allBuildInfo :: PackageDescription -> [BuildInfo]

The BuildInfo for the library (if there is one and it's buildable), and all buildable executables, test suites and benchmarks. Useful for gathering dependencies.

allLanguages :: BuildInfo -> [Language]

The Languages used by this component

allExtensions :: BuildInfo -> [Extension]

The Extensions that are used somewhere by this component

usedExtensions :: BuildInfo -> [Extension]

The Extensions that are used by all modules in this component

hcOptions :: CompilerFlavor -> BuildInfo -> [String]

Select options for a particular Haskell compiler.

Supplementary build information

type HookedBuildInfo = (Maybe BuildInfo, [(String, BuildInfo)])

package configuration

data Flag

A flag can represent a feature to be included, or a way of linking a target against its dependencies, or in fact whatever you can think of.




flagName :: FlagName
flagDescription :: String
flagDefault :: Bool
flagManual :: Bool


Eq Flag 
Data Flag 
Show Flag 
Generic Flag 
Binary Flag 
type Rep Flag 

newtype FlagName

A FlagName is the name of a user-defined configuration flag


FlagName String 


Eq FlagName 
Data FlagName 
Ord FlagName 
Read FlagName 
Show FlagName 
Generic FlagName 
Binary FlagName 
type Rep FlagName 

type FlagAssignment = [(FlagName, Bool)]

A FlagAssignment is a total or partial mapping of FlagNames to Bool flag values. It represents the flags chosen by the user or discovered during configuration. For example --flags=foo --flags=-bar becomes [("foo", True), ("bar", False)]

data CondTree v c a




condTreeData :: a
condTreeConstraints :: c
condTreeComponents :: [(Condition v, CondTree v c a, Maybe (CondTree v c a))]


(Eq v, Eq c, Eq a) => Eq (CondTree v c a) 
(Data v, Data c, Data a) => Data (CondTree v c a) 
(Show v, Show c, Show a) => Show (CondTree v c a) 
Generic (CondTree v c a) 
(Binary v, Binary c, Binary a) => Binary (CondTree v c a) 
type Rep (CondTree v c a) 

data ConfVar

A ConfVar represents the variable type used.


Eq ConfVar 
Data ConfVar 
Show ConfVar 
Generic ConfVar 
Binary ConfVar 
type Rep ConfVar 

data Condition c

A boolean expression parameterized over the variable type used.


Var c 
Lit Bool 
CNot (Condition c) 
COr (Condition c) (Condition c) 
CAnd (Condition c) (Condition c) 


Monad Condition 
Functor Condition 
Applicative Condition 
Foldable Condition 
Traversable Condition 
MonadPlus Condition 
Alternative Condition 
Eq c => Eq (Condition c) 
Data c => Data (Condition c) 
Show c => Show (Condition c) 
Generic (Condition c) 
Monoid (Condition a) 
Binary c => Binary (Condition c) 
Semigroup (Condition a) 
type Rep (Condition c) 

cNot :: Condition a -> Condition a

Boolean negation of a Condition value.

cAnd :: Condition a -> Condition a -> Condition a

Boolean AND of two Condtion values.

cOr :: Eq v => Condition v -> Condition v -> Condition v

Boolean OR of two Condition values.

Source repositories

data SourceRepo

Information about the source revision control system for a package.

When specifying a repo it is useful to know the meaning or intention of the information as doing so enables automation. There are two obvious common purposes: one is to find the repo for the latest development version, the other is to find the repo for this specific release. The ReopKind specifies which one we mean (or another custom one).

A package can specify one or the other kind or both. Most will specify just a head repo but some may want to specify a repo to reconstruct the sources for this package release.

The required information is the RepoType which tells us if it's using Darcs, Git for example. The repoLocation and other details are interpreted according to the repo type.




repoKind :: RepoKind

The kind of repo. This field is required.

repoType :: Maybe RepoType

The type of the source repository system for this repo, eg Darcs or Git. This field is required.

repoLocation :: Maybe String

The location of the repository. For most RepoTypes this is a URL. This field is required.

repoModule :: Maybe String

CVS can put multiple "modules" on one server and requires a module name in addition to the location to identify a particular repo. Logically this is part of the location but unfortunately has to be specified separately. This field is required for the CVS RepoType and should not be given otherwise.

repoBranch :: Maybe String

The name or identifier of the branch, if any. Many source control systems have the notion of multiple branches in a repo that exist in the same location. For example Git and CVS use this while systems like Darcs use different locations for different branches. This field is optional but should be used if necessary to identify the sources, especially for the RepoThis repo kind.

repoTag :: Maybe String

The tag identify a particular state of the repository. This should be given for the RepoThis repo kind and not for RepoHead kind.

repoSubdir :: Maybe FilePath

Some repositories contain multiple projects in different subdirectories This field specifies the subdirectory where this packages sources can be found, eg the subdirectory containing the .cabal file. It is interpreted relative to the root of the repository. This field is optional. If not given the default is "." ie no subdirectory.


Eq SourceRepo 
Data SourceRepo 
Read SourceRepo 
Show SourceRepo 
Generic SourceRepo 
Binary SourceRepo 
type Rep SourceRepo 

data RepoKind

What this repo info is for, what it represents.



The repository for the "head" or development version of the project. This repo is where we should track the latest development activity or the usual repo people should get to contribute patches.


The repository containing the sources for this exact package version or release. For this kind of repo a tag should be given to give enough information to re-create the exact sources.

RepoKindUnknown String 


Eq RepoKind 
Data RepoKind 
Ord RepoKind 
Read RepoKind 
Show RepoKind 
Generic RepoKind 
Binary RepoKind 
Text RepoKind 
type Rep RepoKind 

data RepoType

An enumeration of common source control systems. The fields used in the SourceRepo depend on the type of repo. The tools and methods used to obtain and track the repo depend on the repo type.


Eq RepoType 
Data RepoType 
Ord RepoType 
Read RepoType 
Show RepoType 
Generic RepoType 
Binary RepoType 
Text RepoType 
type Rep RepoType 

Custom setup build information

data SetupBuildInfo




setupDepends :: [Dependency]
defaultSetupDepends :: Bool

Is this a default 'custom-setup' section added by the cabal-install code (as opposed to user-provided)? This field is only used internally, and doesn't correspond to anything in the .cabal file. See #3199.