[docs] Clarify how to run cmake and llvm-lit with Visual Studio addressing PR45978

[yaron.keren]

https://bugs.llvm.org/show_bug.cgi?id=45978

[amccarth]

llvm/docs/GettingStartedVS.rst

126

There are some potential gotchas lurking here.

Visual Studio (often) includes cmake, git, ninja, and even python. Those might be different versions than what you installed in the previous steps. Depending how vcvarsall.bat juggles the path, you might not be invoking the versions you think you are. In many cases, this might not be a problem, but it can be a real mess in lldb, especially lldb tests.

My solution is:

• Do not install CMake, git, or ninja. Rely on the VS-distributed ones.
• Uninstall the VS-distributed Python, then install an independent python3 (with debug libraries if working in LLDB). The VS version doesn't come with the debug libraries. Even with all the CMake fixes and hints to point to your own python3, some parts of the build may pick up the VS version (or any other version) that exists on the machine. Apparently, there can be only one.
• Use the git tools instead of the out-of-date and unsupported GnuWin32 one...
• ... except for make, which isn't included in the git tools, so that's the only GnuWin32 tool I do install. (LLDB tests uses make to build test executables.)
• And you might want doxygen.
• LLDB also requires swift.
• I maintain my own set of batch files that start by running vcvarsall.bat to select the right toolchain and then fix-up the PATH to ensure I get a consistent set of tools. I have shortcuts for each configuration that lunch CMD with the appropriate batch file.
• I also use a batch file to run CMake, since there are so many flags you have to get right. For example:

cmake -GNinja -DCMAKE_BUILD_TYPE=Debug -DLLDB_TEST_DEBUG_TEST_CRASHES=1 -DLLDB_PYTHON_HOME="C:\Program Files\Python38" -DPython3_ROOT_DIR="C:\Program Files\Python38" -DPython3_FIND_REGISTRY=LAST -DLLDB_TEST_COMPILER=D:\src\llvm\build\ninja_dbg\bin\clang.exe ..\..\llvm-project\llvm -DLLVM_ENABLE_ZLIB=OFF -DLLVM_ENABLE_PROJECTS="clang;lld;lldb"

[yaron.keren]

I completely agree, the Getting Started document should be modernized considering a current Visual Studio 2019 installation bundles tools and that GnuWin32 is antique. I will create revision for your review.

llvm/docs/GettingStartedVS.rst

* Once CMake is installed then the simplest way is to just start the
      once compiling is complete, although installation is not mandatory for
      using LLVM.  Another important option is ``LLVM_TARGETS_TO_BUILD``,
      which controls the LLVM target architectures that are included on the
      build.
    * If CMake complains that it cannot find the compiler, make sure that
      you have the Visual Studio C++ Tools installed, not just Visual Studio
      itself (trying to create a C++ project in Visual Studio will generally
      download the C++ tools if they haven't already been).
+   * Run cmake from a "x86/x64 Native Tools Command Prompt" so Visual C++ will
+     be on the PATH and its environment variables are set. Do **not** use
+     ``CMAKE_C_COMPILER`` and ``CMAKE_CXX_COMPILER`` for this purpose:
+
+     .. code-block:: bat
+
+        **********************************************************************
+        ** Visual Studio 2019 Developer Command Prompt v16.11.1
+        ** Copyright (c) 2021 Microsoft Corporation
+        **********************************************************************
+        [vcvarsall.bat] Environment initialized for: 'x64'
+        c:\build> cmake ..\llvm\llvm -DLLVM_ENABLE_PROJECTS=clang -DLLVM_TARGETS_TO_BUILD=X86 -Thost=x64
+
    * See the :doc:`LLVM CMake guide <CMake>` for detailed information about
      how to configure the LLVM build.
    * CMake generates project files for all build types. To select a specific
      build type, use the Configuration manager from the VS IDE or the
      ``/property:Configuration`` command line option when using MSBuild.
    * By default, the Visual Studio project files generated by CMake use the
      32-bit toolset. If you are developing on a 64-bit version of Windows and
      want to use the 64-bit toolset, pass the ``-Thost=x64`` flag when
* The Fibonacci project is a sample program that uses the JIT. Modify the
      project's debugging properties to provide a numeric command line argument
      or run it from the command line.  The program will print the
      corresponding fibonacci value.
 
 8. Test LLVM in Visual Studio:
 
    * If ``%PATH%`` does not contain GnuWin32, you may specify
      ``LLVM_LIT_TOOLS_DIR`` on CMake for the path to GnuWin32.
-   * You can run LLVM tests by merely building the project "check". The test
+   * You can run LLVM tests by merely building the project "check-all". The test
      results will be shown in the VS output window.
 
 9. Test LLVM on the command line:
 
    * The LLVM tests can be run by changing directory to the llvm source
      directory and running:
 
      .. code-block:: bat
 
-        C:\..\llvm> python ..\build\bin\llvm-lit --param build_config=Win32 --param build_mode=Debug --param llvm_site_config=../build/test/lit.site.cfg test
+        c:\llvm> python ..\build\Release\bin\llvm-lit.py llvm\test
 
      This example assumes that Python is in your PATH variable, you
-     have built a Win32 Debug version of llvm with a standard out of
+     have built a Release version of llvm with a standard out of
      line build. You should not see any unexpected failures, but will
      see many unsupported tests and expected failures.
 
      A specific test or test directory can be run with:
 
      .. code-block:: bat
 
-        C:\..\llvm> python ..\build\bin\llvm-lit --param build_config=Win32 --param build_mode=Debug --param llvm_site_config=../build/test/lit.site.cfg test/path/to/test
+        c:\llvm> python ..\build\Release\bin\llvm-lit.py llvm\test\Transforms\Util
 
 
 An Example Using the LLVM Tool Chain
 ====================================
 
 1. First, create a simple C file, name it '``hello.c``':
 
    .. code-block:: c