/****************************************************************************
**
** 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)
   \li Qt 5.14: 1.38.27 (multithreading: 1.38.30)
   \li Qt 5.15: 1.39.8
\endlist

Use \c emsdk to install specific \c emscripten versions. For example, to install
it for Qt 5.15, enter:
\list
    \li ./emsdk install 1.39.8
    \li ./emsdk activate --embedded 1.39.8
\endlist

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.