ghc-lib-parser-9.14.1.20251220: The GHC API, decoupled from GHC versions

Safe Haskell | Ignore
Language | GHC2021

GHC.Unit.Info

Description

Info about installed units (compiled libraries)

Synopsis

- data GenericUnitInfo srcpkgid srcpkgname uid modulename mod = GenericUnitInfo {
  - unitId :: uid
  - unitInstanceOf :: uid
  - unitInstantiations :: [(modulename, mod)]
  - unitPackageId :: srcpkgid
  - unitPackageName :: srcpkgname
  - unitPackageVersion :: Version
  - unitComponentName :: Maybe srcpkgname
  - unitAbiHash :: ShortText
  - unitDepends :: [uid]
  - unitAbiDepends :: [(uid, ShortText)]
  - unitImportDirs :: [FilePathST]
  - unitLibraries :: [ShortText]
  - unitExtDepLibsSys :: [ShortText]
  - unitExtDepLibsGhc :: [ShortText]
  - unitLibraryDirs :: [FilePathST]
  - unitLibraryDynDirs :: [FilePathST]
  - unitExtDepFrameworks :: [ShortText]
  - unitExtDepFrameworkDirs :: [FilePathST]
  - unitLinkerOptions :: [ShortText]
  - unitCcOptions :: [ShortText]
  - unitIncludes :: [ShortText]
  - unitIncludeDirs :: [FilePathST]
  - unitHaddockInterfaces :: [FilePathST]
  - unitHaddockHTMLs :: [FilePathST]
  - unitExposedModules :: [(modulename, Maybe mod)]
  - unitHiddenModules :: [modulename]
  - unitIsIndefinite :: Bool
  - unitIsExposed :: Bool
  - unitIsTrusted :: Bool
  }
- type GenUnitInfo unit = GenericUnitInfo PackageId PackageName unit ModuleName (GenModule (GenUnit unit))
- type UnitInfo = GenUnitInfo UnitId
- newtype UnitKey = UnitKey FastString
- type UnitKeyInfo = GenUnitInfo UnitKey
- mkUnitKeyInfo :: DbUnitInfo -> UnitKeyInfo
- mapUnitInfo :: IsUnitId v => (u -> v) -> GenUnitInfo u -> GenUnitInfo v
- mkUnitPprInfo :: (u -> FastString) -> GenUnitInfo u -> UnitPprInfo
- mkUnit :: UnitInfo -> Unit
- newtype PackageId = PackageId FastString
- newtype PackageName = PackageName {
  - unPackageName :: FastString
  }
- data Version = Version {
  - versionBranch :: [Int]
  - versionTags :: [String]
  }
- unitPackageNameString :: GenUnitInfo u -> String
- unitPackageIdString :: GenUnitInfo u -> String
- pprUnitInfo :: UnitInfo -> SDoc
- collectIncludeDirs :: [UnitInfo] -> [FilePath]
- collectExtraCcOpts :: [UnitInfo] -> [String]
- collectLibraryDirs :: Ways -> [UnitInfo] -> [FilePath]
- collectFrameworks :: [UnitInfo] -> [String]
- collectFrameworksDirs :: [UnitInfo] -> [String]
- unitHsLibs :: GhcNameVersion -> Ways -> UnitInfo -> [String]

# Documentation

data GenericUnitInfo srcpkgid srcpkgname uid modulename mod #

Information about an unit (a unit is an installed module library).

This is a subset of Cabal's `InstalledPackageInfo`, with just the bits that GHC is interested in.

Some types are left as parameters to be instantiated differently in ghc-pkg and in ghc itself.

Constructors

