From a49146a4a4f9abe0abf9888fcd3d775e148fe96d Mon Sep 17 00:00:00 2001
From: Artem Pelenitsyn <a.pelenitsyn@gmail.com>
Date: Fri, 11 Jul 2025 09:41:45 -0400
Subject: [PATCH] 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.
---
 cabal-install/src/Distribution/Client/Config.hs | 13 ++++++++++---
 cabal-install/tests/IntegrationTests2.hs        |  1 -
 changelog.d/pr-11067                            | 12 ++++++++++++
 3 files changed, 22 insertions(+), 4 deletions(-)
 create mode 100644 changelog.d/pr-11067

diff --git a/cabal-install/src/Distribution/Client/Config.hs b/cabal-install/src/Distribution/Client/Config.hs
index 9254b2fae9b..77348dbc638 100644
--- a/cabal-install/src/Distribution/Client/Config.hs
+++ b/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))]
diff --git a/cabal-install/tests/IntegrationTests2.hs b/cabal-install/tests/IntegrationTests2.hs
index 69c4134f142..95f04b81a4c 100644
--- a/cabal-install/tests/IntegrationTests2.hs
+++ b/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"
diff --git a/changelog.d/pr-11067 b/changelog.d/pr-11067
new file mode 100644
index 00000000000..ac735f98f98
--- /dev/null
+++ b/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.
+}