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 @@ 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)

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. '

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)
 

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: