Distribution.Types.PackageDescription

Cabal-2.2.0.1: A framework for packaging Haskell software

Copyright | Isaac Jones 2003-2005
License | BSD3
Maintainer | cabal-devel@haskell.org
Portability | portable
Safe Haskell | None
Language | Haskell2010

Distribution.Types.PackageDescription

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`, `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.

Synopsis

- data PackageDescription = PackageDescription {
  - specVersionRaw :: Either Version VersionRange
  - package :: PackageIdentifier
  - licenseRaw :: Either 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
  - description :: String
  - category :: String
  - customFieldsPD :: [(String, String)]
  - buildDepends :: [Dependency]
  - buildTypeRaw :: Maybe BuildType
  - setupBuildInfo :: Maybe SetupBuildInfo
  - library :: Maybe Library
  - subLibraries :: [Library]
  - executables :: [Executable]
  - foreignLibs :: [ForeignLib]
  - testSuites :: [TestSuite]
  - benchmarks :: [Benchmark]
  - dataFiles :: [FilePath]
  - dataDir :: FilePath
  - extraSrcFiles :: [FilePath]
  - extraTmpFiles :: [FilePath]
  - extraDocFiles :: [FilePath]
  }
- specVersion :: PackageDescription -> Version
- specVersion' :: Either Version VersionRange -> Version
- license :: PackageDescription -> License
- license' :: Either License License -> License
- descCabalVersion :: PackageDescription -> VersionRange
- buildType :: PackageDescription -> BuildType
- emptyPackageDescription :: PackageDescription
- hasPublicLib :: PackageDescription -> Bool
- hasLibs :: PackageDescription -> Bool
- allLibraries :: PackageDescription -> [Library]
- withLib :: PackageDescription -> (Library -> IO ()) -> IO ()
- hasExes :: PackageDescription -> Bool
- withExe :: PackageDescription -> (Executable -> IO ()) -> IO ()
- hasTests :: PackageDescription -> Bool
- withTest :: PackageDescription -> (TestSuite -> IO ()) -> IO ()
- hasBenchmarks :: PackageDescription -> Bool
- withBenchmark :: PackageDescription -> (Benchmark -> IO ()) -> IO ()
- hasForeignLibs :: PackageDescription -> Bool
- withForeignLib :: PackageDescription -> (ForeignLib -> IO ()) -> IO ()
- allBuildInfo :: PackageDescription -> [BuildInfo]
- enabledBuildInfos :: PackageDescription -> ComponentRequestedSpec -> [BuildInfo]
- updatePackageDescription :: HookedBuildInfo -> PackageDescription -> PackageDescription
- pkgComponents :: PackageDescription -> [Component]
- pkgBuildableComponents :: PackageDescription -> [Component]
- enabledComponents :: PackageDescription -> ComponentRequestedSpec -> [Component]
- lookupComponent :: PackageDescription -> ComponentName -> Maybe Component
- getComponent :: PackageDescription -> ComponentName -> Component

# Documentation

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 |
Fields 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. See also `specVersion`. package :: PackageIdentifier licenseRaw :: Either 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 `finalizePD` 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. buildTypeRaw :: Maybe BuildType The original `build-type` value as parsed from the `.cabal` file without defaulting. See also `buildType`. Since: Cabal-2.2 setupBuildInfo :: Maybe SetupBuildInfo library :: Maybe Library subLibraries :: [Library] executables :: [Executable] foreignLibs :: [ForeignLib] testSuites :: [TestSuite] benchmarks :: [Benchmark] dataFiles :: [FilePath] dataDir :: FilePath extraSrcFiles :: [FilePath] extraTmpFiles :: [FilePath] extraDocFiles :: [FilePath]

Instances

