From 1c0ebcd62c5449c8120f119bd5a13deebc27cb67 Mon Sep 17 00:00:00 2001 From: Miguel Costa Date: Mon, 8 Nov 2021 14:50:11 +0100 Subject: 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 --- README | 131 ---------------------------------------------------- README.md | 156 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 156 insertions(+), 131 deletions(-) delete mode 100644 README create mode 100644 README.md 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: - - 2016-11-11T10:51:55Z Use the current date and time, keep the 'T' and 'Z' - { Product ID } Set to the Product ID that can be found in the 'source.extension.vsixmanifest' file, - for example: QtVsTools.30112013-cd02-4fd0-89bd-e36f85abe16a - { Version } Set to the Version that can be found in the 'source.extension.vsixmanifest' file, - for example: 2.0.0 - -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. -- cgit v1.2.3