From 1b368d7e7bbe4399e89731cd1c012fc91665d2e7 Mon Sep 17 00:00:00 2001
From: Francesco Gazzetta <fgaz@fgaz.me>
Date: Mon, 3 May 2021 15:45:43 +0200
Subject: [PATCH] Explain why --only-download checks are there

---
 cabal-install/src/Distribution/Client/ProjectBuilding.hs | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/cabal-install/src/Distribution/Client/ProjectBuilding.hs b/cabal-install/src/Distribution/Client/ProjectBuilding.hs
index e2e0f3120d..fac7f863f2 100644
--- a/cabal-install/src/Distribution/Client/ProjectBuilding.hs
+++ b/cabal-install/src/Distribution/Client/ProjectBuilding.hs
@@ -653,6 +653,14 @@ rebuildTarget verbosity
               sharedPackageConfig
               plan rpkg@(ReadyPackage pkg)
               pkgBuildStatus
+    -- Technically, doing the --only-download filtering only in this function is
+    -- not perfect. We could also prune the plan at an earlier stage, like it's
+    -- done with --only-dependencies. But...
+    --   * the benefit would be minimal (practically just avoiding to print the
+    --     "requires build" parts of the plan)
+    --   * we currently don't have easy access to the BuildStatus of packages
+    --     in the pruning phase
+    --   * we still have to check it here to avoid performing successive phases
     | buildSettingOnlyDownload buildSettings = do
         case pkgBuildStatus of
           BuildStatusDownload ->
-- 
GitLab