Cabal-1.2.0: A framework for packaging Haskell softwareContentsIndex
Distribution.PackageDescription
Portabilityportable
Stabilityalpha
MaintainerIsaac Jones <ijones@syntaxpolice.org>
Contents
Package descriptions
Libraries
Executables
Parsing
Sanity checking
Build information
Supplementary build information
Utilities
Description
Package description and parsing.
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
synopsis :: String
description :: String
category :: String
buildDepends :: [Dependency]
descCabalVersion :: VersionRange
buildType :: BuildType
library :: (Maybe Library)
executables :: [Executable]
dataFiles :: [FilePath]
extraSrcFiles :: [FilePath]
extraTmpFiles :: [FilePath]
}
data GenericPackageDescription = GenericPackageDescription {
packageDescription :: PackageDescription
genPackageFlags :: [Flag]
condLibrary :: (Maybe (CondTree ConfVar [Dependency] Library))
condExecutables :: [(String, CondTree ConfVar [Dependency] Executable)]
}
finalizePackageDescription :: [(String, Bool)] -> Maybe [PackageIdentifier] -> String -> String -> (String, Version) -> GenericPackageDescription -> Either [Dependency] (PackageDescription, [(String, Bool)])
flattenPackageDescription :: GenericPackageDescription -> PackageDescription
emptyPackageDescription :: PackageDescription
readPackageDescription :: Verbosity -> FilePath -> IO GenericPackageDescription
writePackageDescription :: FilePath -> PackageDescription -> IO ()
showPackageDescription :: PackageDescription -> String
data BuildType
= Simple
| Configure
| Make
| Custom
data Library = Library {
exposedModules :: [String]
libBuildInfo :: BuildInfo
}
withLib :: PackageDescription -> a -> (Library -> IO a) -> IO a
hasLibs :: PackageDescription -> Bool
libModules :: PackageDescription -> [String]
data Executable = Executable {
exeName :: String
modulePath :: FilePath
buildInfo :: BuildInfo
}
withExe :: PackageDescription -> (Executable -> IO a) -> IO ()
hasExes :: PackageDescription -> Bool
exeModules :: PackageDescription -> [String]
data FieldDescr a = FieldDescr {
fieldName :: String
fieldGet :: (a -> Doc)
fieldSet :: (LineNo -> String -> a -> ParseResult a)
}
type LineNo = Int
sanityCheckPackage :: PackageDescription -> IO ([String], [String])
data BuildInfo = BuildInfo {
buildable :: Bool
buildTools :: [Dependency]
ccOptions :: [String]
ldOptions :: [String]
pkgconfigDepends :: [Dependency]
frameworks :: [String]
cSources :: [FilePath]
hsSourceDirs :: [FilePath]
otherModules :: [String]
extensions :: [Extension]
extraLibs :: [String]
extraLibDirs :: [String]
includeDirs :: [FilePath]
includes :: [FilePath]
installIncludes :: [FilePath]
options :: [(CompilerFlavor, [String])]
ghcProfOptions :: [String]
ghcSharedOptions :: [String]
}
emptyBuildInfo :: BuildInfo
allBuildInfo :: PackageDescription -> [BuildInfo]
type HookedBuildInfo = (Maybe BuildInfo, [(String, BuildInfo)])
emptyHookedBuildInfo :: HookedBuildInfo
readHookedBuildInfo :: Verbosity -> FilePath -> IO HookedBuildInfo
parseHookedBuildInfo :: String -> ParseResult HookedBuildInfo
writeHookedBuildInfo :: FilePath -> HookedBuildInfo -> IO ()
showHookedBuildInfo :: HookedBuildInfo -> String
updatePackageDescription :: HookedBuildInfo -> PackageDescription -> PackageDescription
satisfyDependency :: [PackageIdentifier] -> Dependency -> Maybe PackageIdentifier
data ParseResult a
= ParseFailed PError
| ParseOk [PWarning] a
hcOptions :: CompilerFlavor -> [(CompilerFlavor, [String])] -> [String]
autogenModuleName :: PackageDescription -> String
haddockName :: PackageDescription -> FilePath
setupMessage :: Verbosity -> String -> PackageDescription -> IO ()
cabalVersion :: Version
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.
Constructors
PackageDescription
package :: PackageIdentifier
license :: License
licenseFile :: FilePath
copyright :: String
maintainer :: String
author :: String
stability :: String
testedWith :: [(CompilerFlavor, VersionRange)]
homepage :: String
pkgUrl :: String
synopsis :: StringA one-line summary of this package
description :: StringA more verbose description of this package
category :: String
buildDepends :: [Dependency]
descCabalVersion :: VersionRangeIf this package depends on a specific version of Cabal, give that here.
buildType :: BuildType
library :: (Maybe Library)
executables :: [Executable]
dataFiles :: [FilePath]
extraSrcFiles :: [FilePath]
extraTmpFiles :: [FilePath]
show/hide Instances
data GenericPackageDescription
Constructors
GenericPackageDescription
packageDescription :: PackageDescription
genPackageFlags :: [Flag]
condLibrary :: (Maybe (CondTree ConfVar [Dependency] Library))
condExecutables :: [(String, CondTree ConfVar [Dependency] Executable)]
show/hide Instances
finalizePackageDescription
:: [(String, Bool)]Explicitly specified flag assignments
-> Maybe [PackageIdentifier]Available dependencies
-> StringOS-name
-> StringArch-name
-> (String, Version)Compiler + Version
-> GenericPackageDescription
-> Either [Dependency] (PackageDescription, [(String, Bool)])Either missing dependencies or the resolved package description along with the flag assignments chosen.
flattenPackageDescription :: GenericPackageDescription -> PackageDescription

