WEC2013 and Qt

Introduction

On a regular basis we receive requests whether it is possible to run Qt applications on platforms running our iMX6 BSP. To be able to run Qt applications you need a "Qt Application SDK" which is build against our GuruCE iMX6 SDK. This article will show you how to build the Qt Application SDK so you can run Qt applications on a device running the GuruCE iMX6 BSP.

This step described in this text apply to the QT5.6 alpha release which (sort of) includes WEC2013 support in combination with Visual Studio 2013. The WEC2013 support in this version of Qt is not completely working yet so you'll need to perform some additional steps to make it all work.

We'll show you exactly what you need to do, and while we're at it we'll add support for Visual Studio 2015 as well!

This article seems quite big but actually it isn't all that hard. For the impatient; you'll find a quick reference guide of all the steps to follow at the end of this article.

Qt 5.6 Alpha Release

The instructions in this article apply to the Qt 5.6 alpha release. As soon as we have tested the official 5.6 release, and perhaps other future releases, we'll update this article so it all works with the latest Qt release.

Qt is an open-source project and the git repositories allow you to get the latest and, sometimes not so, greatest developer branches. You can find instructions for getting the complete source code tree from the git repository here. Qt is a very active project, which is good in a way, but it also means there are a lot of commits every day. This can easily result in a broken build, especially since not every commit is checked against all the different platforms and build environments (which make sense in a way). Our suggested approach is to pick the latest stable release and make that work. Of course you can take the latest alpha, beta or even developer branch but in that case you may want to prepare yourself for some long days/nights chasing build errors! ;-)

[Update 21/12/2015]
QT 5.6.0 Beta is released. You can find the patch needed in order to build QT5.6.0 beta here. There are no other changes required in order to build QT for WEC2013 just as described in this article, except that you need to run the beta patch.

Qt Prerequisites

You'll need to download and install a couple tools and packages before you can start building the Qt application SDK:

• Download and install Python. Make sure the Python binary folder is added to the system's %PATH% variable. This will be requested during installation.
• Download and install Perl. Also the Perl binaries must be accessible by the build system, and so the binary folder also needs to be added to the %PATH% system variable.
• Install Visual Studio 2013 or Visual Studio 2015.
• Install Application builder for Embedded Compact 2013".
• Download and install the latest GuruCE iMX6 SDK. You can pick any preferred platform. For Visual Studio 2015 you'll need the SDK of a release later than r550 (coming soon).
• Download the Qt 5.6 alpha release from this location. Extract the source to any folder but make sure the extracted source code is on the same drive as the "working directory" (the directory where your generated binaries will end up).

Patch the Qt sources

The current 5.6 alpha release won't build for Windows Embedded Compact without some changes to the Qt source tree. We have packaged up all required patches and made them available for download here). All these patches are made by us and may not conform to the Qt coding standards, so please monitor the bug tracker for Qt to see if better solutions become available.

One of the patches also results in some mkspec files to be copied into the "Qt source tree\qtbase\mkspec" folder. These mkspec's contain the configuration information for the development environment and target platform. In our case we need mkspec files to indicate we use Visual Studio 2013 or Visual Studio 2015, the GuruCE iMX6 SDK and a Windows Development machine.

All said and done, lets build a Qt Application SDK now!

Building the Qt Application SDK

1. Install the patches

Download the Qt56alpha_patches.zip file and extract it in the root of the QT5.6a source path. You should end up with a "patch" folder after extraction (e.g. H:\qt-everywhere-opensource-src-5.6.0-alpha\patch). Navigate to this patch folder and run the patch.bat batch file.

If you want to undo the patches just open a Command Prompt in the patch folder and run:

This will revert the changes made by our patches and restore the original Qt code tree.

2. Open Visual Studio 2013 or Visual Studio 2015 Developer Command Prompt

With Visual Studio 2013 there is no 'standard' start menu item for opening the Visual Studio 2013 "Developer command prompt", but shortcuts are available. Open a file explorer and navigate to the Shortcuts folder inside your Visual Studio installation folder, eg:

"C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\Tools\Shortcuts"

Run the shortcut: "Developer Command Prompt for VS2013"

For Visual Studio 2015 there is a start menu item for the Developer Command prompt, just type "Command" in the desktop search pane and it should show up:

In both cases (VS2013 or VS2015) you can drag the developer command prompt shortcut to the desktop. This allows you to quickly open a developer command prompt whenever needed.

3. Set %PATH% variable to the source path

In the Visual Studio 2013/2015 developers command prompt, navigate to your Qt working directory (e.g. H:\Qt\QT5.6a). Remember that QT5.6a source path and the work directory must be on the same drive. Add the QT5.6a source path to the %PATH% environment variable by executing the following command (of course change the drive and folder name if needed):

You can also add this variable to the system environment variables. In that case you must not forget to change it in case you change the Qt working folder (for instance when you want to build a Qt Application SDK against a different Qt source tree). Setting the Qt source path in the command prompt is the most flexible way and allows you to build a Qt SDK against different Qt source trees.

4. Configure the Qt build environment

Execute the following command in the Visual Studio 2013 Developer command prompt (followed by enter):

Or for Visual Studio 2015 execute the following:

Now relax, take a deep breath and we'll go over the parameters while configure.bat runs (shouldn't take more than a minute or so).

The configure tool will generate the configuration and build tools needed to build Qt for the given platform and environment. Check the Qt documentation for detailed information regarding the configure tool.

-plaform	win32-msvc2013 -or- win32-msvc2015: Specifies Windows Desktop and Visual Studio version.
-xplatform	The target platform: the GuruCE iMX6 SDK.
-rtti	Compile run-time type information.
-mp	Enable multi-processors when building the SDK.
-ltcg	Use link-time code generation.
-release	Build a release configuration for the SDK.
-opensource	Compile and link the open source edition of Qt Check Qt licensing for more info.
-confirm-license	By specifying this parameter you automatically accept the selected Qt license (in our case this is the open-source license).
-nomake	Exclude a specific part from the build. In our case we skip building the tests. In case you want to save some disk space you can specify -nomake examples. This will leave out the Qt examples. In our case we want to use the examples later on so don't specify -nomake examples.
-no-compile-examples	Indicates not to compile the examples but include them as source in the SDK.
-opengl	The GuruCE iMX6 BSP fully supports hardware accelerated OpenGL ES2.0, so enable es20 in Qt.
-openvg	The GuruCE iMX6 BSP fully supports hardware accelerated OpenVG, so enable OpenVG in Qt.
-skip	This will exclude complete modules from the build. In our case we skip the qtandroidextras, qtactiveqt and qtsensors modules.
-prefix	This indicates the path of where to install the SDK locally. If you don't specify the -prefix parameter, everything will be installed in the working directory.

When configure.bat is finished you can review the used configuration settings by checking the "config.summary" file, which is located in the generated qtbase folder (in our case H:\Qt\QT5.6a\qtbase).

5. Build the Qt Application SDK; time for coffee!

To start the build process the only thing left to do is to enter the following command in the Visual Studio 2013/2015 Developer command prompt:

This process will take roughly an hour depending on your development machine configuration.

Install the SDK

When the build is done we can generate the Qt Application SDK installer. Type the following command followed by enter:

This will generate the folder specified by the -prefix in the configure command line, in our case H:\Qt\QT5.6a\SDK.

The last thing we need to do is copy a qt.conf file into the SDK's bin folder. qt.conf is used to override hard-coded paths defined in the Qt libraries. The qt.conf file specifies where a Qt application can find libraries to link against. Every application needs a seperate qt.conf file if it's not present in the SDK\bin folder.

The contents of the qt.conf are quite simple:

[Paths]
Prefix=..


Download and extract the qt.conf.zip file and copy the qt.conf file to the generated SDK\bin folder (e.g. H:\Qt\QT5.6a\SDK\bin).

That's it! Now you can copy the SDK folder to the device. The size of the Qt Application SDK is approximately 420MB so this Qt Application SDK can be easily shared among developers.

Test Qt

When the Qt Application SDK is built, installed and it contains the qt.conf file in the SDK\bin directory, we can copy the Qt Application SDK to the device and run a Qt application:

• Copy the SDK folder to the Windows Embedded Compact device.
  You can copy the SDK folder to the root of an SD card and insert the SD card into the device running CE. The Qt Application SDK folder contains an "examples" folder with sample applications you can try. To run the sample applications continue the steps below.
• Telnet to the device.
• Navigate to the Qt Application SDK bin folder: cd \SD\SDK\bin.
• Start qml.exe with the following parameters, followed by ENTER:

Quick reference guide

This is a summary of all the steps required to build the Qt Application SDK for the GuruCE iMX6 SDK:

Update October 2020

Thanks to Stan Morris we can now provide an update to all of the above. There are two issues with the above instructions and patches:

• Missing configure argument which expose crash defect QTBUG-87767
• mkspecs settings result in debug build stability issues

Regarding the crash defect in Qt related to the build instructions in this post, the “configure” command line needs the “-qreal float” argument.

The Qt 5.6 defect involves evaluating an uninitialized “double” in QML. Stan wrote up the defect in QTBUG-87767.

This post’s linked Qt56alpha_patches.zip file contains mkspec files that have bad settings for debug builds which cause stability issues when debugging. Specifically, it is the /MTd flag that causes a problem. You can read a little about it on stack overflow.

Bad directives:


QMAKE_CFLAGS_DEBUG += -Zi -MTd
QMAKE_CFLAGS_DEBUG -= -MDd


Corrected directives:


QMAKE_CFLAGS_DEBUG += -Zi