clarify "configure" messages from Cabal (#9476)

* clarify "configure" messages from Cabal * add changelog * Apply suggestions from code review Co-authored-by: Javier Sagredo <[email protected]> --------- Co-authored-by: Javier Sagredo <[email protected]> Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
haskell · Aug 3, 2024 · f203a2c · f203a2c
1 parent e931ca1
commit f203a2c
Show file tree

Hide file tree

Showing 3 changed files with 42 additions and 30 deletions.
diff --git a/Cabal/src/Distribution/Simple/Configure.hs b/Cabal/src/Distribution/Simple/Configure.hs
@@ -208,20 +208,20 @@ data ConfigStateFileError
 dispConfigStateFileError :: ConfigStateFileError -> Doc
 dispConfigStateFileError ConfigStateFileNoHeader =
   text "Saved package config file header is missing."
-    <+> text "Re-run the 'configure' command."
+    <+> text "Re-run the 'Setup configure' command."
 dispConfigStateFileError ConfigStateFileBadHeader =
   text "Saved package config file header is corrupt."
-    <+> text "Re-run the 'configure' command."
+    <+> text "Re-run the 'Setup configure' command."
 dispConfigStateFileError ConfigStateFileNoParse =
   text "Saved package config file is corrupt."
-    <+> text "Re-run the 'configure' command."
+    <+> text "Re-run the 'Setup configure' command."
 dispConfigStateFileError ConfigStateFileMissing{} =
-  text "Run the 'configure' command first."
+  text "Run the 'Setup configure' command first."
 dispConfigStateFileError (ConfigStateFileBadVersion oldCabal oldCompiler _) =
   text "Saved package config file is outdated:"
     $+$ badCabal
     $+$ badCompiler
-    $+$ text "Re-run the 'configure' command."
+    $+$ text "Re-run the 'Setup configure' command."
   where
     badCabal =
       text "• the Cabal version changed from"

diff --git a/Cabal/src/Distribution/Simple/Errors.hs b/Cabal/src/Distribution/Simple/Errors.hs
@@ -314,7 +314,7 @@ versionRequirement range
 exceptionMessage :: CabalException -> String
 exceptionMessage e = case e of
   NoBenchMarkProgram cmd -> "Could not find benchmark program \"" ++ cmd ++ "\". Did you build the package first?"
-  EnableBenchMark -> "No benchmarks enabled. Did you remember to configure with " ++ "\'--enable-benchmarks\'?"
+  EnableBenchMark -> "No benchmarks enabled. Did you remember to \'Setup configure\' with " ++ "\'--enable-benchmarks\'?"
   BenchMarkNameDisabled bmName -> "Package configured with benchmark " ++ bmName ++ " disabled."
   NoBenchMark bmName -> "no such benchmark: " ++ bmName
   NoLibraryFound -> "No executables and no library found. Nothing to do."
@@ -331,8 +331,8 @@ exceptionMessage e = case e of
       ++ ".\n"
       ++ "If the module "
       ++ "is autogenerated it should be added to 'autogen-modules'."
-  RegMultipleInstancePkg -> "HcPkg.register: the compiler does not support,registering multiple instances of packages."
-  SuppressingChecksOnFile -> "HcPkg.register: the compiler does not support ,suppressing checks on files."
+  RegMultipleInstancePkg -> "HcPkg.register: the compiler does not support registering multiple instances of packages."
+  SuppressingChecksOnFile -> "HcPkg.register: the compiler does not support suppressing checks on files."
   NoSupportDirStylePackageDb -> "HcPkg.writeRegistrationFileDirectly: compiler does not support dir style package dbs"
   OnlySupportSpecificPackageDb -> "HcPkg.writeRegistrationFileDirectly: only supports SpecificPackageDB for now"
   FailedToParseOutputDescribe programId pkgId -> "failed to parse output of '" ++ programId ++ " describe " ++ prettyShow pkgId ++ "'"
@@ -353,7 +353,7 @@ exceptionMessage e = case e of
       ++ " but "
       ++ "haddock is using GHC version "
       ++ prettyShow haddockGhcVersion
-  MustHaveSharedLibraries -> "Must have vanilla or shared libraries " ++ "enabled in order to run haddock"
+  MustHaveSharedLibraries -> "Must have vanilla or shared libraries enabled in order to run haddock"
   HaddockPackageFlags inf ->
     "internal error when calculating transitive "
       ++ "package dependencies.\nDebug info: "
@@ -391,7 +391,7 @@ exceptionMessage e = case e of
   GlobalPackageDBLimitation ->
     "With current ghc versions the global package db is always used "
       ++ "and must be listed first. This ghc limitation may be lifted in "
-      ++ "future, see https://gitlab.haskell.org/ghc/ghc/-/issues/5977"
+      ++ "the future, see https://gitlab.haskell.org/ghc/ghc/-/issues/5977"
   GlobalPackageDBSpecifiedFirst ->
     "If the global package db is specified, it must be "
       ++ "specified first and cannot be specified multiple times"
@@ -487,8 +487,7 @@ exceptionMessage e = case e of
       ++ "suite type "
       ++ prettyShow tt
   NoSupportForPreProcessingBenchmark tt ->
-    "No support for preprocessing benchmark "
-      ++ "type "
+    "No support for preprocessing benchmark type "
       ++ prettyShow tt
   CantFindSourceForPreProcessFile errorStr -> errorStr
   NoSupportPreProcessingTestExtras tt ->
@@ -511,11 +510,11 @@ exceptionMessage e = case e of
   SanityCheckHookedBuildInfo exe1 ->
     "The buildinfo contains info for an executable called '"
       ++ prettyShow exe1
-      ++ "' but the package does not have a "
+      ++ "' but the package does not have an "
       ++ "executable with that name."
   ConfigureScriptNotFound fp -> "configure script not found at " ++ fp ++ "."
   NoValidComponent -> "No valid component targets found"
-  ConfigureEitherSingleOrAll -> "Can only configure either single component or all of them"
+  ConfigureEitherSingleOrAll -> "Can only configure either a single component or all of them"
   ConfigCIDValidForPreComponent -> "--cid is only supported for per-component configure"
   SanityCheckForEnableComponents ->
     "--enable-tests/--enable-benchmarks are incompatible with"
@@ -525,23 +524,23 @@ exceptionMessage e = case e of
       ++ " are incompatible with each other."
   UnsupportedLanguages pkgId compilerId langs ->
     "The package "
-      ++ prettyShow (pkgId)
+      ++ prettyShow pkgId
       ++ " requires the following languages which are not "
       ++ "supported by "
-      ++ prettyShow (compilerId)
+      ++ prettyShow compilerId
       ++ ": "
       ++ intercalate ", " langs
   UnsupportedLanguageExtension pkgId compilerId exts ->
     "The package "
-      ++ prettyShow (pkgId)
+      ++ prettyShow pkgId
       ++ " requires the following language extensions which are not "
       ++ "supported by "
-      ++ prettyShow (compilerId)
+      ++ prettyShow compilerId
       ++ ": "
       ++ intercalate ", " exts
   CantFindForeignLibraries unsupportedFLibs ->
     "Cannot build some foreign libraries: "
-      ++ intercalate "," unsupportedFLibs
+      ++ intercalate ", " unsupportedFLibs
   ExpectedAbsoluteDirectory fPath -> "expected an absolute directory name for --prefix: " ++ fPath
   FlagsNotSpecified diffFlags ->
     "'--exact-configuration' was given, "
@@ -572,7 +571,7 @@ exceptionMessage e = case e of
       ++ "' refers to a library which is defined within the same "
       ++ "package. To use this feature the package must specify at "
       ++ "least 'cabal-version: >= 1.8'."
-  ReportFailedDependencies failed hackageUrl -> (intercalate "\n\n" (map reportFailedDependency failed))
+  ReportFailedDependencies failed hackageUrl -> intercalate "\n\n" (map reportFailedDependency failed)
     where
       reportFailedDependency (DependencyNotExists pkgname) =
         "there is no version of "
@@ -617,7 +616,7 @@ exceptionMessage e = case e of
   NoWorkingGcc ->
     unlines
       [ "No working gcc"
-      , "This package depends on foreign library but we cannot "
+      , "This package depends on a foreign library but we cannot "
           ++ "find a working C compiler. If you have it in a "
           ++ "non-standard location you can use the --with-gcc "
           ++ "flag to specify it."
@@ -674,8 +673,8 @@ exceptionMessage e = case e of
           ++ "where it is."
           ++ "If the library file does exist, it may contain errors that "
           ++ "are caught by the C compiler at the preprocessing stage. "
-          ++ "In this case you can re-run configure with the verbosity "
-          ++ "flag -v3 to see the error messages."
+          ++ "In this case you can re-run 'Setup configure' with the "
+          ++ "verbosity flag -v3 to see the error messages."
       messagePlural =
         "This problem can usually be solved by installing the system "
           ++ "packages that provide these libraries (you may need the "
@@ -685,18 +684,18 @@ exceptionMessage e = case e of
           ++ "where they are."
           ++ "If the library files do exist, it may contain errors that "
           ++ "are caught by the C compiler at the preprocessing stage. "
-          ++ "In this case you can re-run configure with the verbosity "
-          ++ "flag -v3 to see the error messages."
+          ++ "In this case you can re-run 'Setup configure' with the "
+          ++ "verbosity flag -v3 to see the error messages."
       headerCppMessage =
         "If the header file does exist, it may contain errors that "
           ++ "are caught by the C compiler at the preprocessing stage. "
-          ++ "In this case you can re-run configure with the verbosity "
-          ++ "flag -v3 to see the error messages."
+          ++ "In this case you can re-run 'Setup configure' with the "
+          ++ "verbosity flag -v3 to see the error messages."
       headerCcMessage =
         "The header file contains a compile error. "
-          ++ "You can re-run configure with the verbosity flag "
+          ++ "You can re-run 'Setup configure' with the verbosity flag "
           ++ "-v3 to see the error messages from the C compiler."
-  CheckPackageProblems errors -> (intercalate "\n\n" $ errors)
+  CheckPackageProblems errors -> intercalate "\n\n" errors
   LibDirDepsPrefixNotRelative l p ->
     "Library directory of a dependency: "
       ++ show l
@@ -757,7 +756,7 @@ exceptionMessage e = case e of
   RegisMultiplePkgNotSupported -> "Registering multiple package instances is not yet supported for this compiler"
   RegisteringNotImplemented -> "Registering is not implemented for this compiler"
   NoTestSuitesEnabled ->
-    "No test suites enabled. Did you remember to configure with "
+    "No test suites enabled. Did you remember to 'Setup configure' with "
       ++ "\'--enable-tests\'?"
   TestNameDisabled tName ->
     "Package configured with test suite "

diff --git a/changelog.d/configure-messages b/changelog.d/configure-messages
@@ -0,0 +1,13 @@
+synopsis: clarify Cabal "configure" messages
+packages: Cabal
+prs: #9476
+
+synopsis: {
+
+	Cabal can issue a number of error messages referencing "Setup configure",
+	but it simply references "configure" which could mean any of three
+	things (Setup configure, the package's "configure" script, or "cabal
+	configure"). This has recently caught out even Cabal devs. Clarify these
+	messages.
+
+}