| /**************************************************************************** |
| ** |
| ** Copyright (C) 2019 The Qt Company Ltd. |
| ** Contact: https://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 https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://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: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \page winrt_support.html |
| \title Qt for UWP |
| \brief Running Qt applications on devices supporting the |
| Universal Windows Platform (UWP). |
| \ingroup supportedplatform |
| |
| Qt for UWP allows you to run Qt applications on devices supporting the |
| Universal Windows Platform (UWP). Microsoft Windows 10 introduced UWP, which |
| provides a common application platform on every device that runs Windows 10, |
| as a successor to Windows Runtime (WinRT) introduced by Windows 8. The UWP |
| core APIs are the same on all Windows devices, and therefore applications |
| that only use the core APIs will run on any Windows 10 device, such as a |
| desktop PC, or Xbox One. |
| |
| The Qt port was originally written for WinRT and updated to support UWP. The |
| port uses the C++ capabilities. While UWP supports the component |
| extensions internally, they are not used inside Qt and you do not need to |
| use them. UWP applications run in a sandboxed environment for security |
| reasons and support different architectures, such as ARM and x86. |
| |
| \target winrt-supported-configurations |
| \section1 Supported Configurations |
| |
| The following configurations are supported. |
| |
| \include supported-platforms.qdocinc winrt |
| |
| \section1 Requirements |
| |
| Development for UWP requires a Microsoft Windows development host. |
| The minimum version supported is Windows 10. |
| |
| Qt supports UWP apps running on any variant of Windows 10 or later on the |
| desktop PC, IoT, Xbox One, and so on. |
| |
| If you are targeting a remote device, follow the instructions by |
| Visual Studio to set it up correctly. |
| |
| \section1 Getting Started |
| |
| \section2 Notes to Desktop Users |
| |
| As UWP applications run in a sandboxed environment, some restrictions should be taken |
| into account when considering porting or writing cross-platform applications: |
| |
| \list |
| \li The class QProcess is not implemented (indicated by the macro \c QT_NO_PROCESS |
| being defined) as no subprocesses can be launched. |
| \li Some paths returned by QStandardPaths::writableLocation() may be empty. |
| \li A UWP application may not do socket-based communication with another application |
| running on the same host (as this would violate the sandboxing). |
| \li Applications run in fullscreen mode only (see QStyleHints). On desktop, |
| the screen size varies as the application is resized. |
| \li There are no environment variables. Qt emulates the functionality |
| by maintaining the values locally, so that qputenv() and related |
| functions continue to work. All known variables influencing Qt can |
| be set in source code. |
| \li UWP applications are UI applications by nature. This implies that |
| console type applications will have a window created internally, |
| which is always visible. |
| \li Applications should not exit programmatically. In particular, calling |
| exit() before the UI is shown causes a crash. |
| \li The UWP clipboard is local to the application; it cannot be retrieved |
| by a desktop application. |
| \endlist |
| |
| \section2 Building Applications |
| |
| You can develop applications for UWP 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 <your project>.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 <your project>.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 UWP 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 UWP 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 for Windows, |
| this will only create binaries for UWP. 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 UWP 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 UWP mkspec format is \c {<platform>-<architecture>-<toolchain>} |
| where architecture can be \c arm, \c x86, or \c x64. The following is an |
| example of building qtbase for UWP: |
| \code |
| > ./configure -xplatform winrt-x64-msvc2017 -release |
| > nmake/jom |
| \endcode |
| |
| \section1 Running Applications from Command Line |
| |
| UWP 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 UWP 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' |
| 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 [options] package [arguments] |
| winrtrunner installs, runs, and collects test results for packages made with Qt. |
| |
| Options: |
| --test Install, start, collect output, stop (if |
| needed), and uninstall the package. This is |
| the default action of winrtrunner. |
| --start Start the package. The package is installed |
| if it is not already installed. Pass |
| --install to force reinstallation. |
| --debug <debugger> Start the package with the debugger |
| attached. The package is installed if it is |
| not already installed. Pass --install to |
| force reinstallation. |
| --debugger-arguments <arguments> Arguments that are passed to the debugger |
| when --debug is used. If no debugger was |
| provided this option is ignored. |
| --suspend Suspend a running package. When combined |
| with --stop or --test, the app will be |
| suspended before being terminated. |
| --stop Terminate a running package. Can be be |
| combined with --start and --suspend. |
| --wait <seconds> 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 <name|index> 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 <name> Force a particular run profile. |
| --list-devices List the available devices (for use with |
| --device). |
| --verbose <level> The verbosity level of the message output |
| (0 - silent, 1 - info, 2 - debug). Defaults |
| to 1. |
| --ignore-errors Always exit with code 0, regardless of the |
| error state. |
| --loopbackexempt <mode> Enables localhost communication for |
| clients,servers or both. Adding this |
| possibility for servers needs elevated |
| rights and might ask for these in a |
| dialog.Possible values: client, server, |
| clientserver |
| -?, -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 |
| */ |
