Deprecate --build-dir

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.

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)

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(