new win bash mechanism (conan-io#2152)

* new win bash mechanism

* Apply suggestions from code review

Co-authored-by: Daniel <[email protected]>

* fix html

* Update reference/conanfile/attributes.rst

Co-authored-by: Daniel <[email protected]>
Co-authored-by: czoido <[email protected]>
Co-authored-by: James <[email protected]>

Author: 4 people

reference/conanfile/attributes.rst

@@ -1698,3 +1698,20 @@ To declare that a recipe provides the functionality of several different recipes
 
 If the attribute is omitted, the value of the attribute is assumed to be equal to the current package name. Thus, it's redundant for
 ``libjpeg`` recipe to declare that it provides ``libjpeg``, it's already implicitly assumed by Conan.
+
+
+
+win_bash
+--------
+
+This is an **experimental** feature introduced in Conan 1.39.
+
+When ``True`` it enables the new run in a subsystem bash in Windows mechanism. :ref:`Read more here<conanfile_win_bash>`.
+
+.. code-block:: python
+
+    from conans import ConanFile
+
+    class FooRecipe(ConanFile):
+        ...
+        win_bash = True

systems_cross_building/windows_subsystems.rst

@@ -37,6 +37,33 @@ shouldn't specify it.
 Running commands inside the subsystem
 -------------------------------------
 
+
+.. _conanfile_win_bash:
+
+self.win_bash
+_____________
+
+This is an experimental feature introduced in Conan 1.39. It supersedes the ``run(..., win_bash=True)`` argument but
+if the ``run(..., win_bash=True)`` is used, it will have priority so the compatibility with the previous behavior is
+guaranteed.
+
+The ``self.win_bash`` is an attribute of the conanfile, when set to ``True`` and only when running in Windows (you don't need
+to check if you are in Windows), it will run the ``self.run()`` commands inside a bash shell.
+
+
+.. note::
+
+    The ``bash.exe`` that will run **is not auto-detected** or read from the ``CONAN_BASH_PATH`` anymore, neither the subsystem to be used.
+    These are the config variables used:
+
+    - ``tools.microsoft.bash:subsystem``: Values can be ``msys2``, ``cygwin``, ``msys`` and ``wsl``.
+    - ``tools.microsoft.bash:path``: Path to the ``bash.exe``
+
+The new :ref:`Autotools, AutotoolsToolchain, AutotoolsDeps and PkgConfigDeps<conan_tools_gnu>` will work automatically
+when ``self.win_bash`` is set.
+
+
+
 self.run()
 __________
 
@@ -54,6 +81,11 @@ run in Windows-native mode, the compiler won't link against the ``msys-2.0.dll``
 AutoToolsBuildEnvironment
 _________________________
 
+.. note::
+
+    From Conan 1.39 the new :ref:`Autotools<conan_tools_gnu_build_helper>` build helper will use the ``self.win_bash``
+    conanfile attribute (see above) to adjust automatically all the paths to the subsystem.
+
 In the constructor of the build helper, you have the ``win_bash`` parameter. Set it to ``True`` to
 run the ``configure`` and ``make`` commands inside a bash.