Distribution.PackageDescription.Check

This has code for checking for various problems in packages. There is one set of checks that just looks at a PackageDescription in isolation and another set of checks that also looks at files in the package. Some of the checks are basic sanity checks, others are portability standards that we'd like to encourage. There is a PackageCheck type that distinguishes the different kinds of checks so we can see which ones are appropriate to report in different situations. This code gets used when configuring a package when we consider only basic problems. The higher standard is used when preparing a source tarball and by Hackage when uploading new packages. The reason for this is that we want to hold packages that are expected to be distributed to a higher standard than packages that are only ever expected to be used on the author's own environment.

Package Checking

data CheckExplanation

Explanations of PackageCheck's errors/warnings.

Constructors

ParseWarning FilePath PWarning

NoNameField

NoVersionField

NoTarget

UnnamedInternal

DuplicateSections [UnqualComponentName]

IllegalLibraryName PackageName

NoModulesExposed LibraryName

SignaturesCabal2

AutogenNotExposed

AutogenIncludesNotIncluded

NoMainIs UnqualComponentName

NoHsLhsMain

MainCCabal1_18

AutogenNoOther CEType

AutogenIncludesNotIncludedExe

TestsuiteTypeNotKnown TestType

TestsuiteNotSupported TestType

BenchmarkTypeNotKnown BenchmarkType

BenchmarkNotSupported BenchmarkType

NoHsLhsMainBench

InvalidNameWin PackageName

ZPrefix

NoBuildType

NoCustomSetup

UnknownCompilers [String]

UnknownLanguages [String]

UnknownExtensions [String]

LanguagesAsExtension [String]

DeprecatedExtensions [(Extension, Maybe Extension)]

MissingFieldCategory

MissingFieldMaintainer

MissingFieldSynopsis

MissingFieldDescription

MissingFieldSynOrDesc

SynopsisTooLong

ShortDesc

InvalidTestWith [Dependency]

ImpossibleInternalDep [Dependency]

ImpossibleInternalExe [ExeDependency]

MissingInternalExe [ExeDependency]

NONELicense

NoLicense

AllRightsReservedLicense

LicenseMessParse License

UnrecognisedLicense String

UncommonBSD4

UnknownLicenseVersion License [Version]

NoLicenseFile

UnrecognisedSourceRepo String

MissingType

MissingLocation

GitProtocol

MissingModule

MissingTag

SubdirRelPath

SubdirGoodRelPath String

OptFasm String

OptHpc String

OptProf String

OptO String

OptHide String

OptMake String

OptONot String

OptOOne String

OptOTwo String

OptSplitSections String

OptSplitObjs String

OptWls String

OptExts String

OptRts String

OptWithRts String

COptONumber String WarnLang

COptCPP String

OptAlternatives String String [(String, String)]

RelativeOutside String FilePath

AbsolutePath String FilePath

BadRelativePath String FilePath String

DistPoint (Maybe String) FilePath

GlobSyntaxError String String

RecursiveGlobInRoot String FilePath

InvalidOnWin [FilePath]

FilePathTooLong FilePath

FilePathNameTooLong FilePath

FilePathSplitTooLong FilePath

FilePathEmpty

CVTestSuite

CVDefaultLanguage

CVDefaultLanguageComponent

CVDefaultLanguageComponentSoft

CVExtraDocFiles

CVMultiLib

CVReexported

CVMixins

CVExtraFrameworkDirs

CVDefaultExtensions

CVExtensionsDeprecated

CVSources

CVExtraDynamic [[String]]

CVVirtualModules

CVSourceRepository

CVExtensions CabalSpecVersion [Extension]

CVCustomSetup

CVExpliticDepsCustomSetup

CVAutogenPaths

CVAutogenPackageInfo

CVAutogenPackageInfoGuard

GlobNoMatch String String

GlobExactMatch String String FilePath

GlobNoDir String String FilePath

UnknownOS [String]

UnknownArch [String]

UnknownCompiler [String]

BaseNoUpperBounds

MissingUpperBounds CEType [String]

SuspiciousFlagName [String]

DeclaredUsedFlags (Set FlagName) (Set FlagName)

NonASCIICustomField [String]

RebindableClashPaths

RebindableClashPackageInfo

WErrorUnneeded String

JUnneeded String

FDeferTypeErrorsUnneeded String

DynamicUnneeded String

ProfilingUnneeded String

