 | Cabal-1.10.1.0: A framework for packaging Haskell software | Contents | Index |
|
| Distribution.PackageDescription | | Portability | portable | | Maintainer | cabal-devel@haskell.org |
|
|
|
|
|
| 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,
Executable, and TestSuite sections each of which have associated
BuildInfo data that's used to build the library, exe, or test. 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 |
|
|
|
|
| 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 | | | 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] | | | 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 | | | library :: Maybe Library | | | executables :: [Executable] | | | testSuites :: [TestSuite] | | | dataFiles :: [FilePath] | | | dataDir :: FilePath | | | extraSrcFiles :: [FilePath] | | | extraTmpFiles :: [FilePath] | |
|
|  Instances | |
|
|
| emptyPackageDescription :: PackageDescription |
|
| 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 |
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.
| | 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 | |
|
|
| knownBuildTypes :: [BuildType] |
|
| Libraries
|
|
| data Library |
| Constructors | | Library | | | exposedModules :: [ModuleName] | | | libExposed :: Bool | Is the lib to be exposed by default?
| | libBuildInfo :: BuildInfo | |
|
| | Instances | |
|
|
| emptyLibrary :: 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)
|
|
| Executables
|
|
| data Executable |
| Constructors | | Executable | | | exeName :: String | | | modulePath :: FilePath | | | buildInfo :: BuildInfo | |
|
| | Instances | |
|
|
| emptyExecutable :: Executable |
|
| 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
|
|
| Tests
|
|
| data TestSuite |
| A "test-suite" stanza in a cabal file.
| | Constructors | | | Instances | |
|
|
| 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.
| | Constructors | | 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).
|
| | Instances | |
|
|
| data TestType |
| The "test-type" field in the test suite stanza.
| | Constructors | | TestTypeExe Version | "type: exitcode-stdio-x.y"
| | TestTypeLib Version | "type: detailed-x.y"
| | TestTypeUnknown String Version | Some unknown test type e.g. "type: foo"
|
| | Instances | |
|
|
| testType :: TestSuite -> TestType |
|
| knownTestTypes :: [TestType] |
|
| emptyTestSuite :: TestSuite |
|
| 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.
|
|
| Build information
|
|
| data BuildInfo |
| 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
| | 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
| | 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.
| | targetBuildDepends :: [Dependency] | Dependencies specific to a library or executable target
|
|
| | 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.
|
|
| 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)]) |
|
| emptyHookedBuildInfo :: HookedBuildInfo |
|
| updatePackageDescription :: HookedBuildInfo -> PackageDescription -> PackageDescription |
|
| package configuration
|
|
| data GenericPackageDescription |
| Constructors | | GenericPackageDescription | | |
| | Instances | |
|
|
| 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.
| | Constructors | | MkFlag | | | flagName :: FlagName | | | flagDescription :: String | | | flagDefault :: Bool | | | flagManual :: Bool | |
|
| | Instances | |
|
|
| newtype FlagName |
| A FlagName is the name of a user-defined configuration flag
| | Constructors | | | Instances | |
|
|
| 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 |
| Constructors | | | 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 |
| A ConfVar represents the variable type used.
| | Constructors | | | Instances | |
|
|
| data Condition c |
| A boolean expression parameterized over the variable type used.
| | Constructors | | | Instances | |
|
|
| 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.
| | 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 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.
|
|
| | Instances | |
|
|
| data RepoKind |
| 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 | |
|
|
| 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.
| | Constructors | | Darcs | | | Git | | | SVN | | | CVS | | | Mercurial | | | GnuArch | | | Bazaar | | | Monotone | | | OtherRepoType String | |
| | Instances | |
|
|
| knownRepoTypes :: [RepoType] |
|
| Produced by Haddock version 2.6.1 |