GenericUnitInfo |
Fields unitId :: uid Unique unit identifier that is used during compilation (e.g. to generate symbols). unitInstanceOf :: uid Identifier of an indefinite unit (i.e. with module holes) that this unit is an instance of. For non instantiated units, unitInstanceOf=unitId unitInstantiations :: [(modulename, mod)] How this unit instantiates some of its module holes. Map hole module names to actual module unitPackageId :: srcpkgid Source package identifier. Cabal instantiates this with Distribution.Types.PackageId.PackageId type which only contains the source package name and version. Notice that it doesn't contain the Hackage revision, nor any kind of hash. unitPackageName :: srcpkgname Source package name unitPackageVersion :: Version Source package version unitComponentName :: Maybe srcpkgname Name of the component. Cabal supports more than one components (libraries, executables, testsuites) in the same package. Each component has a name except the default one (that can only be a library component) for which we use Nothing. GHC only deals with "library" components as they are the only kind of components that can be registered in a database and used by other modules. unitAbiHash :: ShortText ABI hash used to avoid mixing up units compiled with different dependencies, compiler, options, etc. unitDepends :: [uid] Identifiers of the units this one depends on unitAbiDepends :: [(uid, ShortText)] Like `unitDepends`, but each dependency is annotated with the ABI hash we expect the dependency to respect. unitImportDirs :: [FilePathST] Directories containing module interfaces unitLibraries :: [ShortText] Names of the Haskell libraries provided by this unit unitExtDepLibsSys :: [ShortText] Names of the external system libraries that this unit depends on. See also `unitExtDepLibsGhc` field. unitExtDepLibsGhc :: [ShortText] Because of slight differences between the GHC dynamic linker (in GHC.Runtime.Linker) and the native system linker, some packages have to link with a different list of libraries when using GHC's. Examples include: libs that are actually gnu ld scripts, and the possibility that the .a libs do not exactly match the .so/.dll equivalents. If this field is set, then we use that instead of the `unitExtDepLibsSys` field. unitLibraryDirs :: [FilePathST] Directories containing libraries provided by this unit. See also `unitLibraryDynDirs`. It seems to be used to store paths to external library dependencies too. unitLibraryDynDirs :: [FilePathST] Directories containing the dynamic libraries provided by this unit. See also `unitLibraryDirs`. It seems to be used to store paths to external dynamic library dependencies too. unitExtDepFrameworks :: [ShortText] Names of the external MacOS frameworks that this unit depends on. unitExtDepFrameworkDirs :: [FilePathST] Directories containing MacOS frameworks that this unit depends on. unitLinkerOptions :: [ShortText] Linker (e.g. ld) command line options unitCcOptions :: [ShortText] C compiler options that needs to be passed to the C compiler when we compile some C code against this unit. unitIncludes :: [ShortText] C header files that are required by this unit (provided by this unit or external) unitIncludeDirs :: [FilePathST] Directories containing C header files that this unit depends on. unitHaddockInterfaces :: [FilePathST] Paths to Haddock interface files for this unit unitHaddockHTMLs :: [FilePathST] Paths to Haddock directories containing HTML files unitExposedModules :: [(modulename, Maybe mod)] Modules exposed by the unit. A module can be re-exported from another package. In this case, we indicate the module origin in the second parameter. unitHiddenModules :: [modulename] Hidden modules. These are useful for error reporting (e.g. if a hidden module is imported) unitIsIndefinite :: Bool True if this unit has some module holes that need to be instantiated with real modules to make the unit usable (a.k.a. Backpack). unitIsExposed :: Bool True if the unit is exposed. A unit could be installed in a database by "disabled" by not being exposed. unitIsTrusted :: Bool True if the unit is trusted (cf Safe Haskell)

#### Instances

Instances details

Binary DbUnitInfo # |
Instance details Defined in GHC.Unit.Database Methods put :: DbUnitInfo -> Put # get :: Get DbUnitInfo # putList :: [DbUnitInfo] -> Put #
(Show uid, Show modulename, Show mod, Show srcpkgid, Show srcpkgname) => Show (GenericUnitInfo srcpkgid srcpkgname uid modulename mod) # |
Instance details Defined in GHC.Unit.Database Methods showsPrec :: Int -> GenericUnitInfo srcpkgid srcpkgname uid modulename mod -> ShowS # show :: GenericUnitInfo srcpkgid srcpkgname uid modulename mod -> String # showList :: [GenericUnitInfo srcpkgid srcpkgname uid modulename mod] -> ShowS #
(Eq uid, Eq modulename, Eq mod, Eq srcpkgid, Eq srcpkgname) => Eq (GenericUnitInfo srcpkgid srcpkgname uid modulename mod) # |
Instance details Defined in GHC.Unit.Database Methods (==) :: GenericUnitInfo srcpkgid srcpkgname uid modulename mod -> GenericUnitInfo srcpkgid srcpkgname uid modulename mod -> Bool # (/=) :: GenericUnitInfo srcpkgid srcpkgname uid modulename mod -> GenericUnitInfo srcpkgid srcpkgname uid modulename mod -> Bool #

