Update README

Updated the README file with the current instructions to build and debug
the Qt VS Tools solution. The text is now formatted with Markdown.

Change-Id: I92d0ea2d466b3e2970977baa5c7a140c3a8adcf0
Reviewed-by: Karsten Heimrich <karsten.heimrich@qt.io>

2 files changed, 156 insertions, 131 deletions

diff --git a/README b/README
deleted file mode 100644
index 07631898..00000000
--- a/README
+++ /dev/null
@@ -1,131 +0,0 @@
-How to build
-============
-
-The instructions should help you build the Qt Visual Studio Tools from scratch.
-
-
-
-Get the sources
----------------
-
-Use Git to check out the Qt Visual Studio Tools sources that are hosted at:
-
-http://code.qt.io/cgit/qt-labs/vstools.git/
-
-
-
-Build a static Qt
------------------
-
-Building the Qt Visual Studio Tools from sources requires a static build of Qt (version 5.6.0
-or newer). Supported compilers are MSVC 2013 or newer, GCC 4.7 or newer, and Clang 3.1 or newer.
-
-See the Qt documentation for the prerequisites and steps to build Qt from sources.
-https://wiki.qt.io/Building_Qt_5_from_Git#Windows
-
-Recommended configuration options:
-configure -prefix %CD%\qtbase -release -static -static-runtime -opensource -nomake examples -nomake tests
-
-Recommended (n)make options: (n)make module-qtbase
-
-
-
-Build the Qt Visual Studio Tools
---------------------------------
-
-Change the directory into 'src' and run 'qmake && make' (or 'mingw32-make', 'nmake' ...) to build
-the Qt Visual Studio Tools command line applications. Once finished, open the solution QtVsTools.sln
-in Visual Studio. Choose "Build"->"Transform All T4 Templates", Accept the following dialog and
-build the solution.
-
-To debug the resulting VSIX, select the 'QtVsTools' node, right click and choose 'Properties|Debug'.
-Update 'Start Action|Start external program:' to point to your Visual Studio 'devenv.exe' application.
-Update 'Start Options|Command line arguments:' with '/rootSuffix Exp'. Note: The implemented post
-build targets will only work reliable if you use the 'Exp' hive of Visual Studio.
-
-
-
-Build the qtdeclarative integration (vsqml.dll)
------------------------------------------------
-
-The QtVSTools solution contains one C++ project that implements the integration with qtdeclarative.
-This exposes QML services, like parsing and debugging, to C# code via platform invoke calls to
-vsqml.dll. Building this library also requires a static build of Qt. For details, please refer to
-the README file in 'src/vsqml'.
-
-
-
-Build the Qt Visual Studio Tools documentation
-----------------------------------------------
-
-Run 'qmake && make docs' (or 'mingw32-make docs', 'nmake docs' ...) from the root directory to
-build the Qt Visual Studio Tools documentation. You need to have 'qdoc' and friends built already.
-
-See the Qt documentation for the prerequisites and steps to build Qt documentation from sources.
-https://wiki.qt.io/Building_Qt_Documentation
-
-
-
-
-Product name or Publisher name update
--------------------------------------
-
-Open the file 'source.extension.vsixmanifest_TT' inside the 'src\config\$(VisualStudioVersion)'
-directory and update the 'DisplayName' tag's value or the 'Identity' tag's 'Publisher' attribute.
-Important: Updating the information requires also updating the MsBuild 'AfterTargets' information
-inside the 'qtvstools.afterbuild.targets' file in the 'src\config' directory.
-
-
-
-Version number update
----------------------
-
-1. In the QtVSTools solution, open the 'version.targets' file and update the version.
-
-2. Select the menu option 'Build' > 'Transform All T4 Templates'.
-   --> The updated version number is propagated into the remaining source files.
-
-3. Rebuild the solution.
-
-
-
-Support for newer Visual Studio Versions
-----------------------------------------
-
-Add a new directory in 'src\config' matching '$(VisualStudioVersion)' by copying one of the existing
-directories.
-
-Minimum changes to the 'qtvstools.targets' file:
-
-Update the 'Project' tag's 'ToolsVersion' attribute to match the new VS tools version.
-Update the 'DefineConstants' tag's value to match the new VS version.
-Update the 'ItemGroup' tag's 'Condition' attribute to match the new VS version.
-Update the 'Reference' tag's 'Include' attribute to match the new VS version, most likely the following:
-    - Microsoft.VisualStudio.ExtensionsExplorer.UI
-    - Microsoft.VisualStudio.Shell.{VersionNumber}
-    - Microsoft.VisualStudio.VCCodeModel
-    - Microsoft.VisualStudio.VCProjectEngine
-
-Minimum changes to the 'source.extension.vsixmanifest' file:
-
-Update the 'Identity' tag's 'Id' attribute with a new GUID.
-
-
-
-How to locally test the Qt Visual Studio Tools update
------------------------------------------------------
-
-Inside the src\config directory, edit the qt.io.xml file and modify the following tags:
-
-    <updated>2016-11-11T10:51:55Z</updated>   Use the current date and time, keep the 'T' and 'Z'
-    <id>{ Product ID }</id>                   Set to the Product ID that can be found in the 'source.extension.vsixmanifest' file,
-                                              for example: <id>QtVsTools.30112013-cd02-4fd0-89bd-e36f85abe16a</id>
-    <Version>{ Version }</Version>            Set to the Version that can be found in the 'source.extension.vsixmanifest' file,
-                                              for example: <Version>2.0.0</Version>
-
-Copy the XML file and the VSIX package inside a new folder side by side and open the
-'Tools | Options | Extensions and Updates' settings dialog in Visual Studio. Add a new entry in the
-Additional Extension Gallery, like this:
-
-    Name: qt.io
-    Url: file://path/to/your/atom.xml
diff --git a/README.md b/README.md
new file mode 100644
index 00000000..d56af32d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,156 @@
+# Qt Visual Studio Tools
+
+The Qt Visual Studio Tools integrate the Qt development tools into Microsoft Visual Studio. This
+enables developers to use the standard Windows development environment without having to worry
+about Qt-related build steps or tools.
+
+## Sources
+
+Use Git to check out the
+[Qt Visual Studio Tools sources](https://code.qt.io/cgit/qt-labs/vstools.git), using one of the
+following options:
+
+    git clone git://code.qt.io/qt-labs/vstools.git
+
+    git clone https://code.qt.io/qt-labs/vstools.git
+
+Contributions to the Qt Visual Studio Tools project must be submitted to the
+[`qt-labs/vstools`](https://codereview.qt-project.org/admin/repos/qt-labs/vstools) Gerrit
+repository. For instructions on how to set up a Gerrit account and contribute to Qt projects, refer
+to the wiki page ["Setting up Gerrit"](https://wiki.qt.io/Setting_up_Gerrit).
+
+## Qt installation
+
+To build the Qt Visual Studio Tools, an installation of Qt is required. The version of Qt that is
+currently supported is 5.12.9. Either build Qt from the sources available in the
+[Qt Project Git Repository Browser](https://code.qt.io/cgit/qt/qt5.git/tag/?h=v5.12.9)
+or install a [pre-built binary package](https://download.qt.io/official_releases/qt/5.12/5.12.9/).
+
+### Building Qt from sources
+
+See the [Qt documentation](https://wiki.qt.io/Building_Qt_5_from_Git#Windows) for the prerequisites
+and steps to build Qt from sources.
+
+Recommended options for the `configure` tool:
+
+    configure -static -opensource -confirm-license -nomake examples -nomake tests -opengl desktop
+
+Recommended options for [jom](https://wiki.qt.io/Jom):
+
+    jom module-qtbase module-qtdeclarative
+
+### 32-bit or 64-bit
+
+Visual Studio 2022 is a 64-bit application, whereas VS 2019 and 2017 are 32-bit applications. The
+target platform for which Qt is built must reflect this:
+
+- For Visual Studio 2022, use Qt built for the x64 platform.
+
+- For Visual Studio 2019, use Qt built for the x86 platform.
+
+- For Visual Studio 2017, use Qt built for the x86 platform.
+
+## Build
+
+After cloning the repository, follow the instructions below to build the Qt Visual Studio Tools.
+
+### Requirements
+
+The following is required in order to build the Qt Visual Studio solution:
+
+- Visual Studio 2017, 2019 or 2022, with the following workloads:
+    - Desktop development with C++
+    - .NET desktop development
+    - [Visual Studio extension development](https://docs.microsoft.com/en-us/visualstudio/extensibility/installing-the-visual-studio-sdk)
+    - [Linux development with C++](https://devblogs.microsoft.com/cppblog/linux-development-with-c-in-visual-studio/)
+
+- [`vswhere` tool](https://github.com/microsoft/vswhere) (usually installed with Visual Studio):
+    - [Version 2.7.1](https://github.com/microsoft/vswhere/releases/tag/2.7.1) or greater.
+
+- `git` must be installed and included in the `PATH` environment variable.
+
+### Environment variables
+
+Set environment variables `QTBUILD_STATIC_VS`_`nnnn`_ according to the installed VS versions, i.e.:
+- `QTBUILD_STATIC_VS2017` = _path to Qt installation built with msvc2017_
+- `QTBUILD_STATIC_VS2019` = _path to Qt installation built with msvc2019_
+- `QTBUILD_STATIC_VS2022` = _path to Qt installation built with msvc2022_
+
+For example, assuming Qt is installed in the following directory tree:
+
+    C:
+    +--- build
+         +--- qt_5.12.9_msvc2019_x86
+         |    +--- bin
+         |    +--- include
+         |    +--- lib
+         |    (etc.)
+         |
+         +--- qt_5.12.9_msvc2022_x64
+              +--- bin
+              +--- include
+              +--- lib
+              (etc.)
+
+In this case, the following environment variables must be set:
+
+    QTBUILD_STATIC_VS2019=C:\build\qt_5.12.9_msvc2019_x86
+    QTBUILD_STATIC_VS2022=C:\build\qt_5.12.9_msvc2022_x64
+
+### Initialization
+
+In a command prompt (a "regular" one, *not* a VS Developer/Native Tools prompt), `CD` to the
+root of the repository and run `vstools.bat` to initialize the solution and open it in Visual
+Studio, with the following arguments:
+
+    C:\...\vstools> vstools -init -startvs
+
+This will:
+- Delete all output files;
+- Restore NuGet packages;
+- Run an initial text template generation;
+- Open the solution in the VS IDE, ready to build/debug.
+
+This procedure must be repeated when opening the solution on another
+version of VS. For example, assuming VS 2022 and VS 2019 are
+installed, to open the solution in VS 2019 after it has already been
+initialized and used in VS 2022, run the following:
+
+    C:\...\vstools> vstools -vs2019 -init -startvs
+
+By default, if no VS version is specified, the most recent version is selected.
+
+### Target platform
+
+The solution platform must be set to `'x64'` for VS 2022, and `'x86'`
+or `'Any CPU'` for VS 2019 and VS 2017.
+
+## Debug
+
+To debug the Qt Visual Studio tools extension, the
+`QtVsTools.Package` project must be set as the
+startup project. Also, the target binary for the debug session must
+be set to the Visual Studio executable (`devenv.exe`), with the
+option to start an
+[experimental instance](https://docs.microsoft.com/en-us/visualstudio/extensibility/the-experimental-instance).
+
+Follow these instructions to configure the solution for debug:
+
+- In the solution explorer: right-click QtVsTools.Package > Set as
+startup
+- In the solution explorer: right-click QtVsTools.Package > Properties
+- In the properties dialog: select the Debug page
+- In the debug properties page, set the following options:
+    - _Start external program_ = path to the Visual Studio executable
+    (`devenv.exe`).
+    - _Command line arguments_ = `/rootSuffix Exp`.
+
+## Documentation
+
+To build the Qt Visual Studio Tools documentation, run
+`qmake && jom docs` from the root directory of the `vstools`
+repository. You need to have `qdoc` and friends built already.
+
+See the
+[Qt documentation](https://wiki.qt.io/Building_Qt_Documentation) for
+the prerequisites and steps to build Qt documentation from sources.