MSBuildToolchain docs (#1865)

* MSBuildToolchain docs

* Update creating_packages/toolchains/msbuild.rst

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

* Update creating_packages/toolchains/msbuild.rst

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

* Update creating_packages/toolchains/msbuild.rst

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

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

creating_packages/toolchains.rst

@@ -1,7 +1,7 @@
 Toolchains
 ==========
 
-.. warning: 
+.. warning:
 
     This is a very **EXPERIMENTAL** feature, introduced in Conan 1.26, only supporting CMake
     and with limited functionality, and subject to breaking changes in the future.
@@ -69,7 +69,7 @@ Toolchains have some important advantages:
 - They execute at :command:`conan install` time. They generate files, not command line
   arguments, providing better reproducibility and debugging of builds.
 - They provide a better developer experience. The command line used by developers locally, like
-  ``cmake ...`` will achieve the same build, with the same flags, as the :command:`conan build` or 
+  ``cmake ...`` will achieve the same build, with the same flags, as the :command:`conan build` or
   the build that is done in the cache with a :command:`conan create`.
 - They are more extensible and configurable.
 
@@ -102,3 +102,4 @@ Built-in toolchains
 
    toolchains/cmake
    toolchains/make
+   toolchains/msbuild

creating_packages/toolchains/cmake.rst

@@ -1,6 +1,11 @@
 CMakeToolchain
 ==============
 
+.. warning::
+
+    This is an **experimental** feature subject to breaking changes in future releases.
+
+
 The ``CMakeToolchain`` can be used in the ``toolchain()`` method:
 
 
@@ -24,7 +29,7 @@ The ``CMakeToolchain`` will generate 2 files, after a ``conan install`` command
 before calling the ``build()`` method when the package is being built in the cache):
 
 - The main *conan_toolchain.cmake* file, that can be used in the command line.
-- A *conan_project_include.cmake* file, that will automatically be called right after the 
+- A *conan_project_include.cmake* file, that will automatically be called right after the
   ``project()`` call for cmake>=3.15, containing definitions that only take effect after such
   call. For older cmake versions you should explicitly call ``include(.../conan_project_include.cmake)``
   in your *CMakeLists.txt*.
@@ -98,7 +103,7 @@ With the ``CMakeToolchain`` it is possible to do, for multi-configuration system
     $ mkdir build && cd build
     # Install both debug and release deps and create the toolchain
     $ conan install ..
-    $ conan install .. -s build_type=Debug 
+    $ conan install .. -s build_type=Debug
     # the conan_toolchain.cmake is common for both configurations
     # Need to pass the generator WITHOUT the platform, that matches your default settings
     $ cmake .. -G "Visual Studio 15" -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake
@@ -139,7 +144,7 @@ CMake build helper
 
 The ``CMake()`` build helper that works with the ``CMakeToolchain`` is also experimental,
 and subject to breaking change in the future. It will evolve to adapt and complement the
-toolchain functionality. 
+toolchain functionality.
 
 The helper is intended to be used in the ``build()`` method, to call CMake commands automatically
 when a package is being built directly by Conan (create, install)
@@ -214,7 +219,7 @@ install()
 
 Equivalent to run ``cmake --build . --target=install``
 
-- ``build_type``: Use it only to override the value defined in the ``settings.build_type``. It 
+- ``build_type``: Use it only to override the value defined in the ``settings.build_type``. It
   can fail if the build is single configuration (e.g. Unix Makefiles), as in that case the build
   type must be specified at configure time, not build type.
 
@@ -229,7 +234,7 @@ test()
 
 Equivalent to running :command:`cmake --build . --target=RUN_TESTS`.
 
-- ``build_type``: Use it only to override the value defined in the ``settings.build_type``. It 
+- ``build_type``: Use it only to override the value defined in the ``settings.build_type``. It
   can fail if the build is single configuration (e.g. Unix Makefiles), as in that case the build
   type must be specified at configure time, not build type.
 - ``target``: name of the build target to run, by default ``RUN_TESTS`` or ``test``.

creating_packages/toolchains/msbuild.rst

@@ -0,0 +1,98 @@
+MSBuildToolchain
+================
+
+.. warning::
+
+    This is an **experimental** feature subject to breaking changes in future releases.
+
+
+The ``MSBuildToolchain`` can be used in the ``toolchain()`` method:
+
+
+.. code:: python
+
+    from conans import ConanFile, MSBuildToolchain
+
+    class App(ConanFile):
+        settings = "os", "arch", "compiler", "build_type"
+        requires = "hello/0.1"
+        generators = "msbuild"
+        options = {"shared": [True, False]}
+        default_options = {"shared": False}
+
+        def toolchain(self):
+            tc = MSBuildToolchain(self)
+            tc.write_toolchain_files()
+
+
+The ``MSBuildToolchain`` will generate two files after a ``conan install`` command or
+before calling the ``build()`` method when the package is building in the cache:
+
+- The main *conan_toolchain.props* file, that can be used in the command line.
+- A *conan_toolchain_<config>.props* file, that will be conditionally included from the previous
+  *conan_toolchain.props* file based on the configuration, platform and toolset, e.g.:
+  *conan_toolchain_Release_x86_v140.props*
+
+Every invocation to ``conan install`` with different configuration will create a new properties ``.props``
+file, that will also be conditionally included. This allows to install different sets of dependencies,
+then switch among them directly from the Visual Studio IDE.
+
+The toolchain files can configure:
+
+- The Visual Studio runtime (MT/MD/MTd/MDd), obtained from Conan input settings
+- The C++ standard, obtained from Conan input settings
+
+
+Generators
+----------
+
+The ``MSBuildToolchain`` only works with the ``msbuild`` generator.
+Please, do not use other generators, as they can have overlapping definitions that can conflict.
+
+
+Using the toolchain in developer flow
+-------------------------------------
+
+One of the advantages of using Conan toolchains is that they can help to achieve the exact same build
+with local development flows, than when the package is created in the cache.
+
+With the ``MSBuildToolchain`` it is possible to do:
+
+.. code:: bash
+
+    # Lets start in the folder containing the conanfile.py
+    $ mkdir build && cd build
+    # Install both debug and release deps and create the toolchain
+    $ conan install ..
+    $ conan install .. -s build_type=Debug
+    # Add ``conan_toolchain.props`` in your IDE to the project properties
+    # No need to add the configuration .props files. This needs to be done only once
+    # If you have dependencies, you will need to add the .props files of the dependencies
+    # too, check the "msbuild" generator
+    # Open Visual Studio IDE and build, switching configurations directly in the IDE
+
+
+MSBuild build helper
+---------------------
+
+.. warning::
+
+    The existing ``MSBuild`` helper is not suitable to be used with toolchain yet. A new
+    helper will be added in future releases.
+
+
+At the moment there is no build helper to work with the ``MSBuildToolchain``. Call directly
+``msbuild`` in your recipes to build your project, something like:
+
+.. code:: python
+
+    def build(self):
+        vs_path = vs_installation_path("15")
+        vcvars_path = os.path.join(vs_path, "VC/Auxiliary/Build/vcvarsall.bat")
+
+        platform_arch = "x86" if self.settings.arch == "x86" else "x64"
+        build_type = self.settings.build_type
+        cmd = ('set "VSCMD_START_DIR=%%CD%%" && '
+                   '"%s" x64 && msbuild "MyProject.sln" /p:Configuration=%s '
+                   '/p:Platform=%s ' % (vcvars_path, build_type, platform_arch))
+        self.run(cmd)