From acab2ee54ed25edd44edbdf793a4b1d173bfbcb1 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      |  3 ++-
 tests/functional/test_install_cleanup.py |  6 +++++-
 tests/functional/test_wheel.py           |  3 +++
 5 files changed, 28 insertions(+), 2 deletions(-)
 create mode 100644 news/8372.removal

diff --git a/news/8372.removal b/news/8372.removal
new file mode 100644
index 000000000..af0cb6e70
--- /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 c523c4e56..52027e6e8 100644
--- a/src/pip/_internal/cli/base_command.py
+++ b/src/pip/_internal/cli/base_command.py
@@ -190,6 +190,20 @@ class Command(CommandContextMixIn):
                 )
                 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.3",
+                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 120d51eee..4c557efa8 100644
--- a/src/pip/_internal/cli/cmdoptions.py
+++ b/src/pip/_internal/cli/cmdoptions.py
@@ -702,7 +702,8 @@ build_dir = partial(
     metavar='dir',
     action='callback',
     callback=_handle_build_dir,
-    help='Directory to unpack packages into and build in. Note that '
+    help='(DEPRECATED) '
+         '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. '
diff --git a/tests/functional/test_install_cleanup.py b/tests/functional/test_install_cleanup.py
index e5d8c4602..719c3cc42 100644
--- a/tests/functional/test_install_cleanup.py
+++ b/tests/functional/test_install_cleanup.py
@@ -14,7 +14,11 @@ def test_no_clean_option_blocks_cleaning_after_install(script, data):
     build = script.base_path / 'pip-build'
     script.pip(
         'install', '--no-clean', '--no-index', '--build', build,
-        '--find-links={}'.format(data.find_links), 'simple', expect_temp=True,
+        '--find-links={}'.format(data.find_links), 'simple',
+        expect_temp=True,
+        # TODO: allow_stderr_warning is used for the --build deprecation,
+        #       remove it when removing support for --build
+        allow_stderr_warning=True,
     )
     assert exists(build)
 
diff --git a/tests/functional/test_wheel.py b/tests/functional/test_wheel.py
index 4f60e192e..9fcb18032 100644
--- a/tests/functional/test_wheel.py
+++ b/tests/functional/test_wheel.py
@@ -201,6 +201,9 @@ def test_no_clean_option_blocks_cleaning_after_wheel(
         '--find-links={data.find_links}'.format(**locals()),
         'simple',
         expect_temp=True,
+        # TODO: allow_stderr_warning is used for the --build deprecation,
+        #       remove it when removing support for --build
+        allow_stderr_warning=True,
     )
 
     if not use_new_resolver: