View source for Install new kit to Qt Design Studio

'''<span style="color: red;">DISCLAIMER:</span> The procedure is only to be followed by EXPERT users of Qt Design Studio. Creating a non-standard setup with Qt Design Studio can result in incorrect behavior which is not covered with standard support.'''



For Qt Design Studio 4.5 build, the compiler version for MSVC is 2019. For later versions (Qt Design Studio 4.6 =>) the compiler is MSVC 2022.

Qt Design Studio comes preinstalled with Qt6 kit (as of in Qt DS4). This kit is a stripped-down version of Qt and cannot be used in production.

You need to change the configuration of the Qt Design Studio for a custom setup. This document describes the steps to use Qt Design Studio with an environment based on the standard Qt kit installation.

This describes the workflow for enabling a custom kit on the Windows environment. 

== Enable the Settings ==
Locate '''QtDesignStudio.ini''' file. This is stored in the same directory structure where Qt Design Studio is installed. On windows Qt is usually installed to '''C:\Qt''' directory. So the the path to Qt Design '''Studio ini''' file is:<syntaxhighlight lang="html">
C:\Qt\Tools\QtDesignStudio\share\qtcreator\QtProject\QtDesignStudio.ini
</syntaxhighlight>At this point, you should '''TAKE A BACKUP''' of the '''.ini''' file. In some cases, the file gets destroyed, and you cannot recover from it.

Open the file with a text editor, and find where Qt Creator item visibility is controlled:<syntaxhighlight lang="ini">
[General]
HideOptionCategories=C++, Debug, Designer, Kits, BuildAndRun, CPaster, LanguageClient, Version Control
SuppressedWarnings=LinkWithQtInstallation
</syntaxhighlight>Remove '<nowiki/>'''Kits'''<nowiki/>' and '''<nowiki/>'BuildAndRun'<nowiki/>''' from the options and save the file.

'''<span style="color: blue;">NOTICE:</span>''' You might need administrator rights to edit the file.

Start Qt Design Studio and continue to configure a kit.

== Configure the Kit for Use ==
'''<span style="color: blue;">NOTICE:</span>''' The customized kit should be the same version from baseline as the original kit from Qt Design Studio or it might not operate correctly.

First, check the version of the Qt kit that Qt Design Studio is currently using; it is in the bottom toolbar.
[[File:Kit select.png|none|alt=Qt Design Studio Bottom Toolbar|caption]]
To get the kit configuration options, select '''Edit > Preferences > Kits > Qt Versions.'''
[[File:Kit preferences.png|none|alt=Kit Preferences|caption]]In this tutorial, we are using Qt 6.7.2 as a kit (it is compatible with Qt 6.7.1).

Setting up a Qt kit is a two-step operation: First, you need to set the '''Qt''' '''Version,''' and then assign this to your kit.

=== Qt Version ===
To configure the '''Qt Version''' you need to find the ''''qmake'''<nowiki/>' binary from the build. This is located in:<syntaxhighlight lang="text">
<QTDIR>/<Qt Version>/<Arch>/bin
</syntaxhighlight>First, open the '''Qt Versions''' tab in the kit management dialog:
[[File:Kit management.png|none|alt=Kit Management|caption]]Select '''Add...,''' and from the next window browse and select the ''''qmake'''<nowiki/>' of your target environment. In our case, it can be found in this location:<syntaxhighlight lang="html">
C:\Qt\6.7.2\msvc2019_64\bin\qmake
</syntaxhighlight>Select '<nowiki/>'''OK'''<nowiki/>', and proceed to the next step.

=== Qt Kit ===
Now that the Qt Version is set, you need to define a kit that uses this version. To open the kit management, go to '''Edit > Preferences > Kits > Kits.'''

To add the kit here, select '''<nowiki/>'Add...',''' it expands the fields below.
[[File:Kit management add new kit.png|none|alt=Add a new kit|caption]]Here, you need to update two fields, '''Name''', and '''Qt Version'''.

You can give any '''Name you want''', however, for clarity you should follow this format of naming (see the next image for reference): <syntaxhighlight lang="text">
<Qt Version> <Intended Usage/Platform>
</syntaxhighlight>Select the '''Qt Version''' from the dropdown.
[[File:Kit management add new kit version.png|none|alt=Select the new kit version|caption]]Select, '''OK''' to add the new kit. 

The new kit is set now, however, it is not fully functional yet. Restart Qt Design Studio to make the changes effective.

== Qt Kit Preparation ==

=== Qt Modules ===
Qt Design Studio kit requires these two Qt Libraries:

* Qt Quick Timeline
* Qt Shader Tools 

If you don't have them, use the Maintenance Tool in the Qt folder to install them.

=== Qt Studio Components ===
Qt Design Studio uses a special library called Studio Components. This is a set of important QML types which are not yet part of the Qt offering. You need to install it manually. Use Qt Creator and follow the steps below: 
==== 1. Opening Studio Components Project in Qt Creator ====
Download or clone a copy of the Studio Components from the Qt Labs. You can find it from the link below: 

[https://github.com/qt-labs/qtquickdesigner-components Download Studio Components]

Open Qt Creator, then browse to and open the '''CMakeFiles.txt''' file from the downloaded Design Components folder. Qt Creator does the additional configurations automatically.

==== 2. Setting up the Build ====
First, open the '''Projects''' view in Qt Creator by selecting the wrench icon on the sidebar.
[[File:QtCreator project view.png|none|alt=Opening Project View in Qt Creator.|caption]]
Then, select '''Build.'''
[[File:QtCreator project view build.png|none|alt=Selecting Build from the Projects view|caption]]
From the Build Settings, select '''Install.''' Then, close the settings.
[[File:QtCreator project view build install.png|none|alt=Selecting the install option from the project view in Qt Creator.|caption]]
Select Compile to finalize the process. 
[[File:QtCreator project compile.png|none|alt=Compile in Qt Creator|caption]]

=== QML Puppet ===
'''<span style="color: blue;">NOTICE:</span>''' In some cases, the '''QML Puppet''' recompilation is not needed. However, it is safe to compile; especially if the kit has C++ libraries that differ from the original kit.

Before starting with '''QML Puppet,''' make sure you,

* Know the version of your Qt Design Studio.
* Know the Kit you are building against.
* Have a functional Qt Kit (tools such as CMake and Ninja working correctly).
* Have Qt Timeline, Qt 5 Compatibility Module, and Qt Shader Tools installed in the Qt Kit.

The '''QML Puppet''' is Qt Design Studio's runtime tool to run a '''QML''' project. Its sources are part of the Qt Creator repository. Regardless of the license used, you can find the sources from the link below.

[https://github.com/qt-creator/qt-creator Get the Sources of QML Puppet]

'''<span style="color: blue;">NOTICE:</span>''' Git gives you the '''master''' branch by default. You need to switch to the branch matching your Qt Design Studio. For this example, we use '''qds/4.5''' branch. 

QML Puppet sources are in the sub-folder:<syntaxhighlight lang="html">
src/tools/qml2puppet
</syntaxhighlight>Find the '''CMakeFiles.txt''' file in this folder, open it with the Qt Creator, and then define your build environment.

[[File:QML Puppet build environment setup.png|none|alt=QML Puppet build environment setup|caption]]Some helper options are available to simplify the process. In the CMake environment, select the '''BUILD_DESIGNSTUDIO''' option from the list before compiling.

[[File:QtCreator QML Puppet turn the macro on.png|none|alt=Turn the macro on in QML Puppet configuration.|caption]]With these settings, the puppet is automatically compiled and linked with the correct filename (with version). 

By default Qt Creator build environment is set to ''''Debug'''<nowiki/>'. You can change this from the build target dropdown, it opens from the following control:
[[File:QtCreator change mode.png|none|alt=Change the build environment in Qt Creator|caption]]We recommend selecting ''''Release with Debug Symbols'''.' This allows you to open the '''callstack''' if there is a crash.

For this example, we have cloned the sources to the following directory:  <syntaxhighlight lang="html">
C:\QtSrc\qt-creator
</syntaxhighlight>So, the full path to the source for the '''QML Puppet''' is:<syntaxhighlight lang="html">
C:\QtSrc\qt-creator\src\tools\qml2puppet
</syntaxhighlight>When you build the '''QML Puppet''', Qt Creator creates a build directory where the executable binary is located. In this example, that directory is:<syntaxhighlight lang="html">
C:\QtSrc\qt-creator\src\tools\qml2puppet\build\Desktop_Qt_6_7_2_MSVC2019_64bit-RelWithDebInfo
</syntaxhighlight>Typically, in the Windows environment, the '''install''' step is not automatically done for the executables. So, you need to copy the file from your build environment to the kit manually. 

Copy the binary, '<nowiki/>'''qml2puppet-<QDS VERSION>.exe'''<nowiki/>', from the build directory to the '<nowiki/>'''bin'''<nowiki/>' directory of the Qt environment. You can do it manually or follow this command:<syntaxhighlight lang="html">
copy C:\QtSrc\qt-creator\src\tools\qml2puppet\build\Desktop_Qt_6_7_2_MSVC2019_64bit-RelWithDebInfo\qml2puppet-4.5.1.exe C:\Qt\6.7.2\msvc2019_64\bin

</syntaxhighlight>The kit is ready now. You can run and display UI projects from Qt Design Studio.