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).

The Qt 5.6 alpha source path used in this article is: H:\qt-everywhere-opensource-src-5.6.0-alpha
The Qt working directory used in this article is: H:\Qt\QT5.6a

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:

H:\qt-everywhere-opensource-src-5.6.0-alpha\patch>patch -u

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):

set PATH=%PATH%;H:\qt-everywhere-opensource-src-5.6.0-alpha

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):

H:\Qt\QT5.6a>configure -platform win32-msvc2013 -xplatform wince80GuruCE-armv7-msvc2013 -rtti -mp -ltcg -release -opensource -confirm-license -no-compile-examples -nomake tests -opengl es2 -openvg -skip qtandroidextras -skip qtactiveqt -skip qtsensors -prefix %CD%\SDK

Or for Visual Studio 2015 execute the following:

H:\Qt\QT5.6a>configure -platform win32-msvc2015 -xplatform wince80GuruCE-armv7-msvc2015 -rtti -mp -ltcg -release -opensource -confirm-license -no-compile-examples -nomake tests -opengl es2 -openvg -skip qtandroidextras -skip qtactiveqt -skip qtsensors -prefix %CD%\SDK

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:

H:\Qt\QT5.6a>nmake

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:

H:\Qt\QT5.6a>nmake install

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:

\SD\SDK\bin>qml ..\examples\quick\animation\animation.qml

Telnet Screenshot

  • Choose any of the samples, for example "ColorAnimation":

    Running Qt Animation Application

    Is it really all that great?

    This article describes how to build the Qt Application SDK and how you can run a simple Qt application. We have not tested the Qt Application SDK more than what we described in this article. Testing all features of Qt is certainly possible, but our time is better spend adding low-level functionailty to our iMX6 BSP. We are certain there are more problems in the Qt source code than what we discovered so far; Windows Embedded Compact specific, but most probably also generic issues. Hopefully the final release of Qt 5.6 will solve a lot of the issues we have discovered. It's always good to participate and report issues to the Qt community, like we did as well. Current known issues we see in Qt 5.6 alpha are for instance:

  • qmlscene.exe sample application crashes. [update 18-12-2015] This is fixed now in the new patch
  • Visual Studio plugin is not accepting the Qt Application SDK build.
  • And probably some more...
  • Quick reference guide

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

    The Qt 5.6 alpha source tree location: H:\qt-everywhere-opensource-src-5.6.0-alpha
    The Qt working directory: H:\Qt\QT5.6a

    Nr. Description Command
    1 Make sure you meet the prerequisites and QT5.6a code tree is extracted (e.g. H:\qt-everywhere-opensource-src-5.6.0-alpha) -
    2 Download and extract the Qt56alpha_patches.zip file in the root of the QT5.6a source tree -
    3 Open a command prompt in the root of the Qt source code tree and run the patches: \H:\qt-everywhere-opensource-src-5.6.0-alpha\patch\patch.bat
    4 Exit command prompt exit
    5 Open VS2013 or VS2015 Developer command prompt and navigate to the work directory cd H:\Qt\QT5.6a
    6 Run the Qt configure tool for Visual Studio 2013 configure -platform win32-msvc2013 -xplatform wince80GuruCE-armv7-msvc2013 -rtti -mp -ltcg -release -opensource -confirm-license -no-compile-examples -nomake tests -opengl es2 -openvg -skip qtandroidextras -skip qtactiveqt -skip qtsensors -prefix %CD%\SDK
    - or -
    6 Run the Qt configure tool for Visual Studio 2015 configure -platform win32-msvc2015 -xplatform wince80GuruCE-armv7-msvc2015 -rtti -mp -ltcg -release -opensource -confirm-license -no-compile-examples -nomake tests -opengl es2 -openvg -skip qtandroidextras -skip qtactiveqt -skip qtsensors -prefix %CD%\SDK
    7 Build the SDK nmake
    8 Install the SDK nmake install
    9 Download and extract the qt.conf.zip file. Copy qt.conf to SDK\bin -
    10 Copy/FTP the Qt Application SDK to the device (~420MB) -
    11 Telnet to the device telnet 192.168.2.15
    12 Navigate to SDK location cd \sd\SDK\bin
    13 Run the animation sample qml ..\examples\quick\animation\animation.qml

    Comments

    Hello Erwin,

    I installed QT with your guide, but I get an error trying to run a sample.
    Error message on WEC 2013 is "Cannot Execute \Hard Disk\sdkfs\bin\qml.EXE"
    That's not pretty much :-(

    Can anybody help?

    Hi Tobias,

    Missed your comment sorry. Difficult to tell from here.
    - \Hard Disk\sdkfs? "sdkfs" is that a typo or just the name of your SDK?
    - Is the qml.exe really present in the bin file? I mean did the build and install succeed?
    - What board did you use, did you use one of the online kernels or your own?

    If you would like I could send you my generated SDK an you can retry?

    Hi Erwin,

    "sdkfs" is my name of the sdk.
    The qml.exe is also present and i`ve got no error during build and install process.
    I use a efus board from our distributor fs-net.de.

    Can you send me a link to download your SDK? Then i will try it and hope it will run on my board.

    Sure, just send me an email and I will pass on the SDK. My email constructs of myfirstname at guruce.com

    Hello Erwin,

    Can I use QT on my WEC2013 device without commercial licence?

    Thanks in advance