Portability | portable |
---|---|
Maintainer | cabal-devel@haskell.org |
Distribution.PackageDescription
Contents
Description
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
and Executable
sections each of which have associated BuildInfo
data
that's used to build the library or exe. 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.
- data PackageDescription = PackageDescription {
- package :: PackageIdentifier
- license :: License
- licenseFile :: FilePath
- copyright :: String
- maintainer :: String
- author :: String
- stability :: String
- testedWith :: [(CompilerFlavor, VersionRange)]
- homepage :: String
- pkgUrl :: String
- bugReports :: String
- sourceRepos :: [SourceRepo]
- synopsis :: String
- description :: String
- category :: String
- customFieldsPD :: [(String, String)]
- buildDepends :: [Dependency]
- descCabalVersion :: VersionRange
- buildType :: Maybe BuildType
- library :: Maybe Library
- executables :: [Executable]
- dataFiles :: [FilePath]
- dataDir :: FilePath
- extraSrcFiles :: [FilePath]
- extraTmpFiles :: [FilePath]
- emptyPackageDescription :: PackageDescription
- data BuildType
- knownBuildTypes :: [BuildType]
- data Library = Library {}
- emptyLibrary :: Library
- withLib :: PackageDescription -> (Library -> IO ()) -> IO ()
- hasLibs :: PackageDescription -> Bool
- libModules :: Library -> [ModuleName]
- data Executable = Executable {}
- emptyExecutable :: Executable
- withExe :: PackageDescription -> (Executable -> IO ()) -> IO ()
- hasExes :: PackageDescription -> Bool
- exeModules :: Executable -> [ModuleName]
- data BuildInfo = BuildInfo {
- buildable :: Bool
- buildTools :: [Dependency]
- cppOptions :: [String]
- ccOptions :: [String]
- ldOptions :: [String]
- pkgconfigDepends :: [Dependency]
- frameworks :: [String]
- cSources :: [FilePath]
- hsSourceDirs :: [FilePath]
- otherModules :: [ModuleName]
- extensions :: [Extension]
- extraLibs :: [String]
- extraLibDirs :: [String]
- includeDirs :: [FilePath]
- includes :: [FilePath]
- installIncludes :: [FilePath]
- options :: [(CompilerFlavor, [String])]
- ghcProfOptions :: [String]
- ghcSharedOptions :: [String]
- customFieldsBI :: [(String, String)]
- targetBuildDepends :: [Dependency]
- emptyBuildInfo :: BuildInfo
- allBuildInfo :: PackageDescription -> [BuildInfo]
- hcOptions :: CompilerFlavor -> BuildInfo -> [String]
- type HookedBuildInfo = (Maybe BuildInfo, [(String, BuildInfo)])
- emptyHookedBuildInfo :: HookedBuildInfo
- updatePackageDescription :: HookedBuildInfo -> PackageDescription -> PackageDescription
- data GenericPackageDescription = GenericPackageDescription {}
- data Flag = MkFlag {}
- newtype FlagName = FlagName String
- type FlagAssignment = [(FlagName, Bool)]
- data CondTree v c a = CondNode {
- condTreeData :: a
- condTreeConstraints :: c
- condTreeComponents :: [(Condition v, CondTree v c a, Maybe (CondTree v c a))]
- data ConfVar
- = OS OS
- | Arch Arch
- | Flag FlagName
- | Impl CompilerFlavor VersionRange
- data Condition c
- data SourceRepo = SourceRepo {}
- data RepoKind
- data RepoType
Package descriptions
data PackageDescription Source
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.
Constructors
PackageDescription | |
Fields
|
The type of build system used by this package.
Constructors
Simple | calls |
Configure | calls |
Make | calls |
Custom | uses user-supplied |
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. |
Libraries
Constructors
Library | |
Fields
|
withLib :: PackageDescription -> (Library -> IO ()) -> IO ()Source
If the package description has a library section, call the given function with the library build info as argument.
hasLibs :: PackageDescription -> BoolSource
does this package have any libraries?
libModules :: Library -> [ModuleName]Source
Get all the module names from the library (exposed and internal modules)
Executables
withExe :: PackageDescription -> (Executable -> IO ()) -> IO ()Source
Perform the action on each buildable Executable
in the package
description.
hasExes :: PackageDescription -> BoolSource
does this package have any executables?
exeModules :: Executable -> [ModuleName]Source
Get all the module names from an exe
Build information
Constructors
BuildInfo | |
Fields
|
allBuildInfo :: PackageDescription -> [BuildInfo]Source
The BuildInfo
for the library (if there is one and it's buildable) and
all the buildable executables. Useful for gathering dependencies.
hcOptions :: CompilerFlavor -> BuildInfo -> [String]Source
Select options for a particular Haskell compiler.
Supplementary build information
package configuration
data GenericPackageDescription Source
Constructors
GenericPackageDescription | |
Fields
|
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.
Constructors
MkFlag | |
Fields
|
A FlagName
is the name of a user-defined configuration flag
type FlagAssignment = [(FlagName, Bool)]Source
A FlagAssignment
is a total or partial mapping of FlagName
s 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)]
Constructors
CondNode | |
Fields
|
A ConfVar
represents the variable type used.
Constructors
OS OS | |
Arch Arch | |
Flag FlagName | |
Impl CompilerFlavor VersionRange |
A boolean expression parameterized over the variable type used.
Source repositories
data SourceRepo Source
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.
Constructors
SourceRepo | |
Fields
|
Instances
What this repo info is for, what it represents.
Constructors
RepoHead | 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. |
RepoThis | 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 |
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.