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

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.
+}