Distribution.Client.PackageHash

cabal-install-3.12.1.0: The command-line interface for Cabal and Hackage.

Safe Haskell | None
Language | Haskell2010

Distribution.Client.PackageHash

Contents

- Calculating package hashes
  - Platform-specific variations

Description

Functions to calculate nix-style hashes for package ids.

The basic idea is simple, hash the combination of:

- the package tarball
- the ids of all the direct dependencies
- other local configuration (flags, profiling, etc)

See `PackageHashInputs` for a detailed list of what determines the hash.

Synopsis

- data PackageHashInputs = PackageHashInputs {
  - pkgHashPkgId :: PackageId
  - pkgHashComponent :: Maybe Component
  - pkgHashSourceHash :: PackageSourceHash
  - pkgHashPkgConfigDeps :: Set (PkgconfigName, Maybe PkgconfigVersion)
  - pkgHashDirectDeps :: Set InstalledPackageId
  - pkgHashOtherConfig :: PackageHashConfigInputs
  }
- data PackageHashConfigInputs = PackageHashConfigInputs {
  - pkgHashCompilerId :: CompilerId
  - pkgHashCompilerABI :: AbiTag
  - pkgHashPlatform :: Platform
  - pkgHashFlagAssignment :: FlagAssignment
  - pkgHashConfigureScriptArgs :: [String]
  - pkgHashVanillaLib :: Bool
  - pkgHashSharedLib :: Bool
  - pkgHashDynExe :: Bool
  - pkgHashFullyStaticExe :: Bool
  - pkgHashGHCiLib :: Bool
  - pkgHashProfLib :: Bool
  - pkgHashProfExe :: Bool
  - pkgHashProfLibDetail :: ProfDetailLevel
  - pkgHashProfExeDetail :: ProfDetailLevel
  - pkgHashCoverage :: Bool
  - pkgHashOptimization :: OptimisationLevel
  - pkgHashSplitObjs :: Bool
  - pkgHashSplitSections :: Bool
  - pkgHashStripLibs :: Bool
  - pkgHashStripExes :: Bool
  - pkgHashDebugInfo :: DebugInfoLevel
  - pkgHashProgramArgs :: Map String [String]
  - pkgHashExtraLibDirs :: [FilePath]
  - pkgHashExtraLibDirsStatic :: [FilePath]
  - pkgHashExtraFrameworkDirs :: [FilePath]
  - pkgHashExtraIncludeDirs :: [FilePath]
  - pkgHashProgPrefix :: Maybe PathTemplate
  - pkgHashProgSuffix :: Maybe PathTemplate
  - pkgHashPackageDbs :: [Maybe PackageDB]
  - pkgHashDocumentation :: Bool
  - pkgHashHaddockHoogle :: Bool
  - pkgHashHaddockHtml :: Bool
  - pkgHashHaddockHtmlLocation :: Maybe String
  - pkgHashHaddockForeignLibs :: Bool
  - pkgHashHaddockExecutables :: Bool
  - pkgHashHaddockTestSuites :: Bool
  - pkgHashHaddockBenchmarks :: Bool
  - pkgHashHaddockInternal :: Bool
  - pkgHashHaddockCss :: Maybe FilePath
  - pkgHashHaddockLinkedSource :: Bool
  - pkgHashHaddockQuickJump :: Bool
  - pkgHashHaddockContents :: Maybe PathTemplate
  - pkgHashHaddockIndex :: Maybe PathTemplate
  - pkgHashHaddockBaseUrl :: Maybe String
  - pkgHashHaddockLib :: Maybe String
  - pkgHashHaddockOutputDir :: Maybe FilePath
  }
- type PackageSourceHash = HashValue
- hashedInstalledPackageId :: PackageHashInputs -> InstalledPackageId
- hashPackageHashInputs :: PackageHashInputs -> HashValue
- renderPackageHashInputs :: PackageHashInputs -> ByteString
- hashedInstalledPackageIdLong :: PackageHashInputs -> InstalledPackageId
- hashedInstalledPackageIdShort :: PackageHashInputs -> InstalledPackageId

# Calculating package hashes

data PackageHashInputs #

All the information that contributes to a package's hash, and thus its `InstalledPackageId`.

Constructors

PackageHashInputs |
Fields pkgHashPkgId :: PackageId pkgHashComponent :: Maybe Component pkgHashSourceHash :: PackageSourceHash pkgHashPkgConfigDeps :: Set (PkgconfigName, Maybe PkgconfigVersion) pkgHashDirectDeps :: Set InstalledPackageId pkgHashOtherConfig :: PackageHashConfigInputs

data PackageHashConfigInputs #

Those parts of the package configuration that contribute to the package hash.

Constructors

PackageHashConfigInputs |
Fields pkgHashCompilerId :: CompilerId pkgHashCompilerABI :: AbiTag pkgHashPlatform :: Platform pkgHashFlagAssignment :: FlagAssignment pkgHashConfigureScriptArgs :: [String] pkgHashVanillaLib :: Bool pkgHashSharedLib :: Bool pkgHashDynExe :: Bool pkgHashFullyStaticExe :: Bool pkgHashGHCiLib :: Bool pkgHashProfLib :: Bool pkgHashProfExe :: Bool pkgHashProfLibDetail :: ProfDetailLevel pkgHashProfExeDetail :: ProfDetailLevel pkgHashCoverage :: Bool pkgHashOptimization :: OptimisationLevel pkgHashSplitObjs :: Bool pkgHashSplitSections :: Bool pkgHashStripLibs :: Bool pkgHashStripExes :: Bool pkgHashDebugInfo :: DebugInfoLevel pkgHashProgramArgs :: Map String [String] pkgHashExtraLibDirs :: [FilePath] pkgHashExtraLibDirsStatic :: [FilePath] pkgHashExtraFrameworkDirs :: [FilePath] pkgHashExtraIncludeDirs :: [FilePath] pkgHashProgPrefix :: Maybe PathTemplate pkgHashProgSuffix :: Maybe PathTemplate pkgHashPackageDbs :: [Maybe PackageDB] pkgHashDocumentation :: Bool pkgHashHaddockHoogle :: Bool pkgHashHaddockHtml :: Bool pkgHashHaddockHtmlLocation :: Maybe String pkgHashHaddockForeignLibs :: Bool pkgHashHaddockExecutables :: Bool pkgHashHaddockTestSuites :: Bool pkgHashHaddockBenchmarks :: Bool pkgHashHaddockInternal :: Bool pkgHashHaddockCss :: Maybe FilePath pkgHashHaddockLinkedSource :: Bool pkgHashHaddockQuickJump :: Bool pkgHashHaddockContents :: Maybe PathTemplate pkgHashHaddockIndex :: Maybe PathTemplate pkgHashHaddockBaseUrl :: Maybe String pkgHashHaddockLib :: Maybe String pkgHashHaddockOutputDir :: Maybe FilePath

#### Instances

Instances details

Show PackageHashConfigInputs # |
Instance details Defined in Distribution.Client.PackageHash Methods showsPrec :: Int -> PackageHashConfigInputs -> ShowS # show :: PackageHashConfigInputs -> String # showList :: [PackageHashConfigInputs] -> ShowS #

type PackageSourceHash = HashValue #

hashedInstalledPackageId :: PackageHashInputs -> InstalledPackageId #

Calculate a `InstalledPackageId` for a package using our nix-style inputs hashing method.

Note that due to path length limitations on Windows, this function uses a different method on Windows that produces shorted package ids. See `hashedInstalledPackageIdLong` vs `hashedInstalledPackageIdShort`.

hashPackageHashInputs :: PackageHashInputs -> HashValue #

Calculate the overall hash to be used for an `InstalledPackageId`.

renderPackageHashInputs :: PackageHashInputs -> ByteString #

Render a textual representation of the `PackageHashInputs`.

The `hashValue` of this text is the overall package hash.

## Platform-specific variations

hashedInstalledPackageIdLong :: PackageHashInputs -> InstalledPackageId #

Calculate a `InstalledPackageId` for a package using our nix-style inputs hashing method.

This produces large ids with big hashes. It is only suitable for systems without significant path length limitations (ie not Windows).

hashedInstalledPackageIdShort :: PackageHashInputs -> InstalledPackageId #

On Windows we have serious problems with path lengths. Windows imposes a maximum path length of 260 chars, and even if we can use the windows long path APIs ourselves, we cannot guarantee that ghc, gcc, ld, ar, etc etc all do so too.

So our only choice is to limit the lengths of the paths, and the only real way to do that is to limit the size of the `InstalledPackageId`s that we generate. We do this by truncating the package names and versions and also by truncating the hash sizes.

Truncating the package names and versions is technically ok because they are just included for human convenience, the full source package id is included in the hash.

Truncating the hash size is disappointing but also technically ok. We rely on the hash primarily for collision avoidance not for any security properties (at least for now).