type GenUnitInfo unit = GenericUnitInfo PackageId PackageName unit ModuleName (GenModule (GenUnit unit)) #

Information about an installed unit

We parameterize on the unit identifier: * UnitKey: identifier used in the database (cf `UnitKeyInfo`) * UnitId: identifier used to generate code (cf `UnitInfo`)

These two identifiers are different for wired-in packages. See Note [About units] in GHC.Unit

type UnitInfo = GenUnitInfo UnitId #

Information about an installed unit (units are identified by their internal UnitId)

newtype UnitKey #

A unit key in the database

Constructors

UnitKey FastString |

#### Instances

Instances details

IsUnitId UnitKey # |
Instance details Defined in GHC.Unit.Types Methods unitFS :: UnitKey -> FastString #

type UnitKeyInfo = GenUnitInfo UnitKey #

Information about an installed unit (units are identified by their database UnitKey)

mkUnitKeyInfo :: DbUnitInfo -> UnitKeyInfo #

Convert a DbUnitInfo (read from a package database) into `UnitKeyInfo`

mapUnitInfo :: IsUnitId v => (u -> v) -> GenUnitInfo u -> GenUnitInfo v #

Map over the unit parameter

mkUnitPprInfo :: (u -> FastString) -> GenUnitInfo u -> UnitPprInfo #

Create a UnitPprInfo from a UnitInfo

mkUnit :: UnitInfo -> Unit #

Make a `Unit` from a `UnitInfo`

If the unit is definite, make a `RealUnit` from `unitId` field.

If the unit is indefinite, make a `VirtUnit` from `unitInstanceOf` and `unitInstantiations` fields. Note that in this case we don't keep track of `unitId`. It can be retrieved later with "improvement", i.e. matching on `unitInstanceOf/unitInstantiations` fields (see Note [About units] in GHC.Unit).

newtype PackageId #

Constructors

PackageId FastString |

#### Instances

Instances details

Uniquable PackageId # |
Instance details Defined in GHC.Unit.Info Methods getUnique :: PackageId -> Unique #
Outputable PackageId # |
Instance details Defined in GHC.Unit.Info Methods ppr :: PackageId -> SDoc #
Eq PackageId # |
Instance details Defined in GHC.Unit.Info Methods (==) :: PackageId -> PackageId -> Bool # (/=) :: PackageId -> PackageId -> Bool #

newtype PackageName #

Constructors

PackageName |
Fields unPackageName :: FastString

#### Instances

Instances details

Uniquable PackageName # |
Instance details Defined in GHC.Unit.Info Methods getUnique :: PackageName -> Unique #
Outputable PackageName # |
Instance details Defined in GHC.Unit.Info Methods ppr :: PackageName -> SDoc #
Eq PackageName # |
Instance details Defined in GHC.Unit.Info Methods (==) :: PackageName -> PackageName -> Bool # (/=) :: PackageName -> PackageName -> Bool #

data Version #

A `Version` represents the version of a software entity.

An instance of `Eq` is provided, which implements exact equality modulo reordering of the tags in the `versionTags` field.

An instance of `Ord` is also provided, which gives lexicographic ordering on the `versionBranch` fields (i.e. 2.1 > 2.0, 1.2.3 > 1.2.2, etc.). This is expected to be sufficient for many uses, but note that you may need to use a more specific ordering for your versioning scheme. For example, some versioning schemes may include pre-releases which have tags `"pre1"`, `"pre2"`, and so on, and these would need to be taken into account when determining ordering. In some cases, date ordering may be more appropriate, so the application would have to look for `date` tags in the `versionTags` field and compare those. The bottom line is, don't always assume that `compare` and other `Ord` operations are the right thing for every `Version`.

Similarly, concrete representations of versions may differ. One possible concrete representation is provided (see `showVersion` and `parseVersion`), but depending on the application a different concrete representation may be more appropriate.

Constructors

Version |
Fields versionBranch :: [Int] The numeric branch for this version. This reflects the fact that most software versions are tree-structured; there is a main trunk which is tagged with versions at various points (1,2,3...), and the first branch off the trunk after version 3 is 3.1, the second branch off the trunk after version 3 is 3.2, and so on. The tree can be branched arbitrarily, just by adding more digits. We represent the branch as a list of `Int`, so version 3.2.1 becomes [3,2,1]. Lexicographic ordering (i.e. the default instance of `Ord` for `[Int]`) gives the natural ordering of branches. versionTags :: [String] A version can be tagged with an arbitrary list of strings. The interpretation of the list of tags is entirely dependent on the entity that this version applies to.