UpperBoundSetup String

DuplicateModule String [ModuleName]

PotentialDupModule String [ModuleName]

BOMStart FilePath

NotPackageName FilePath String

NoDesc

MultiDesc [String]

UnknownFile String (RelativePath Pkg File)

MissingSetupFile

MissingConfigureScript

UnknownDirectory String FilePath

MissingSourceControl

MissingExpectedDocFiles Bool [FilePath]

WrongFieldForExpectedDocFiles Bool String [FilePath]

Instances

Show CheckExplanation

Defined in Distribution.PackageDescription.Check.Warning

Methods

showsPrec :: Int -> CheckExplanation -> ShowS

show :: CheckExplanation -> String

showList :: [CheckExplanation] -> ShowS

Eq CheckExplanation

Defined in Distribution.PackageDescription.Check.Warning

Methods

(==) :: CheckExplanation -> CheckExplanation -> Bool

(/=) :: CheckExplanation -> CheckExplanation -> Bool

Ord CheckExplanation

Defined in Distribution.PackageDescription.Check.Warning

Methods

compare :: CheckExplanation -> CheckExplanation -> Ordering

(<) :: CheckExplanation -> CheckExplanation -> Bool

(<=) :: CheckExplanation -> CheckExplanation -> Bool

(>) :: CheckExplanation -> CheckExplanation -> Bool

(>=) :: CheckExplanation -> CheckExplanation -> Bool

max :: CheckExplanation -> CheckExplanation -> CheckExplanation

min :: CheckExplanation -> CheckExplanation -> CheckExplanation

data CheckExplanationID

Identifier for the speficic CheckExplanation. This ensures `--ignore` can output a warning on unrecognised values. ☞ N.B.: should be kept in sync with CheckExplanation.

Instances

Bounded CheckExplanationID

Defined in Distribution.PackageDescription.Check.Warning

Methods

minBound :: CheckExplanationID

maxBound :: CheckExplanationID

Enum CheckExplanationID

Defined in Distribution.PackageDescription.Check.Warning

Methods

succ :: CheckExplanationID -> CheckExplanationID

pred :: CheckExplanationID -> CheckExplanationID

toEnum :: Int -> CheckExplanationID

fromEnum :: CheckExplanationID -> Int

enumFrom :: CheckExplanationID -> [CheckExplanationID]

enumFromThen :: CheckExplanationID -> CheckExplanationID -> [CheckExplanationID]

enumFromTo :: CheckExplanationID -> CheckExplanationID -> [CheckExplanationID]

enumFromThenTo :: CheckExplanationID -> CheckExplanationID -> CheckExplanationID -> [CheckExplanationID]

Show CheckExplanationID

Defined in Distribution.PackageDescription.Check.Warning

Methods

showsPrec :: Int -> CheckExplanationID -> ShowS

show :: CheckExplanationID -> String

showList :: [CheckExplanationID] -> ShowS

Eq CheckExplanationID

Defined in Distribution.PackageDescription.Check.Warning

Methods

(==) :: CheckExplanationID -> CheckExplanationID -> Bool

(/=) :: CheckExplanationID -> CheckExplanationID -> Bool

Ord CheckExplanationID

Defined in Distribution.PackageDescription.Check.Warning

Methods

compare :: CheckExplanationID -> CheckExplanationID -> Ordering

(<) :: CheckExplanationID -> CheckExplanationID -> Bool

(<=) :: CheckExplanationID -> CheckExplanationID -> Bool

(>) :: CheckExplanationID -> CheckExplanationID -> Bool

(>=) :: CheckExplanationID -> CheckExplanationID -> Bool

max :: CheckExplanationID -> CheckExplanationID -> CheckExplanationID

min :: CheckExplanationID -> CheckExplanationID -> CheckExplanationID

type CheckExplanationIDString = String

data PackageCheck

Results of some kind of failed package check.

There are a range of severities, from merely dubious to totally insane. All of them come with a human readable explanation. In future we may augment them with more machine readable explanations, for example to help an IDE suggest automatic corrections.

Constructors

PackageBuildImpossible

This package description is no good. There's no way it's going to build sensibly. This should give an error at configure time.

Fields

• explanation :: CheckExplanation

PackageBuildWarning

A problem that is likely to affect building the package, or an issue that we'd like every package author to be aware of, even if the package is never distributed.

Fields

