SOH_2023-Structured errors and error codes for cabal-install

 Structured errors and Error codes for Cabal-Install - SoH '23


Contributor  :  Suganya Raju

Mentor          :  Gershom Bazerman


The Haskell error Index site https://errors.haskell.org/ describes the error messages produced by the various Haskell related tools.

This project is to refactor the cabal codebase to provide structured errors rather than mere strings, and also assign codes to corresponding cabal errors that can be added to the error index. In the same vein as GHC and other Haskell related tools, the work of this project is moving away from the current way of signaling errors with `die'` to something that allows more structure. The end goal is to have package-specific error data types, where each constructor of such a data type will represent one error corresponding to the error that the module can throw.


Benefits of Structured Errors:

  • Users have an easier time contributing documentation for how to work around various situations that may arise, so more docs may exist.


  • Error messages gain a notion of identity that allows them to be rephrased without breaking all docs.

  • Interactive tools that invoke Cabal and GHC can link to one consistent, predictable location if an error message occurs, and new users don't have to figure out which tool is the source of the error.

Outcome of this Project :
Existing Error Infrastructure:

Core Changes in the New Infrastructure:

  • New sum types CabalException and CabalInstallException are created.


  • The die’ function is replaced with a new function dieWithException.


  • A new datatype “VerboseException a” is created which is polymorphic over “CabalException” and “CabalInstallException”

  • Each error message is assigned a unique code of the form [Cabal -1234].






So far all the errors in the modules Cabal and Cabal- Install have been moved to the new representation
 and the work has been committed to the upstream repository.

List of Exceptions and Error codes :

I am listing all the Error codes I have used as part of the project for future reference.