#### Instances

Instances details

Binary Version | Since: binary-0.8.0.0
Instance details Defined in Data.Binary.Class Methods put :: Version -> Put # get :: Get Version # putList :: [Version] -> Put #
NFData Version | Since: deepseq-1.3.0.0
Instance details Defined in Control.DeepSeq Methods rnf :: Version -> () #
Data Version | @since base-4.7.0.0
Instance details Defined in GHC.Internal.Data.Data Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Version -> c Version # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c Version # toConstr :: Version -> Constr # dataTypeOf :: Version -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c Version) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c Version) # gmapT :: (forall b. Data b => b -> b) -> Version -> Version # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Version -> r # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Version -> r # gmapQ :: (forall d. Data d => d -> u) -> Version -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> Version -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> Version -> m Version # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Version -> m Version # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Version -> m Version #
Generic Version |
Instance details Defined in GHC.Internal.Data.Version Associated Types
type Rep Version | @since base-4.9.0.0
Instance details Defined in GHC.Internal.Data.Version type Rep Version = D1 ('MetaData "Version" "GHC.Internal.Data.Version" "ghc-internal" 'False) (C1 ('MetaCons "Version" 'PrefixI 'True) (S1 ('MetaSel ('Just "versionBranch") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [Int]) :*: S1 ('MetaSel ('Just "versionTags") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [String])))
Methods from :: Version -> Rep Version x # to :: Rep Version x -> Version #
IsList Version | @since base-4.8.0.0
Instance details Defined in GHC.Internal.IsList Associated Types
type Item Version |
Instance details Defined in GHC.Internal.IsList type Item Version = Int
Methods fromList :: [Item Version] -> Version # fromListN :: Int -> [Item Version] -> Version # toList :: Version -> [Item Version] #
Read Version | @since base-2.01
Instance details Defined in GHC.Internal.Data.Version Methods readsPrec :: Int -> ReadS Version # readList :: ReadS [Version] # readPrec :: ReadPrec Version # readListPrec :: ReadPrec [Version] #
Show Version | @since base-2.01
Instance details Defined in GHC.Internal.Data.Version Methods showsPrec :: Int -> Version -> ShowS # show :: Version -> String # showList :: [Version] -> ShowS #
Eq Version | @since base-2.01
Instance details Defined in GHC.Internal.Data.Version Methods (==) :: Version -> Version -> Bool # (/=) :: Version -> Version -> Bool #
Ord Version | @since base-2.01
Instance details Defined in GHC.Internal.Data.Version Methods compare :: Version -> Version -> Ordering # (<) :: Version -> Version -> Bool # (<=) :: Version -> Version -> Bool # (>) :: Version -> Version -> Bool # (>=) :: Version -> Version -> Bool # max :: Version -> Version -> Version # min :: Version -> Version -> Version #
type Rep Version | @since base-4.9.0.0
Instance details Defined in GHC.Internal.Data.Version type Rep Version = D1 ('MetaData "Version" "GHC.Internal.Data.Version" "ghc-internal" 'False) (C1 ('MetaCons "Version" 'PrefixI 'True) (S1 ('MetaSel ('Just "versionBranch") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [Int]) :*: S1 ('MetaSel ('Just "versionTags") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [String])))
type Item Version |
Instance details Defined in GHC.Internal.IsList type Item Version = Int

unitPackageNameString :: GenUnitInfo u -> String #

unitPackageIdString :: GenUnitInfo u -> String #

pprUnitInfo :: UnitInfo -> SDoc #

collectIncludeDirs :: [UnitInfo] -> [FilePath] #

Find all the include directories in the given units

collectExtraCcOpts :: [UnitInfo] -> [String] #

Find all the C-compiler options in the given units

collectLibraryDirs :: Ways -> [UnitInfo] -> [FilePath] #

Find all the library directories in the given units for the given ways

collectFrameworks :: [UnitInfo] -> [String] #

Find all the frameworks in the given units

collectFrameworksDirs :: [UnitInfo] -> [String] #

Find all the package framework paths in these and the preload packages

unitHsLibs :: GhcNameVersion -> Ways -> UnitInfo -> [String] #