Add build_folder parameter in basic_layout (#4140)

* 188442 Add build_folder parameter in basic_layout

* more of explanation

* Update reference/tools/layout.rst

Co-authored-by: Carlos Zoido <mrgalleta@gmail.com>

* fix bad identation code

---------

Co-authored-by: Carlos Zoido <mrgalleta@gmail.com>

Author: ErniGH

reference/tools/layout.rst

@@ -55,16 +55,22 @@ Usage:
 
 The current layout implementation is very simple, basically sets a different build folder for different build_types
 and sets the generators output folder inside the build folder. This way we avoid to clutter our project
-while working locally.
+while working locally. If you prefer, you can define the `build_folder` to take control over the destination folder,
+so the temporary build files do not pollute the source tree.
 
 
 .. code:: python
 
-    def basic_layout(conanfile, src_folder="."):
-        conanfile.folders.build = "build"
-        if conanfile.settings.get_safe("build_type"):
-            conanfile.folders.build += "-{}".format(str(conanfile.settings.build_type).lower())
+    def basic_layout(conanfile, src_folder=".", build_folder=None):
+        subproject = conanfile.folders.subproject
+
+        conanfile.folders.source = src_folder if not subproject else os.path.join(subproject, src_folder)
+        if build_folder:
+            conanfile.folders.build = build_folder if not subproject else os.path.join(subproject, build_folder)
+        else:
+            conanfile.folders.build = "build" if not subproject else os.path.join(subproject, "build")
+            if conanfile.settings.get_safe("build_type"):
+                conanfile.folders.build += "-{}".format(str(conanfile.settings.build_type).lower())
         conanfile.folders.generators = os.path.join(conanfile.folders.build, "conan")
         conanfile.cpp.build.bindirs = ["."]
         conanfile.cpp.build.libdirs = ["."]
-        conanfile.folders.source = src_folder