List of Cabal Package Exception:

  1.   NoBenchMarkProgram                   = 1678
  2.   EnableBenchMark                       = 1453
  3.   BenchMarkNameDisabled                            = 2781
  4.   NoBenchMark                       = 1654
  5.   NoLibraryFound                   = 2546
  6.   CompilerNotInstalled             = 7465
  7.   CantFindIncludeFile               = 3876
  8.   UnsupportedTestSuite               = 3245
  9.   UnsupportedBenchMark             = 9123
  10.   NoIncludeFileFound               = 2987
  11.   NoModuleFound                     = 6421
  12.   RegMultipleInstancePkg           = 3421
  13.   SuppressingChecksOnFile            = 5436
  14.   NoSupportDirStylePackageDb        = 2980
  15.   OnlySupportSpecificPackageDb      = 6547
  16.   FailedToParseOutputDescribe       = 7218
  17.   DumpFailed                       = 6736
  18.   FailedToParseOutputDump           = 9076
  19.   ListFailed                       = 5109
  20.   FailedToParseOutputList           = 7650
  21.   ProgramNotFound                   = 4123
  22.   NoSupportForHoogle               = 8706
  23.   NoSupportForQuickJumpFlag         = 7086
  24.   NoGHCVersionFromHaddock           = 5045
  25.   NoGHCVersionFromCompiler          = 4098
  26.   HaddockAndGHCVersionDoesntMatch = 1998
  27.   MustHaveSharedLibraries           = 6032
  28.   HaddockPackageFlags               = 4569
  29.   UnknownCompilerFlavor             = 3102
  30.   FailedToDetermineTarget           = 5049
  31.   NoMultipleTargets                 = 6091
  32.   REPLNotSupported                 = 1098
  33.   NoSupportBuildingTestSuite       = 4106
  34.   NoSupportBuildingBenchMark       = 5320
  35.   BuildingNotSupportedWithCompiler = 7077
  36.   ProvideHaskellSuiteTool           = 7509
  37.   CannotDetermineCompilerVersion   = 4519
  38.   PkgDumpFailed                     = 2291
  39.   FailedToParseOutput               = 5500
  40.   CantFindSourceModule             = 8870
  41.   VersionMismatchJS                 = 9001
  42.   VersionMismatchGHCJS             = 4001
  43.   GlobalPackageDBLimitation         = 5002
  44.   GlobalPackageDBSpecifiedFirst     = 3901
  45.   MatchDirFileGlob                 = 9760
  46.   MatchDirFileGlobErrors           = 6661
  47.   ErrorParsingFileDoesntExist       = 1234
  48.   FailedParsing                     = 6565
  49.   NotFoundMsg                       = 8011
  50.   UnrecognisedBuildTarget           = 3410
  51.   ReportBuildTargetProblems         = 5504
  52.   UnknownBuildTarget               = 4444
  53.   AmbiguousBuildTarget              = 7865
  54.   CheckBuildTargets                 = 4733
  55.   VersionMismatchGHC               = 4000
  56.   CheckPackageDbStackPost76         = 3000
  57.   CheckPackageDbStackPre76         = 5640
  58.   GlobalPackageDbSpecifiedFirst     = 2345
  59.   CantInstallForeignLib             = 8221
  60.   NoSupportForPreProcessingTest     = 3008
  61.   NoSupportForPreProcessingBenchmark  = 6990
  62.   CantFindSourceForPreProcessFile     = 7554
  63.   NoSupportPreProcessingTestExtras   = 7886
  64.   NoSupportPreProcessingBenchmarkExtras = 9999
  65.   UnlitException                   = 5454
  66.   RunProgramInvocationException     = 8012
  67.   GetProgramInvocationException     = 7300
  68.   GetProgramInvocationLBSException = 6578
  69.   CheckSemaphoreSupport           = 2002
  70.   NoLibraryForPackage               = 8004
  71.   SanityCheckHookedBuildInfo       = 6007
  72.   ConfigureScriptNotFound           = 4567
  73.   NoValidComponent                 = 5680
  74.   ConfigureEitherSingleOrAll       = 2001
  75.   ConfigCIDValidForPreComponent     = 7006
  76.   SanityCheckForEnableComponents   = 5004
  77.   SanityCheckForDynamicStaticLinking     = 4007
  78.   UnsupportedLanguages              = 8074
  79.   UnsupportedLanguageExtension = 5656
  80.   CantFindForeignLibraries          = 4574
  81.   ExpectedAbsoluteDirectory         = 6662
  82.   FlagsNotSpecified                 = 9080
  83.   EncounteredMissingDependency     = 8010
  84.   CompilerDoesn'tSupportThinning   = 4003
  85.   CompilerDoesn'tSupportReexports   = 3456
  86.   CompilerDoesn'tSupportBackpack   = 5446
  87.   LibraryWithinSamePackage          = 7007
  88.   ReportFailedDependencies          = 4321
  89.   NoPackageDatabaseSpecified       = 2300
  90.   HowToFindInstalledPackages       = 3003
  91.   PkgConfigNotFound                 = 7123
  92.   BadVersion                       = 7600
  93.   UnknownCompilerException          = 3022
  94.   NoWorkingGcc                     = 1088
  95.   NoOSSupport                       = 3339
  96.   NoCompilerSupport                 = 2290
  97.   InstallDirsNotPrefixRelative      = 6000
  98.   ExplainErrors                     = 4345
  99.   CheckPackageProblems             = 5559
  100.   LibDirDepsPrefixNotRelative       = 6667
  101.   CombinedConstraints               = 5000
  102.   CantParseGHCOutput = 1980
  103.   IncompatibleWithCabal             = 8123
  104.   Couldn'tFindTestProgram           = 5678
  105.   TestCoverageSupport = 7890
  106.   Couldn'tFindTestProgLibV09       = 9012
  107.   TestCoverageSupportLibV09         = 1076
  108.   RawSystemStdout                   = 3098
  109.   FindFileCwd                     = 4765
  110.   FindFileEx = 2115
  111.   FindModuleFileEx = 6663
  112.   MultipleFilesWithExtension = 3333
  113.   NoDesc = 7654
  114.   MultiDesc = 5554
  115.   RelocRegistrationInfo = 4343
  116.   CreatePackageDB = 6787
  117.   WithHcPkg = 9876
  118.   RegisMultiplePkgNotSupported = 7632
  119.   RegisteringNotImplemented = 5411
  120.   NoTestSuitesEnabled = 9061
  121.   TestNameDisabled = 8210
  122.   NoSuchTest = 8000
  123.   ConfigureProgram = 5490
  124.   RequireProgram = 6666
  125.   NoProgramFound = 7620
  126.   BadVersionDb = 8038
  127.   UnknownVersionDb = 1008
