/**************************************************************************** ** ** Copyright (C) 2015 The Qt Company Ltd. ** Contact: http://www.qt.io/licensing/ ** ** This file is part of the documentation of the Qt Toolkit. ** ** $QT_BEGIN_LICENSE:FDL$ ** Commercial License Usage ** Licensees holding valid commercial Qt licenses may use this file in ** accordance with the commercial license agreement provided with the ** Software or, alternatively, in accordance with the terms contained in ** a written agreement between you and The Qt Company. For licensing terms ** and conditions see http://www.qt.io/terms-conditions. For further ** information use the contact form at http://www.qt.io/contact-us. ** ** GNU Free Documentation License Usage ** Alternatively, this file may be used under the terms of the GNU Free ** Documentation License version 1.3 as published by the Free Software ** Foundation and appearing in the file included in the packaging of ** this file. Please review the following information to ensure ** the GNU Free Documentation License version 1.3 requirements ** will be met: http://www.gnu.org/copyleft/fdl.html. ** $QT_END_LICENSE$ ** ****************************************************************************/ /*! \page winrt_support.html \title Qt for WinRT \brief Provides insight into Qt's WinRT port and how to use it. \ingroup supportedplatform Qt for WinRT allows you to run Qt applications on devices supporting the Windows Store App APIs. This includes Modern UI applications in Windows 8.1 and up, as well as devices running Windows RT 8.1 and Windows Phone 8.1 and up. Microsoft introduced a new design paradigm with the Windows 8 Modern UI. A core part of this new approach is Windows Runtime (WinRT) that supports development using different programming languages, such as C++/CX (component extensions), C# VB.NET, or JavaScript. The Qt port uses the C++ capabilities. While WinRT supports the component extensions internally, they are not used inside Qt and you do not need to use them. WinRT applications run in a sandboxed environment for security reasons and support different architectures, such as ARM and x86. \section1 Requirements Development for Windows Runtime requires a Microsoft Windows development host. The minimum version supported is Windows 8.1. Depending on your device target you will need the following tools provided by Microsoft to be installed: \table \header \li Device Target \li Environment \row \li Windows 8.1 Modern UI \li Visual Studio 2013 for Windows \row \li Windows RT \li Visual Studio 2013 for Windows \row \li Windows Phone 8.1 \li Visual Studio 2013 for Windows Phone \row \li Windows 10 \li Visual Studio 2015 \endtable If you are targeting a remote device, please follow all instructions by Visual Studio to set it up correctly. If you are targeting an emulator for Windows Phone, Windows 8.1 Pro is required by Microsoft to launch the emulator itself. \section1 Getting Started \section2 Building Applications You can develop applications for WinRT just as any other Qt applications. Use your favorite editor or IDE (such as Qt Creator) and create your application or load a Qt example. Then run \c qmake and \c {nmake/jom} to build your application. \section3 Building Applications with Visual Studio To launch your project with Visual Studio a corresponding project needs to be created. \c qmake supports converting a \c .pro project into Visual Studio format by passing the parameters \c -tp vc. \code qmake -tp vc .pro \endcode Be aware of using the correct match of \c qmake and Visual Studio. As the Visual Studio format is generic, it does not return an immediate error if for instance you open a Windows Phone project inside Visual Studio for Windows. This creates a project which supports building applications and running them with Visual Studio. It does not embed Qt libraries into the package and requires you to add them manually. For this purpose, the command line tool \l{The Windows Deployment Tool}{windeployqt} has been included in the installed package. To enable automatic parsing of dependencies and adding the libraries and dependencies into the application package, create the project with the following options: \code qmake -tp vc .pro "CONFIG+=windeployqt" \endcode \section3 Building Applications with Qt Creator You will not need to do any conversion to open your project in Qt Creator. Please follow the generic instructions on how to open and build a project. Qt Creator deploys your application on the WinRT device, if the device is detected by the PC. \note Remote PCs, such as the Surface, are not yet supported for deployment by Creator. \section1 Building from Source We assume that you have cloned the Qt 5 repositories (or obtained the Qt sources elsewhere) and followed the platform-independent requirements for building Qt. The process of building Qt is found in the \l{Building Qt Sources} page. Qt for WinRT is always built as a cross-build, because tools, such as qmake, are built as desktop applications. For compiling those, a desktop development environment is required. If you have installed Visual Studio 2013 for Windows, this will only create binaries for WinRT. You will need Visual Studio for Windows Desktop as well to create those desktop tools. Please make sure to use an x86 command prompt (either use the \e {VS x86 Native Tools Command Prompt} or call \e vcvarsall.bat without any parameter or with \c x86) for every WinRT/Windows Phone build. While the toolchain which is used for the target is set automatically, the command prompt decides what will be used for the host tools like \e qmake or \e moc. Building these tools might fail if another command prompt is used. The WinRT mkspec format is \c {--} where \e platform can be \c winrt or \c winphone and architecture can be \c arm, \c x86, or \c x64. The following is an example of building qtbase for WinRT: \code > ./configure -xplatform winrt-x64-msvc2013 -release > nmake/jom \endcode \section1 Running Applications from Command Line WinRT applications must be packaged (including all dependencies) and installed or registered with the application service in order to be launched. \l{winrtrunner}{The WinRT Runner Tool} can be used to launch these applications from the command line. \section2 Package Content Package content consists of the application executable and its dependencies, as for every Windows application. The dependencies are the needed (Qt) libraries and plugins. Note that Qt plugins have to be put into a folder named after their category (platforms, imageformats, and so on) without using a \c plugins folder as root. For more information, see \l{Qt for Windows - Deployment}. As WinRT applications are run in a sandboxed environment, setting the path variable to point to the files required will not work. The \l{The Windows Deployment Tool}{windeployqt} convenience tool looks up the application's dependencies and copies Qt libraries and plugins to the appropriate directories, as necessary. Because all resources are placed to one directory, you can register the directory using an XML file (AppxManifest.xml) and Windows Powershell. The reference for these manifest files can be found \l{http://msdn.microsoft.com/en-us/library/windows/apps/br211473.aspx}{here}. The target processor architecture must be specified (as opposed to the default, 'neutral'). As soon as these requirements are met, change into your \e packaged directory in PowerShell and call: \code > Add-AppxPackage -Register AppxManifest.xml \endcode \note \l{winrtrunner}{The WinRT Runner Tool} can perform the same operation with the --install option. If that worked, you should be able to find your application in Windows 8.1's start screen. To remove your application, use Windows' built-in way to uninstall applications (right-click or tap and hold the application and choose \c{Uninstall}). \note \l{winrtrunner}{The WinRT Runner Tool} can perform the same operation with the --remove option. \section2 WinRT Runner Tool \target winrtrunner The WinRT Runner Tool can be found in QTDIR/bin/winrtrunner. It is intended to aid in the deployment, launching, and debugging of Qt for WinRT applications. It can be used from the command line, or invoked by the IDE. \badcode Usage: winrtrunner.exe [options] package [arguments] winrtrunner installs, runs, and collects test results for packages made with Qt. Options: --test Installs, starts, collects output, stops (if needed), and uninstalls the package. This is the default action of winrtrunner. --start Starts the package. The package is installed if it is not already installed. Pass --install to force reinstallation. --debug Starts the package with the debugger attached. The package is installed if it is not already installed. Pass --install to force reinstallation. --debugger-arguments Sets the arguments to be passed to the debugger when --debug is used. If no debugger was provided, this option is ignored. --suspend Suspends a running package. When combined with --stop or --test, the app will be suspended before being terminated. --stop Terminates a running package. Can be be combined with --start and --suspend. --wait If the package is running, waits the given number of seconds before continuing to the next task. Passing 0 causes the runner to wait indefinitely. --install (Re)installs the package. --remove Uninstalls the package. --device Specifies the device to target as a device name or index. Use --list-devices to find available devices. The default device is the first device found for the active run profile. --profile Forces a particular run profile. --list-devices Lists the available devices (for use with --device). --verbose Sets the verbosity level of the message output (0 - silent, 1 - info, 2 - debug). Defaults to 1. --ignore-errors Always exits with code 0, regardless of the error state. -?, -h, --help Displays this help. Arguments: package [arguments] The executable or package manifest to act upon. Arguments after the package name will be passed to the application when it starts. \endcode */