cabal update: don't show comment with builddir in the default config

When calling `cabal update` with an empty state (empty CABAL_DIR or new
machine), cabal writes out a default config file with many fields
commented out to show their defaults. This suggests that the user can
uncomment the field and override the default. This is wrong for fields
that aren't allowed in the config file like `builddir`. This patch
avoids generating a comment with `builddir` in the default config.

Fix #11050.

Author: ulysses4ever

cabal-install/src/Distribution/Client/Config.hs

@@ -1782,9 +1782,16 @@ showConfigWithComments comment vals =
         (fmap (field . savedConfigureFlags) mcomment)
         ((field . savedConfigureFlags) vals)
 
-    -- skip fields based on field name.  currently only skips "remote-repo",
-    -- because that is rendered as a section.  (see 'ppRemoteRepoSection'.)
-    skipSomeFields = filter ((/= "remote-repo") . fieldName)
+    -- Skip fields based on field name.
+    skipSomeFields =
+      filter
+        ( ( `notElem`
+              [ "remote-repo" -- rendered as a section (see 'ppRemoteRepoSection')
+              , "builddir" -- no effect in config file (see Note [reading project configuration])
+              ]
+          )
+            . fieldName
+        )
 
 -- | Fields for the 'install-dirs' sections.
 installDirsFields :: [FieldDescr (InstallDirs (Flag PathTemplate))]

cabal-install/tests/IntegrationTests2.hs

@@ -2675,7 +2675,6 @@ testConfigOptionComments = do
   "-- username" `assertHasCommentLine` "username"
   "-- password" `assertHasCommentLine` "password"
   "-- password-command" `assertHasCommentLine` "password-command"
-  "-- builddir" `assertHasCommentLine` "builddir"
 
   "  -- hoogle" `assertHasCommentLine` "hoogle"
   "  -- html" `assertHasCommentLine` "html"

changelog.d/pr-11067

@@ -0,0 +1,12 @@
+synopsis: `cabal update`: create default config without comment about `builddir`
+packages: cabal-install
+prs: #11067
+issues: #11050
+description: {
+When calling `cabal update` with an empty state (empty `CABAL_DIR` or new
+machine), cabal writes out a default config file with many fields
+commented out to show their defaults. This suggests that the user can
+uncomment the field and override the default. This is wrong for fields
+that aren't allowed in the config file like `builddir`. This patch
+avoids generating a comment with `builddir` in the default config.
+}