List of Cabal Install Package Exceptions:
  1.   UnpackGet                               = 7013
  2.   NotTarballDir                             = 7012
  3.   DirectoryAlreadyExists                   = 7014
  4.   FileExists                               = 7015
  5.   FileAlreadyExists                         = 7016
  6.   DirectoryExists                           = 7017
  7.   SplitRunArgs                              = 7018
  8.   CouldNotFindExecutable                   = 7019
  9.   FoundMultipleMatchingExes                 = 7020
  10.   NoRemoteRepositories                      = 7021
  11.   NotATarDotGzFile                         = 7022
  12.   ExpectedMatchingFileName = 7023
  13.   NoTargetProvided                         = 7024
  14.   OneTargetRequired                         = 7025
  15.   ThisIsABug                                = 7026
  16.   NoOrMultipleTargetsGiven                  = 7027
  17.   NoTargetFound                             = 7028
  18.   MultipleTargetsFound                      = 7029
  19.   UnexpectedNamedPkgSpecifiers             = 7030
  20.   UnexpectedSourcePkgSpecifiers             = 7031
  21.   UnableToPerformInplaceUpdate              = 7032
  22.   EmptyValuePagerEnvVariable              = 7033
  23.   FileDoesntExist                          = 7034
  24.   ParseError                               = 7035
  25.   CabalFileNotFound                         = 7036
  26.   FindOpenProgramLocationErr               = 7037
  27.   PkgConfParseFailed                       = 7038
  28.   ErrorPackingSdist                         = 7039
  29.   SdistException                           = 7040
  30.   SpecifyAnExecutable                       = 7041
  31.   TestCommandDoesn'tSupport                 = 7042
  32.   ReportTargetProblems                      = 7043
  33.   ListBinTargetException                   = 7044
  34.   ResolveWithoutDependency                 = 7045
  35.   CannotReadCabalFile                       = 7046
  36.   ErrorUpdatingIndex                       = 7047
  37.   InternalError                             = 7048
  38.   ReadIndexCache                            = 7049
  39.   ConfigStateFileException               = 7050
  40.   UploadAction                             = 7051
  41.   UploadActionDocumentation                 = 7052
  42.   UploadActionOnlyArchives                 = 7053
  43.   FileNotFound                             = 7054
  44.   CheckAction                              = 7055
  45.   ReportAction                             = 7056
  46.   InitAction                               = 7057
  47.   UserConfigAction                         = 7058
  48.   SpecifySubcommand                         = 7059
  49.   UnknownUserConfigSubcommand               = 7060
  50.   ManpageAction                             = 7061
  51.   UnrecognizedResponse                     = 7062
  52.   CheckTarget                               = 7063
  53.   FetchPackage                             = 7064
  54.   PlanPackages                             = 7065
  55.   NoSupportForRunCommand                   = 7066
  56.   RunPhaseReached                           = 7067
  57.   UnknownExecutable                         = 7068
  58.   MultipleMatchingExecutables               = 7069
  59.   CmdRunReportTargetProblems               = 7070
  60.   CleanAction                             = 7071
  61.   ReportCannotPruneDependencies             = 7072
  62.   ReplCommandDoesn'tSupport                 = 7073
  63.   ReplTakesNoArguments                      = 7074
  64.   ReplTakesSingleArgument                   = 7075
  65.   RenderReplTargetProblem                 = 7076
  66.   GetPkgList                               = 7078
  67.   GatherPkgInfo                             = 7079
  68.   UnableToParseRepo                         = 7080
  69.   NullUnknownrepos                         = 7081
  70.   UpdateSetupScript                         = 7082
  71.   InstalledCabalVersion                     = 7083
  72.   FailNoConfigFile                         = 7084
  73.   ParseFailedErr                           = 7085
  74.   ParseExtraLinesFailedErr                 = 7087
  75.   ParseExtraLinesOkError                   = 7088
  76.   FetchPackageErr                           = 7089
  77.   ReportParseResult                         = 7090
  78.   ReportSourceRepoProblems                  = 7091
  79.   BenchActionException                     = 7092
  80.   RenderBenchTargetProblem                  = 7093
  81.   ReportUserTargetProblems                 = 7094
  82.   ReportUserTargerNonexistantFile           = 7095
  83.   ReportUserTargetUnexpectedFile           = 7096
  84.   ReportUserTargetUnexpectedUriScheme       = 7097
  85.   ReportUserTargetUnrecognisedUri           = 7098
  86.   ReadTarballPackageTarget                 = 7099
  87.   ReportPackageTargetProblems               = 7100
  88.   PackageNameAmbiguousErr                   = 7101
  89.   ExtractTarballPackageErr                 = 7102
  90.   OutdatedAction                           = 7103
  91.   FreezeFileExistsErr                     = 7104
  92.   FinalizePDFailed                         = 7105
  93.   ProjectTargetSelector                     = 7106
  94.   PhaseRunSolverErr                         = 7107
  95.   HaddockCommandDoesn'tSupport             = 7108
  96.   CannotParseURIFragment                   = 7109
  97.   MakeDownload                             = 7110
  98.   FailedToDownloadURI                       = 7111
  99.   RemoteRepoCheckHttps                     = 7112
  100.   TransportCheckHttps                       = 7113
  101.   NoPostYet                                 = 7114
  102.   WGetServerError                           = 7115
  103.   Couldn'tEstablishHttpConnection           = 7116
  104.   StatusParseFail                           = 7117
  105.   TryUpgradeToHttps                         = 7118
  106.   UnknownHttpTransportSpecified             = 7119
  107.   CmdHaddockReportTargetProblems           = 7120
  108.   FailedExtractingScriptBlock               = 7121
  109.   FreezeAction                             = 7122
  110.   TryFindPackageDescErr                     = 7124
  111.   DieIfNotHaddockFailureException           = 7125
  112.   ConfigureInstallInternalError             = 7126
  113.   CmdErrorMessages                         = 7127
  114.   ReportTargetSelectorProblems             = 7128
  115.   UnrecognisedTarget                       = 7129
  116.   NoSuchTargetSelectorErr                   = 7131
  117.   TargetSelectorAmbiguousErr                = 7132
  118.   TargetSelectorNoCurrentPackageErr         = 7133
  119.   TargetSelectorNoTargetsInCwdTrue         = 7134
  120.   TargetSelectorNoTargetsInCwdFalse = 7135
  121.   TargetSelectorNoTargetsInProjectErr       = 7136
  122.   TargetSelectorNoScriptErr                 = 7137
  123.   MatchingInternalErrorErr                 = 7130
  124.   ReportPlanningFailure                     = 7138
  125.   Can'tDownloadPackagesOffline             = 7139
  126.   SomePackagesFailedToInstall               = 7140
  127.   PackageDotCabalFileNotFound               = 7141
  128.   PkgConfParsedFailed                       = 7142
  129.   BrokenException                       = 7143
  130.   WithoutProject                           = 7144
  131.   PackagesAlreadyExistInEnvfile             = 7145
  132.   ConfigTests                               = 7146
  133.   ConfigBenchmarks                         = 7147
  134.   UnknownPackage                           = 7148
  135.   InstallUnitExes                           = 7149
  136.   SelectComponentTargetError               = 7150
  137.   SdistActionException                     = 7151
  138.   Can'tWriteMultipleTarballs               = 7152
  139.   ImpossibleHappened                       = 7153
  140.   CannotConvertTarballPackage               = 7154
  141.   Win32SelfUpgradeNotNeeded                 = 7155
  142.   FreezeException                           = 7156
  143.   PkgSpecifierException                     = 7157
  144.   CorruptedIndexCache                       = 7158
PR Links :


Future Work:

  • One instance of die' in Cabal/src/Distribution/Program/Run.hs is not replaced with the new dieWithException function. This change started giving a windows specific error and couldn't pass the CI. Future work on this will be to replace the die' function and identify the CI-Windows error.
  • The error codes that we have generated as part of this project will have to be added to the Haskell error Index.

Challenges and Learnings:

The major challenge that I faced initially was understanding the logic within the code that was written by other contributors. Since this was my first time contributing to an open source project, it took me some time to get familiar with the overall process.


I would say that Summer of Haskell has introduced me to the world of open source and given me the joy of being a part of something huge. I have evolved to become a better programmer in the last 22 weeks, and look forward to continue contributing.

Gratitude:

I am extremely grateful to the Haskell Community for their support throughout this journey.
This would have not been possible without the support and nurturing of Gershom Bazerman.
I would like to extend my sincere thanks to Artem Pelenitsyn for his advice and help on this project.   

Comments

Post a Comment