| Cabal-1.6.0.3: A framework for packaging Haskell software | Source code | Contents | Index
Distribution.PackageDescription |
Portability | portable
Maintainer | cabal-devel@haskell.org
Contents
Package descriptions Libraries Executables Build information Supplementary build information package configuration Source repositories
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.
Synopsis
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
= Simple
| Configure
| Make
| Custom
| UnknownBuildType String
knownBuildTypes :: [BuildType]
data Library = Library {
exposedModules :: [ModuleName]
libExposed :: Bool
libBuildInfo :: BuildInfo
}
emptyLibrary :: Library
withLib :: PackageDescription -> a -> (Library -> IO a) -> IO a
hasLibs :: PackageDescription -> Bool
libModules :: PackageDescription -> [ModuleName]
data Executable = Executable {
exeName :: String
modulePath :: FilePath
buildInfo :: BuildInfo
}
emptyExecutable :: Executable
withExe :: PackageDescription -> (Executable -> IO a) -> IO ()
hasExes :: PackageDescription -> Bool
exeModules :: PackageDescription -> [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)]
}
emptyBuildInfo :: BuildInfo
allBuildInfo :: PackageDescription -> [BuildInfo]
hcOptions :: CompilerFlavor -> BuildInfo -> [String]
type HookedBuildInfo = (Maybe BuildInfo, [(String, BuildInfo)])
emptyHookedBuildInfo :: HookedBuildInfo
updatePackageDescription :: HookedBuildInfo -> PackageDescription -> PackageDescription
data GenericPackageDescription = GenericPackageDescription {
packageDescription :: PackageDescription
genPackageFlags :: [Flag]
condLibrary :: Maybe (CondTree ConfVar [Dependency] Library)
condExecutables :: [(String, CondTree ConfVar [Dependency] Executable)]
}
data Flag = MkFlag {
flagName :: FlagName
flagDescription :: String
flagDefault :: Bool
flagManual :: Bool
}
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
= Var c
| Lit Bool
| CNot (Condition c)
| COr (Condition c) (Condition c)
| CAnd (Condition c) (Condition c)
data SourceRepo = SourceRepo {
repoKind :: RepoKind
repoType :: Maybe RepoType
repoLocation :: Maybe String
repoModule :: Maybe String
repoBranch :: Maybe String
repoTag :: Maybe String
repoSubdir :: Maybe FilePath
}
data RepoKind
= RepoHead
| RepoThis
| RepoKindUnknown String
data RepoType
= Darcs
| Git
| SVN
| CVS
| Mercurial
| GnuArch
| Bazaar
| Monotone
| OtherRepoType String
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 |
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 | 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] |
descCabalVersion :: VersionRange | If this package depends on a specific version of Cabal, give that here.
buildType :: Maybe BuildType |
library :: Maybe Library |
executables :: [Executable] |
dataFiles :: [FilePath] |
dataDir :: FilePath |
extraSrcFiles :: [FilePath] |
extraTmpFiles :: [FilePath] |
Instances
Eq PackageDescription
Read PackageDescription
Show PackageDescription
Package PackageDescription
emptyPackageDescription :: PackageDescription | Source
data BuildType | Source
The type of build system used by this package.
Constructors
Simple | calls `Distribution.Simple.defaultMain`
Configure | calls `Distribution.Simple.defaultMainWithHooks defaultUserHooks`, which invokes `configure` to generate additional build information used by later phases.
Make | calls `Distribution.Make.defaultMain`
Custom | 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.
Instances
Eq BuildType
Read BuildType
Show BuildType
Text BuildType
knownBuildTypes :: [BuildType] | Source
Libraries
data Library | Source
Constructors
Library |
exposedModules :: [ModuleName] |
libExposed :: Bool | Is the lib to be exposed by default?
libBuildInfo :: BuildInfo |
Instances
Eq Library
Read Library
Show Library
Monoid Library
emptyLibrary :: Library | Source
withLib :: PackageDescription -> a -> (Library -> IO a) -> IO a | Source
If the package description has a library section, call the given function with the library build info as argument.
hasLibs :: PackageDescription -> Bool | Source
does this package have any libraries?
libModules :: PackageDescription -> [ModuleName] | Source
Get all the module names from the libraries in this package
Executables
data Executable | Source
Constructors
Executable |
exeName :: String |
modulePath :: FilePath |
buildInfo :: BuildInfo |
Instances
Eq Executable
Read Executable
Show Executable
Monoid Executable
emptyExecutable :: Executable | Source
withExe :: PackageDescription -> (Executable -> IO a) -> IO () | Source
Perform the action on each buildable `Executable` in the package description.
hasExes :: PackageDescription -> Bool | Source
does this package have any executables?
exeModules :: PackageDescription -> [ModuleName] | Source
Get all the module names from the exes in this package
Build information
data BuildInfo | Source
Constructors
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
cSources :: [FilePath] |
hsSourceDirs :: [FilePath] | where to look for the haskell module hierarchy
otherModules :: [ModuleName] | non-exposed or non-main modules
extensions :: [Extension] |
extraLibs :: [String] | what libraries to link with when compiling a program that uses your package
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])] |
ghcProfOptions :: [String] |
ghcSharedOptions :: [String] |
customFieldsBI :: [(String, String)] | Custom fields starting with x-, stored in a simple assoc-list.
Instances
Eq BuildInfo
Read BuildInfo
Show BuildInfo
Monoid BuildInfo
emptyBuildInfo :: BuildInfo | Source
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
type HookedBuildInfo = (Maybe BuildInfo, [(String, BuildInfo)]) | Source
emptyHookedBuildInfo :: HookedBuildInfo | Source
updatePackageDescription :: HookedBuildInfo -> PackageDescription -> PackageDescription | Source
package configuration
data GenericPackageDescription | Source
Constructors
GenericPackageDescription |
packageDescription :: PackageDescription |
genPackageFlags :: [Flag] |
condLibrary :: Maybe (CondTree ConfVar [Dependency] Library) |
condExecutables :: [(String, CondTree ConfVar [Dependency] Executable)] |
Instances
Eq GenericPackageDescription
Show GenericPackageDescription
Package GenericPackageDescription
data Flag | Source
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 |
flagName :: FlagName |
flagDescription :: String |
flagDefault :: Bool |
flagManual :: Bool |
Instances
Eq Flag
Show Flag
newtype FlagName | Source
A `FlagName` is the name of a user-defined configuration flag
Constructors
FlagName String |
Instances
Eq FlagName
Ord FlagName
Show FlagName
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)]`
data CondTree v c a | Source
Constructors
CondNode |
condTreeData :: a |
condTreeConstraints :: c |
condTreeComponents :: [(Condition v, CondTree v c a, Maybe (CondTree v c a))] |
Instances
(Eq v, Eq c, Eq a) => Eq (CondTree v c a)
(Show v, Show c, Show a) => Show (CondTree v c a)
data ConfVar | Source
A `ConfVar` represents the variable type used.
Constructors
OS OS |
Arch Arch |
Flag FlagName |
Impl CompilerFlavor VersionRange |
Instances
Eq ConfVar
Show ConfVar
data Condition c | Source
A boolean expression parameterized over the variable type used.
Constructors
Var c |
Lit Bool |
CNot (Condition c) |
COr (Condition c) (Condition c) |
CAnd (Condition c) (Condition c) |
Instances
Eq c => Eq (Condition c)
Show c => Show (Condition c)
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 |
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 `RepoType`s 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.
Instances
Eq SourceRepo
Read SourceRepo
Show SourceRepo
data RepoKind | Source
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 |
Instances
Eq RepoKind
Ord RepoKind
Read RepoKind
Show RepoKind
Text RepoKind
data RepoType | Source
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.
Constructors
Darcs |
Git |
SVN |
CVS |
Mercurial |
GnuArch |
Bazaar |
Monotone |
OtherRepoType String |
Instances
Eq RepoType
Ord RepoType
Read RepoType
Show RepoType
Text RepoType
Produced by Haddock version 2.4.2