Revert "MIX_BUILD_PATH specifies only the build_path prefix"

This reverts commit 3490a14
which contained a breaking change. Therefore we document the
current behaviour to avoid further confusion.

Author: José Valim

lib/mix/lib/mix.ex

@@ -234,7 +234,9 @@ defmodule Mix do
   Mix responds to the following variables:
 
     * `MIX_ARCHIVES` - specifies the directory into which the archives should be installed
-    * `MIX_BUILD_PATH` - sets the project `Mix.Project.build_path/0` config
+    * `MIX_BUILD_PATH` - sets the project `Mix.Project.build_path/0` config. This option
+      must always point to a subdirectory inside a temporary directory. For instance,
+      never "/tmp" or "_build" but "_build/PROD" or "/tmp/PROD", as required by Mix
     * `MIX_DEPS_PATH` - sets the project `Mix.Project.deps_path/0` config
     * `MIX_DEBUG` - outputs debug information about each task before running it
     * `MIX_ENV` - specifies which environment should be used. See [Environments](#module-environments)

lib/mix/lib/mix/project.ex

@@ -499,11 +499,11 @@ defmodule Mix.Project do
   """
   @spec build_path(keyword) :: Path.t()
   def build_path(config \\ config()) do
-    config[:env_path] || env_path(config)
+    System.get_env("MIX_BUILD_PATH") || config[:env_path] || env_path(config)
   end
 
   defp env_path(config) do
-    dir = System.get_env("MIX_BUILD_PATH") || config[:build_path] || "_build"
+    dir = config[:build_path] || "_build"
     subdir = build_target() <> build_per_environment(config)
     Path.expand(dir <> "/" <> subdir)
   end

lib/mix/test/mix/project_test.exs

@@ -30,9 +30,19 @@ defmodule Mix.ProjectTest do
                Path.join(File.cwd!(), "_build/shared")
     end
 
+    test "considers the target" do
+      Mix.target(:rpi3)
+
+      assert Mix.Project.build_path(build_per_environment: true) ==
+               Path.join(File.cwd!(), "_build/rpi3_dev")
+
+      assert Mix.Project.build_path(build_per_environment: false) ==
+               Path.join(File.cwd!(), "_build/rpi3_shared")
+    end
+
     test "considers MIX_BUILD_PATH" do
       System.put_env("MIX_BUILD_PATH", "_build")
-      assert Mix.Project.build_path() == Path.join(File.cwd!(), "_build/dev")
+      assert Mix.Project.build_path() == "_build"
     after
       System.delete_env("MIX_BUILD_PATH")
     end
@@ -43,16 +53,6 @@ defmodule Mix.ProjectTest do
     after
       System.delete_env("MIX_DEPS_PATH")
     end
-
-    test "considers the target" do
-      Mix.target(:rpi3)
-
-      assert Mix.Project.build_path(build_per_environment: true) ==
-               Path.join(File.cwd!(), "_build/rpi3_dev")
-
-      assert Mix.Project.build_path(build_per_environment: false) ==
-               Path.join(File.cwd!(), "_build/rpi3_shared")
-    end
   end
 
   test "push and pop projects" do