• explanation :: CheckExplanation

PackageDistSuspicious

An issue that might not be a problem for the package author but might be annoying or detrimental when the package is distributed to users. We should encourage distributed packages to be free from these issues, but occasionally there are justifiable reasons so we cannot ban them entirely.

Fields

• explanation :: CheckExplanation

PackageDistSuspiciousWarn

Like PackageDistSuspicious but will only display warnings rather than causing abnormal exit when you run 'cabal check'.

Fields

• explanation :: CheckExplanation

PackageDistInexcusable

An issue that is OK in the author's environment but is almost certain to be a portability problem for other environments. We can quite legitimately refuse to publicly distribute packages with these problems.

Fields

• explanation :: CheckExplanation

Instances

Show PackageCheck

Broken Show instance (not bijective with Read), alas external packages depend on it.

Defined in Distribution.PackageDescription.Check.Warning

Methods

showsPrec :: Int -> PackageCheck -> ShowS

show :: PackageCheck -> String

showList :: [PackageCheck] -> ShowS

Eq PackageCheck

Defined in Distribution.PackageDescription.Check.Warning

Methods

(==) :: PackageCheck -> PackageCheck -> Bool

(/=) :: PackageCheck -> PackageCheck -> Bool

Ord PackageCheck

Defined in Distribution.PackageDescription.Check.Warning

Methods

compare :: PackageCheck -> PackageCheck -> Ordering

(<) :: PackageCheck -> PackageCheck -> Bool

(<=) :: PackageCheck -> PackageCheck -> Bool

(>) :: PackageCheck -> PackageCheck -> Bool

(>=) :: PackageCheck -> PackageCheck -> Bool

max :: PackageCheck -> PackageCheck -> PackageCheck

min :: PackageCheck -> PackageCheck -> PackageCheck

checkPackage :: GenericPackageDescription -> [PackageCheck]

Check for common mistakes and problems in package descriptions.

This is the standard collection of checks covering all aspects except for checks that require looking at files within the package. For those see checkPackageFiles.

checkConfiguredPackage :: PackageDescription -> [PackageCheck]

This function is an oddity due to the historical GenericPackageDescription/PackageDescription split. It is only maintained not to break interface, use checkPackage if possible.

wrapParseWarning :: FilePath -> PWarning -> PackageCheck

Wraps ParseWarning into PackageCheck.

ppPackageCheck :: PackageCheck -> String

Pretty printing PackageCheck.

ppCheckExplanationId :: CheckExplanationID -> CheckExplanationIDString

isHackageDistError :: PackageCheck -> Bool

Would Hackage refuse a package because of this error?

filterPackageChecksById

Arguments

:: [PackageCheck]

Original checks.

-> [CheckExplanationID]

IDs to omit.

-> [PackageCheck]

Filter Package Check by CheckExplanationID.

filterPackageChecksByIdString

Arguments

:: [PackageCheck]

Original checks.

-> [CheckExplanationIDString]

IDs to omit, in String format.

-> ([PackageCheck], [CheckExplanationIDString])

Filter Package Check by Check explanation string.

Checking package contents

checkPackageFiles :: Verbosity -> PackageDescription -> FilePath -> IO [PackageCheck]

Same as checkPackageFilesGPD, but working with PackageDescription.

This function is included for legacy reasons, use checkPackageFilesGPD if you are working with GenericPackageDescription.

checkPackageFilesGPD :: Verbosity -> GenericPackageDescription -> FilePath -> IO [PackageCheck]

Sanity checks that require IO. checkPackageFiles looks at the files in the package and expects to find the package unpacked at the given filepath.

checkPackageContent :: Monad m => CheckPackageContentOps m -> GenericPackageDescription -> m [PackageCheck]

Sanity check things that requires looking at files in the package. This is a generalised version of checkPackageFiles that can work in any monad for which you can provide CheckPackageContentOps operations.

The point of this extra generality is to allow doing checks in some virtual file system, for example a tarball in memory.

data CheckPackageContentOps m

A record of operations needed to check the contents of packages. Abstracted over m to provide flexibility (could be IO, a .tar.gz file, etc).

Constructors

CheckPackageContentOps

Fields

• doesFileExist :: FilePath -> m Bool
• doesDirectoryExist :: FilePath -> m Bool
• getDirectoryContents :: FilePath -> m [FilePath]
• getFileContents :: FilePath -> m ByteString