From dc655b069449e173e85ca0aa5b99c64e01b32139 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?St=C3=A9phane=20Bidoul?= <stephane.bidoul@gmail.com>
Date: Mon, 1 Jun 2020 12:28:18 +0200
Subject: [PATCH] Deprecate --build-dir

---
 news/8372.removal                     |  4 ++++
 src/pip/_internal/cli/base_command.py | 14 ++++++++++++++
 src/pip/_internal/cli/cmdoptions.py   |  6 +-----
 3 files changed, 19 insertions(+), 5 deletions(-)
 create mode 100644 news/8372.removal

diff --git a/news/8372.removal b/news/8372.removal
new file mode 100644
index 00000000000..af0cb6e70c7
--- /dev/null
+++ b/news/8372.removal
@@ -0,0 +1,4 @@
+Deprecate -b/--build/--build-dir/--build-directory. Its current behaviour is confusing
+and breaks in case different versions of the same distribution need to be built during
+the resolution process. Using the TMPDIR/TEMP/TMP environment variable, possibly
+combined with --no-clean covers known use cases.
diff --git a/src/pip/_internal/cli/base_command.py b/src/pip/_internal/cli/base_command.py
index f51682b60e9..c815947473d 100644
--- a/src/pip/_internal/cli/base_command.py
+++ b/src/pip/_internal/cli/base_command.py
@@ -190,6 +190,20 @@ def _main(self, args):
                 )
                 options.cache_dir = None
 
+        if getattr(options, "build_dir", None):
+            deprecated(
+                reason=(
+                    "The -b/--build/--build-dir/--build-directory "
+                    "option is deprecated."
+                ),
+                replacement=(
+                    "use the TMPDIR/TEMP/TMP environment variable, "
+                    "possibly combined with --no-clean"
+                ),
+                gone_in="20.4",
+                issue=8333,
+            )
+
         try:
             status = self.run(options, args)
             assert isinstance(status, int)
diff --git a/src/pip/_internal/cli/cmdoptions.py b/src/pip/_internal/cli/cmdoptions.py
index 5b5647d64f4..f8bb0fc53c4 100644
--- a/src/pip/_internal/cli/cmdoptions.py
+++ b/src/pip/_internal/cli/cmdoptions.py
@@ -702,11 +702,7 @@ def _handle_build_dir(option, opt, value, parser):
     metavar='dir',
     action='callback',
     callback=_handle_build_dir,
-    help='Directory to unpack packages into and build in. Note that '
-         'an initial build still takes place in a temporary directory. '
-         'The location of temporary directories can be controlled by setting '
-         'the TMPDIR environment variable (TEMP on Windows) appropriately. '
-         'When passed, build directories are not cleaned in case of failures.'
+    help=SUPPRESS_HELP,
 )  # type: Callable[..., Option]
 
 ignore_requires_python = partial(