Flatten a generic package description by ignoring all conditions and just join the field descriptors into on package description. Note, however, that this may lead to inconsistent field values, since all values are joined into one field, which may not be possible in the original package description, due to the use of exclusive choices (if ... else ...).

XXX: One particularly tricky case is defaulting. In the original package description, e.g., the source dirctory might either be the default or a certain, explicitly set path. Since defaults are filled in only after the package has been resolved and when no explicit value has been set, the default path will be missing from the package description returned by this function.

emptyPackageDescription :: PackageDescription
readPackageDescription :: Verbosity -> FilePath -> IO GenericPackageDescription
Parse the given package file. readPackageDescription :: Int -> FilePath -> IO PackageDescription readPackageDescription verbosity = readAndParseFile verbosity parseDescription
writePackageDescription :: FilePath -> PackageDescription -> IO ()
showPackageDescription :: PackageDescription -> String
data BuildType
The type of build system used by this package.
Constructors
Simplecalls Distribution.Simple.defaultMain
Configurecalls Distribution.Simple.defaultMainWithHooks defaultUserHooks, which invokes configure to generate additional build information used by later phases.
Makecalls Distribution.Make.defaultMain
Customuses user-supplied Setup.hs or Setup.lhs (default)
show/hide Instances
Libraries
data Library
Constructors
Library
exposedModules :: [String]
libBuildInfo :: BuildInfo
show/hide Instances
withLib :: PackageDescription -> a -> (Library -> IO a) -> IO a
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 :: PackageDescription -> [String]
Get all the module names from the libraries in this package
Executables
data Executable
Constructors
Executable
exeName :: String
modulePath :: FilePath
buildInfo :: BuildInfo
show/hide Instances
withExe :: PackageDescription -> (Executable -> IO a) -> IO ()
Perform the action on each buildable Executable in the package description.
hasExes :: PackageDescription -> Bool
does this package have any executables?
exeModules :: PackageDescription -> [String]
Get all the module names from the exes in this package
Parsing
data FieldDescr a
Field descriptor. The parameter a parameterizes over where the field's value is stored in.
Constructors
FieldDescr
fieldName :: String
fieldGet :: (a -> Doc)
fieldSet :: (LineNo -> String -> a -> ParseResult a)fieldSet n str x Parses the field value from the given input string str and stores the result in x if the parse was successful. Otherwise, reports an error on line number n.
type LineNo = Int
Sanity checking
sanityCheckPackage :: PackageDescription -> IO ([String], [String])
Sanity check this description file.
Build information
data BuildInfo
Constructors
BuildInfo
buildable :: Boolcomponent is buildable here
buildTools :: [Dependency]tools needed to build this bit
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 :: [String]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]
show/hide Instances
emptyBuildInfo :: BuildInfo
allBuildInfo :: PackageDescription -> [BuildInfo]
The BuildInfo for the library (if there is one and it's buildable) and all the buildable executables. Useful for gathering dependencies.
Supplementary build information
type HookedBuildInfo = (Maybe BuildInfo, [(String, BuildInfo)])
emptyHookedBuildInfo :: HookedBuildInfo
readHookedBuildInfo :: Verbosity -> FilePath -> IO HookedBuildInfo
parseHookedBuildInfo :: String -> ParseResult HookedBuildInfo
writeHookedBuildInfo :: FilePath -> HookedBuildInfo -> IO ()
showHookedBuildInfo :: HookedBuildInfo -> String
updatePackageDescription :: HookedBuildInfo -> PackageDescription -> PackageDescription
Update the given package description with the output from the pre-hooks.
Utilities
satisfyDependency :: [PackageIdentifier] -> Dependency -> Maybe PackageIdentifier
data ParseResult a
Constructors
ParseFailed PError
ParseOk [PWarning] a
show/hide Instances
hcOptions :: CompilerFlavor -> [(CompilerFlavor, [String])] -> [String]
Select options for a particular Haskell compiler.
autogenModuleName :: PackageDescription -> String
The name of the auto-generated module associated with a package
haddockName :: PackageDescription -> FilePath
setupMessage :: Verbosity -> String -> PackageDescription -> IO ()
cabalVersion :: Version
Produced by Haddock version 0.8