Eq PackageDescription # |
Instance details Defined in Distribution.Types.PackageDescription Methods (==) :: PackageDescription -> PackageDescription -> Bool # (/=) :: PackageDescription -> PackageDescription -> Bool #
Data PackageDescription # |
Instance details Defined in Distribution.Types.PackageDescription Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> PackageDescription -> c PackageDescription Source # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c PackageDescription Source # toConstr :: PackageDescription -> Constr Source # dataTypeOf :: PackageDescription -> DataType Source # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c PackageDescription) Source # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c PackageDescription) Source # gmapT :: (forall b. Data b => b -> b) -> PackageDescription -> PackageDescription Source # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> PackageDescription -> r Source # gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> PackageDescription -> r Source # gmapQ :: (forall d. Data d => d -> u) -> PackageDescription -> [u] Source # gmapQi :: Int -> (forall d. Data d => d -> u) -> PackageDescription -> u Source # gmapM :: Monad m => (forall d. Data d => d -> m d) -> PackageDescription -> m PackageDescription Source # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> PackageDescription -> m PackageDescription Source # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> PackageDescription -> m PackageDescription Source #
Read PackageDescription # |
Instance details Defined in Distribution.Types.PackageDescription Methods readsPrec :: Int -> ReadS PackageDescription Source # readList :: ReadS [PackageDescription] Source # readPrec :: ReadPrec PackageDescription Source # readListPrec :: ReadPrec [PackageDescription] Source #
Show PackageDescription # |
Instance details Defined in Distribution.Types.PackageDescription Methods showsPrec :: Int -> PackageDescription -> ShowS Source # show :: PackageDescription -> String Source # showList :: [PackageDescription] -> ShowS Source #
Generic PackageDescription # |
Instance details Defined in Distribution.Types.PackageDescription Associated Types type Rep PackageDescription :: * -> * Source # Methods from :: PackageDescription -> Rep PackageDescription x Source # to :: Rep PackageDescription x -> PackageDescription Source #
NFData PackageDescription # |
Instance details Defined in Distribution.Types.PackageDescription Methods rnf :: PackageDescription -> () Source #
Binary PackageDescription # |
Instance details Defined in Distribution.Types.PackageDescription Methods put :: PackageDescription -> Put Source # get :: Get PackageDescription Source # putList :: [PackageDescription] -> Put Source #
Package PackageDescription # |
Instance details Defined in Distribution.Types.PackageDescription Methods packageId :: PackageDescription -> PackageIdentifier #
type Rep PackageDescription # |
Instance details Defined in Distribution.Types.PackageDescription type Rep PackageDescription = D1 (MetaData "PackageDescription" "Distribution.Types.PackageDescription" "Cabal-2.2.0.1" False) (C1 (MetaCons "PackageDescription" PrefixI True) ((((S1 (MetaSel (Just "specVersionRaw") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Either Version VersionRange)) :*: (S1 (MetaSel (Just "package") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 PackageIdentifier) :*: S1 (MetaSel (Just "licenseRaw") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Either License License)))) :*: ((S1 (MetaSel (Just "licenseFiles") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [FilePath]) :*: S1 (MetaSel (Just "copyright") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 String)) :*: (S1 (MetaSel (Just "maintainer") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 String) :*: S1 (MetaSel (Just "author") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 String)))) :*: (((S1 (MetaSel (Just "stability") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 String) :*: S1 (MetaSel (Just "testedWith") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [(CompilerFlavor, VersionRange)])) :*: (S1 (MetaSel (Just "homepage") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 String) :*: S1 (MetaSel (Just "pkgUrl") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 String))) :*: ((S1 (MetaSel (Just "bugReports") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 String) :*: S1 (MetaSel (Just "sourceRepos") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [SourceRepo])) :*: (S1 (MetaSel (Just "synopsis") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 String) :*: S1 (MetaSel (Just "description") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 String))))) :*: ((((S1 (MetaSel (Just "category") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 String) :*: S1 (MetaSel (Just "customFieldsPD") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [(String, String)])) :*: (S1 (MetaSel (Just "buildDepends") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [Dependency]) :*: S1 (MetaSel (Just "buildTypeRaw") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Maybe BuildType)))) :*: ((S1 (MetaSel (Just "setupBuildInfo") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Maybe SetupBuildInfo)) :*: S1 (MetaSel (Just "library") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Maybe Library))) :*: (S1 (MetaSel (Just "subLibraries") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [Library]) :*: S1 (MetaSel (Just "executables") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [Executable])))) :*: (((S1 (MetaSel (Just "foreignLibs") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [ForeignLib]) :*: S1 (MetaSel (Just "testSuites") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [TestSuite])) :*: (S1 (MetaSel (Just "benchmarks") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [Benchmark]) :*: S1 (MetaSel (Just "dataFiles") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [FilePath]))) :*: ((S1 (MetaSel (Just "dataDir") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 FilePath) :*: S1 (MetaSel (Just "extraSrcFiles") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [FilePath])) :*: (S1 (MetaSel (Just "extraTmpFiles") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [FilePath]) :*: S1 (MetaSel (Just "extraDocFiles") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [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.

specVersion' :: Either Version VersionRange -> Version #

Since: Cabal-2.2.0.0

license :: PackageDescription -> License #

The SPDX `LicenseExpression` of the package.

Since: Cabal-2.2.0.0

license' :: Either License License -> License #

See `license`.

Since: Cabal-2.2.0.0

descCabalVersion :: PackageDescription -> VersionRange #

Deprecated: Use specVersion instead. This symbol will be removed in Cabal-3.0 (est. Oct 2018).

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.

buildType :: PackageDescription -> BuildType #

The effective `build-type` after applying defaulting rules.

The original `build-type` value parsed is stored in the `buildTypeRaw` field. However, the `build-type` field is optional and can therefore be empty in which case we need to compute the effective `build-type`. This function implements the following defaulting rules:

- For `cabal-version:2.0` and below, default to the `Custom` build-type unconditionally.
- Otherwise, if a `custom-setup` stanza is defined, default to the `Custom` build-type; else default to `Simple` build-type.

Since: Cabal-2.2

emptyPackageDescription :: PackageDescription #

hasPublicLib :: PackageDescription -> Bool #

Does this package have a buildable PUBLIC library?

hasLibs :: PackageDescription -> Bool #

Does this package have any libraries?

allLibraries :: PackageDescription -> [Library] #

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

If the package description has a buildable library section, call the given function with the library build info as argument. You probably want `withLibLBI` if you have a `LocalBuildInfo`, see the note in Distribution.Types.ComponentRequestedSpec for more information.

hasExes :: PackageDescription -> Bool #

does this package have any executables?

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

Perform the action on each buildable `Executable` in the package description. You probably want `withExeLBI` if you have a `LocalBuildInfo`, see the note in Distribution.Types.ComponentRequestedSpec for more information.

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. You probably want `withTestLBI` if you have a `LocalBuildInfo`, see the note in Distribution.Types.ComponentRequestedSpec for more information.

hasBenchmarks :: PackageDescription -> Bool #

Does this package have any benchmarks?

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

Perform an action on each buildable `Benchmark` in a package. You probably want `withBenchLBI` if you have a `LocalBuildInfo`, see the note in Distribution.Types.ComponentRequestedSpec for more information.

hasForeignLibs :: PackageDescription -> Bool #

Does this package have any foreign libraries?

withForeignLib :: PackageDescription -> (ForeignLib -> IO ()) -> IO () #

Perform the action on each buildable `ForeignLib` in the package description.

allBuildInfo :: PackageDescription -> [BuildInfo] #

All `BuildInfo` in the `PackageDescription`: libraries, executables, test-suites and benchmarks.

Useful for implementing package checks.

enabledBuildInfos :: PackageDescription -> ComponentRequestedSpec -> [BuildInfo] #

Return all of the `BuildInfo`s of enabled components, i.e., all of the ones that would be built if you run `./Setup build`.

updatePackageDescription :: HookedBuildInfo -> PackageDescription -> PackageDescription #

pkgComponents :: PackageDescription -> [Component] #

All the components in the package.

pkgBuildableComponents :: PackageDescription -> [Component] #

A list of all components in the package that are buildable, i.e., were not marked with `buildable: False`. This does NOT indicate if we are actually going to build the component, see `enabledComponents` instead.

Since: Cabal-2.0.0.2

enabledComponents :: PackageDescription -> ComponentRequestedSpec -> [Component] #

A list of all components in the package that are enabled.

Since: Cabal-2.0.0.2

lookupComponent :: PackageDescription -> ComponentName -> Maybe Component #

getComponent :: PackageDescription -> ComponentName -> Component #