1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
|
/****************************************************************************
**
** 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 wasm.html
\title Qt for WebAssembly
\brief Runs Qt applications in a secure sandbox in the browser.
\ingroup supportedplatform
WebAssembly is a binary format that allows sand-boxed executable code
in web pages. This format is nearly as fast as native machine code, and
is now supported by all major web browsers.
Qt for WebAssembly is a \l {Qt Platform Abstraction}{platform plugin} that
lets you build Qt applications, which can be integrated into your web pages.
It doesn't require any client-side installations and reduces the server-side
resource usage.
\section1 Getting Started with Qt for WebAssembly
\section2 Install Emscripten
\l{https://emscripten.org/docs/introducing_emscripten/index.html}{emscripten}
is a toolchain for compiling to asm.js and WebAssembly.
It lets you run Qt on the web at near-native speed without plugins.
Refer to the \l{http://kripken.github.io/emscripten-site/docs/getting_started/index.html}
{emscripten documentation} for more information about checking out the
Emscripten SDK and installing and activating Emscripten for your Qt version.
After installation, you should have emscripten in your path.
Check this with the following command:
\badcode
em++ --version
\endcode
Each minor release of Qt supports a known-good Emscripten version. That Emscripten
version will be supported for the lifetime of that Qt version.
The known-good versions are:
\list
\li Qt 5.12: 1.38.16
\li Qt 5.13: 1.38.27 (multithreading: 1.38.30)
\endlist
Use \c emsdk to install specific \c emscripten versions. For example, to install
it for Qt 5.13, enter:
\list
\li ./emsdk install sdk-1.38.27-64bit
\li ./emsdk activate --embedded sdk-1.38.27-64bit
\endlist
The \c --embedded option is useful if you want to install multiple versions of the SDK.
It locates all configuration and cache files inside the SDK so that multiple versions
do not conflict.
After installation, you should have emscripten in your path. Check this with the following command:
\badcode
em++ --version
\endcode
\section3 Download the binaries
The binary builds can be downloaded in the Downloads section using your Qt
account.
\section3 Build Qt from the sources
Alternatively, you could download the Qt sources in the Downloads section,
and build Qt from it.
Configure Qt as a cross-compile build for the \c wasm-emscripten platform.
This will implicitly set the "-static" and "-no-feature-thread" options.
Pass the \c-compile-examples option to enable examples.
\badcode
./configure -xplatform wasm-emscripten -nomake examples -prefix $PWD/qtbase
\endcode
On Windows, make sure you have \c MinGW as well as \c sed in your \c PATH
and configure with the following:
\badcode
configure -no-warnings-are-errors -xplatform wasm-emscripten -platform win32-g++ -nomake examples -prefix %CD%\qtbase
\endcode
Build required modules:
\badcode
make module-qtbase module-qtdeclarative [other modules]
\endcode
The Qt build is a static build, and does not support threads.
\section3 Build and run your application
\badcode
$ /path/to/qt-wasm/qtbase/bin/qmake
$ make
\endcode
This generates the following files:
\table
\header
\li Generated file
\li Brief Description
\row
\li app.html
\li HTML container
\row
\li qtloader.js \li JS API for loading Qt apps
\row
\li app.js
\li JS API for loading Qt apps
\row
\li app.wasm
\li emscripten app binary
\endtable
When deploying the app, the compression is typically handled on
the server side. We recommend to compress the wasm binaries because
this typically reduces the size of the binary by 50 %.
\sa {WebAssembly Resource site},{Getting Started with Qt for WebAssembly},
{Remote UIs with WebGL and WebAssembly}
\section1 Test-run your application
You can test-run your application in the following way:
\badcode
/path/to/emscripten/emrun --browser=firefox appname.html
\endcode
\section1 Some examples
\list
\li \l {http://example.qt.io/qt-webassembly/opengl/hellowindow/hellowindow.html}
{An example displaying a Qt logo using OpenGL calls}
\li \l {http://example.qt.io/qt-webassembly/SensorTagDemo/SensorTagDemo.html}
{An industry automation use case}
\li \l {http://example.qt.io/qt-webassembly/quickcontrols2/gallery/gallery.html}
{A gallery of available controls in Qt Quick Controls}
\li \l {http://example.qt.io/qt-webassembly/widgets/richtext/textedit/textedit.html}
{A simple text editor, written with Qt Widgets}
\endlist
\section1 Limitations
The most important limitation is that the Qt build is static,
and does not support threads.
For further info, refer to \l { https://wiki.qt.io/Qt_for_WebAssembly#Known_issues_and_platform_notes}{Known_issues_and_platform_notes}.
\section1 External resources
\list
\li \l {Qt for WebAssembly Technology Preview}
\li \l {Qt and WebAssembly}
\li \l {Qt for WebAssembly wiki}
\li \l {Getting Started with Qt for WebAssembly}
\li \l {Remote UIs with WebGL and WebAssembly}
\li \l {WebAssembly Resource site}
\endlist
\section1 Licenses
Qt for WebAssembly is available under commercial licenses from \l{The Qt Company}.
In addition, it is available under the \l{GNU General Public License, version 3}.
See \l{Qt Licensing} for further details.
*/
--------------------------
A couple of comments:
1. We should have a point about installing the 1.38.27 Emscripten SDK like in the wiki. Unfortunately there are sometimes changes in the SDK that breaks Qt, so we need to make sure everyone is on the same version as us.
2. It has instructions for "build Qt from sources". Starting with Qt 5.13.0, we will have binary packages, so this will be the main way people use it. We could have a section about how to build as an optional step but mention that it is optional. Also, it currently says "5.12", but this should probably not specify version number.
3. Two additional things it would be useful to have there: The instructions on how to test-run an application (/path/to/emscripten/emrun --browser=firefox appname.html) and Supported Qt Modules.
|
