[conf] to define vs version for msvc (#2054)

* [conf] to define vs version for msvc

* notes about ``conanvcvars.bat`` file creation

* fix ci

* Update reference/config_files/settings.yml.rst

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

* add to conf

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

reference/conanfile/tools/microsoft.rst

@@ -163,7 +163,7 @@ And it can also be fully instantiated in the conanfile ``generate()`` method:
             tc.generate()
 
 
-The ``MSBuildToolchain`` will generate two files after a ``conan install`` command:
+The ``MSBuildToolchain`` will generate three files after a ``conan install`` command:
 
 .. code-block:: bash
 
@@ -175,6 +175,10 @@ The ``MSBuildToolchain`` will generate two files after a ``conan install`` comma
 - A *conantoolchain_<config>.props* file, that will be conditionally included from the previous
   *conantoolchain.props* file based on the configuration and platform, e.g.:
   *conantoolchain_release_x86.props*
+- A *conanvcvars.bat* file with the necessary ``vcvars`` invocation to define the build environment if necessary
+  to build from the command line or from automated tools (might not be necessary if opening the IDE). This file
+  will be automatically called by the ``tools.microsoft.MSBuild`` helper ``build()`` method.
+
 
 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 configurations,

reference/config_files/global_conf.rst

@@ -32,6 +32,7 @@ have priority over globally defined ones in *global.conf*, and can be defined as
     [conf]
     tools.microsoft.msbuild:verbosity=Diagnostic
     tools.microsoft.msbuild:max_cpu_count=20
+    tools.microsoft.msbuild:vs_version = 16
     tools.build:processes=10
     tools.ninja:jobs=30
     tools.gnu.make:jobs=40
@@ -46,6 +47,8 @@ Existing configurations:
 - ``tools.microsoft.msbuild:max_cpu_count`` argument for the ``/m`` (``/maxCpuCount``) when running
   ``MSBuild`` standalone or via CMake (overrides the general ``tools.build:processes``).
 
+- ``tools.microsoft.msbuild:vs_version`` defines the compiler version when using using the new ``msvc`` compiler.
+
 - ``tools.build:processes``: number of processes to use for every build-helper.
 
 - ``tools.ninja:jobs`` argument for the ``--jobs`` parameter when running Ninja generator via CMake

reference/config_files/settings.yml.rst

@@ -152,8 +152,31 @@ The new ``msvc`` compiler is a new, **experimental** one, that is intended to de
 - It is only used by the new build integrations in :ref:`conan_tools_cmake` and :ref:`conan_tools_microsoft`, but not the previous ones.
 - At the moment it implements a ``compatible_packages`` fallback to Visual Studio compiled packages, that is, previous existing binaries
   compiled with ``settings.compiler="Visual Studio"`` can be used for the ``msvc`` compiler if no binaries exist for it yet.
+  This behavior can be opted-out with ``core.package_id:msvc_visual_incompatible`` :ref:`global_conf` configuration.
 - It is not detected by the profile auto-detect, it needs to explicitly be defined in profiles.
 
+When using the ``msvc`` compiler, the Visual Studio toolset version (the actual ``vcvars`` activation and ``MSBuild`` location) will be
+defined by the default provide of that compiler version:
+
+- ``msvc`` compiler version '19.0': Visual Studio 14 2015
+- ``msvc`` compiler version '19.1': Visual Studio 15 2017
+- ``msvc`` compiler version '19.2': Visual Studio 16 2019
+
+This can be configured in your profiles with the ``tools.microsoft.msbuild:vs_version`` configuration:
+
+.. code-block:: text
+
+    [settings]
+    compiler=msvc
+    compiler.version=19.0
+
+    [conf]
+    tools.microsoft.msbuild:vs_version = 16
+
+
+In this case, the ``vcvars`` will activate the Visual Studio 16 installation, but the ``19.0`` compiler version will still be used
+because the necessary ``toolset=v140`` will be set.
+
 
 Architectures
 -------------