Managing Projects

Once you have installed Qt VS Tools, you can select the following project templates in Visual Studio in File > New Project > Installed > Templates > Visual C++ > Qt:

  • Qt GUI Application creates a simple Qt GUI Application with one form.
  • Qt Custom Designer Widget creates a Qt Designer custom widget plugin.
  • Qt Console Application creates a basic Qt console application.
  • Qt Class Library creates a basic Qt-based dynamic library.
  • Qt ActiveQt Server creates a simple ActiveX server.

Each Qt project provides a wizard that allows you to specify the Qt modules required for your project. For some projects, the wizard will also generate a skeleton class that you can use to get started.

To start writing Qt code and building your projects, you must tell Visual Studio where to find the Qt version that you want to use.

Managing Qt Versions

Qt VS Tools provide you with basic Qt version management that enables you to use multiple versions of Qt 5 in parallel. For example, Qt 5.6.1 and 5.7.0. When you install Qt VS Tools, the information about Qt versions is added to the user registry hive. So, other users will have to add a new Qt version, because no default version will be set.

Qt Versions

To manage Qt versions:

  1. Select Qt VS Tools > Qt Options > Qt Versions > Add.
  2. In the Version name field, enter a name for the Qt version.
  3. In the Path field, enter the path to the Qt root directory. For example: C:\Qt5\5.7\msvc2013_64.
  4. Select OK.
  5. In the Default Qt/Win version field, select the Qt version to be used by default when creating new projects or importing a project from a .pro file.

To use the Qt version set in the QTDIR environment variable, create a version named $(QTDIR). Because the path is not needed, the Path field is disabled. You must restart Visual Studio to make it aware of the new environment variable.

To specify the Qt version that the selected project should use, select Qt VS Tools > Qt Project Settings > Properties > Version.

To change the Qt version for all projects in a solution, select Change Solutions' Qt Version in the context menu, and then select a Qt version in the Installed Qt Versions field.

Note: When you set a Qt version for the solution, it becomes the default version for the new projects that you add to the solution.

Using Qt VS Tools does not require a globally set Qt environment variable. In fact, Qt VS Tools will always overwrite the existing global Qt environment variable.

Note: If building Qt projects fails with the error message The following environment variables were not found: $(QTDIR), the project might have an invalid Qt build specified. For example, the specified Qt version has been uninstalled. To fix this error, specify a valid Qt version for the project.

Qt VS Tools handle everything you need in order to create applications for Windows, so you do not need to add a platform manually using the Visual Studio Configuration Manager. Qt VS Tools create the platform required for the selected Qt version, if necessary.

To switch between platforms, choose the appropriate Qt version in the Version field.

Modifying Project Properties

The properties of new Qt projects are initialized to the values specified in Qt VS Tools > Qt Project Settings.

To modify properties for a particular Qt project, select it in the solution explorer, and then select Qt VS Tools > Qt Project Settings.

Qt Project Settings dialog

You can change the following Qt project settings in the Properties tab:

PropertyDescription
LReleaseOptionsAdditional command-line options for the lrelease tool.
lupdateOnBuildA flag that determines whether to create the translation files while building the project.
LUpdateOptionsAdditional command-line options for the lupdate tool.
MocDirectoryThe directory (relative to the project) where the generated moc files are put. This directory must include the $(ConfigurationName) variable to ensure that the moc files for different configurations (such as debug or release) do not collide. You can use the $(PlatformName) variable to place the files generated for different platforms into separate directories.
MocOptionsAdditional command-line options for the moc build step.
RccDirectoryThe directory (relative to the project) where the rcc generated source files are put.
UicDirectoryThe directory (relative to the project) where the uic generated header files are put.
VersionThe Qt version to use for this project.

Select Qt Modules to add and delete dependencies for the project.

Importing and Exporting Projects

Qt and Visual Studio use different file formats to save projects. If you build your application on multiple platforms, you probably already use Qt .pro files with qmake. Otherwise, you might use .vcproj files and Visual Studio to build your project, which is usually more convenient for Windows-only development.

Qt VS Tools provide a way to combine both approaches so that you do not have to manually maintain .pro files and .vcproj files in parallel. You start by creating a .vcproj file, as usual. When you need a qmake .pro file for storing Linux and macOS specific settings, select Qt VS Tools > Create Basic .pro File.

Export Projects dialog

If you have multiple Qt projects in one Visual Studio solution, the basic .pro file generator can create a master .pro file of type subdirs that includes all of the projects.

The generated .pro file is not meant to be a complete file, but a simple starting point for porting to other platforms. However, these files should be sufficient for compiling the skeleton projects created by the predefined Qt project wizards. The .pro file includes a .pri file.

The .pri file contains the list of source files, header files, .ui files, and .qrc files in the project. To generate the .pri file, select Qt VS Tools > Export Project to .pri File. When you add or remove a file from the Visual Studio project file, you must regenerate the .pri file to ensure that the application can still be built on other platforms.

Also, make sure that the .pri file included in the .pro file points to the correct file. If you saved the .pri file using the suggested path and name, this reference should be correct.

Developers on platforms other than Windows might add or remove files to the project by editing the .pri file. When this happens, Windows developers must select Qt VS Tools > Import .pri File to Project to synchronize the Visual Studio project file with the .pri file.

If your project contains platform-specific source files, you should list them in the .pro file so that they are not overwritten by Qt VS Tools.

To summarize, a cross-platform Qt project consists of the following files:

  • A .vcproj file containing Windows-specific settings and listing the files in the project.
  • A .pro file containing Linux and macOS specific settings.
  • A .pri file (a qmake include file) listing the files in the project.

If you already have a .pro file but no .vcproj file, select Qt VS Tools > Open Qt Project File (.pro) to convert your .pro file to a .vcproj file. The generated .vcproj only contains Windows-specific settings. Also, there is no other way to convert a .vcproj file back to the .pro file format than using the Create Basic .pro File function.

© 2016 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.