/****************************************************************************
**
** Copyright (C) 2020 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 qtwebengine-platform-notes.html
    \title Qt WebEngine Platform Notes

    \brief Contains information about issues that are specific to the \QWE module.

    \section1 Building \QWE from Source

    Static builds are not supported.

    The requirements for building Qt 5 modules from source are listed separately for each supported
    platform:

    \list
        \li \l{Qt for Windows - Requirements}
        \li \l{Qt for X11 Requirements}
        \li \l{Qt for macOS - Building from Source}
    \endlist

    In addition, the following tools are required for building the \l {Qt WebEngine} module:

    \list
        \li \l {All Platforms}
        \li \l {Windows}
        \li \l {Linux}
        \li \l {macOS}
    \endlist

    The tests for skipping the \QWE build are located in the
    \c qtwebengine repository, in the \c tools\qmake\mkspecs subdirectory.
    They can be found by searching for \c skipBuild.

    \section2 All Platforms

    On all platforms, the following tools are required at build time:

    \list
        \li \l Python 2.7.5 or later. Python 3 is not supported.
        \li Bison, Flex
        \li GPerf
        \li Node.js version 8 or later (version 12 or later is recommended)
    \endlist

    \section2 Windows

    On Windows, the following additional tools are required:

    \list
        \li Visual Studio 2017 version 15.8 or later, or clang-cl version 8 or later
        \li Active Template Library (ATL), usually included in the Visual Studio
            installation
        \li Windows 10 SDK version 10.0.19041 or later
    \endlist

    \QWE can only be built on 64-bit Windows, with a x64-bit toolchain.
    For building \QWE for x86 applications, you need to configure
    and compile Qt with the Visual Studio 2017 x64 to x86 cross-compile
    toolchain. This toolchain can be set up on the command line by running
    \c{vcvarsall.bat amd64_x86}.

    \section2 Linux

    On Linux, Clang or GCC version 5 or later is required.
    Supported configurations are \c linux-g++, \c{linux-clang} and \c{linux-clang-libc++}

    \QWE requires \c pkg-config to detect most of its dependencies. The
    following \c pkg-config files are required:

    \list
        \li \c dbus-1
        \li \c fontconfig
    \endlist

    If Qt was configured for \c xcb, the following \c pkg-config files are also
    required:

    \list
        \li \c libdrm
        \li \c xcomposite
        \li \c xcursor
        \li \c xi
        \li \c xrandr
        \li \c xscrnsaver
        \li \c xtst
    \endlist

    Further, development packages for \c khr and \c libcap need to be installed.

    \section2 \macos

    On \macos, the following are required:

    \list
        \li \macos 10.13 or later
        \li Xcode 10.0 or later
        \li \macos 10.13 SDK or later
    \endlist

    \note \QWE cannot be built for the 32-bit mode of \macos (using the
    \c macx-clang-32 \c mkspec).

    \section1 Using Earlier Qt Versions to Build \QWE

    Building \QWE with earlier Qt versions (down to the last LTS
    version) is supported. It means that \QWE 5.15 can be built with
    Qt 5.12.x, Qt 5.14.x, and Qt 5.15.

    To use an earlier Qt version to build Qt Webengine:

    \list 1
        \li Download the qtwebengine sources.
        \li From the earlier Qt version, run
            \c {qmake && make (&& make install)}.
    \endlist

    \section1 Mac App Store Compatibility

    Applications using \QWE are not compatible with the Mac App Store, because:

    \list
        \li The Chromium part of the code uses several private API methods, which are prohibited by
            the App Store.
        \li Applications submitted to the App Store must be code-signed with the App Sandbox feature
            enabled. The App Sandbox feature interferes with Chromium's own sandbox
            initialization, which results in Chromium not being properly initialized. This also
            ties in with the private API usage. Furthermore, standalone Chromium itself is not
            officially tested with the App Sandbox enabled, and even if work is done to bypass
            the App Store's restrictions, that would not guarantee correct behavior of the library.

    \endlist

    \section1 macOS Airplay Support on MacBooks with Dual GPUs

    To make \QWE work correctly when streaming to an AppleTV from a MacBook that supports
    GPU switching, it is important to add the \c NSSupportsAutomaticGraphicsSwitching option to the
    application Info.plist file, with the value set to \c YES. Otherwise rendering issues might
    occur when creating new web engine view instances after Airplay is switched on or off.

    \section1 Default QSurfaceFormat OpenGL Profile Support

    If a new default QSurfaceFormat with a modified OpenGL profile has to be set, it should be set
    before the application instance is declared, to make sure that all created OpenGL contexts use
    the same OpenGL profile.

    On \macos, if the default QSurfaceFormat is set after the application instance, the application
    will exit with qFatal(), and print a message that the default QSurfaceFormat should be set
    before the application instance.

    \section1 Sandboxing Support

    \QWE provides out-of-the-box sandboxing support for Chromium render
    processes.

    On Linux, note the following restrictions:

    \list
        \li The kernel has to support the anonymous namespaces feature
            (kernel version 3.8 or later). However, on Debian, Ubuntu,
            and other Debian-derived distributions, this feature is off
            by default. It can be turned on by setting
            \c /proc/sys/kernel/unprivileged_userns_clone to 1.
        \li The kernel has to support the \c seccomp-bpf feature (kernel
            version 3.5 or later).
        \li Setuid sandboxes are not supported and are thus disabled.
    \endlist

    To explicitly disable sandboxing, use one of the following options:

    \list
        \li Set the \c QTWEBENGINE_DISABLE_SANDBOX environment variable to 1.
        \li Pass the \c{--no-sandbox} command line argument to the user
            application executable.
        \li Set \c QTWEBENGINE_CHROMIUM_FLAGS to \c{--no-sandbox}.
    \endlist

    For more information, see \l{Using Command-Line Arguments}.

    \section1 Memory Requirements in Docker Environment

    When running Qt Web Engine examples in a Docker container and browsing
    content-heavy sites, BUS errors (SIGBUS) might be reported. Typically,
    this is caused by Docker running a container with a too small memory space
    (such as 64MB). To fix this problem, increase the memory space size.

    \section1 Accessibility and Performance

    \QWE enables accessibility support for web pages when the following conditions
    are met:

    \list
        \li Qt Core is configured and built with accessibility support enabled.
        \li The QPA plugin is notified by the operating system that accessibility should be
            activated. This happens for example when using a screen reader application on Windows
            or VoiceOver on \macos.
    \endlist

    Due to some limitations, the Linux QPA plugin almost always reports that accessibility should
    be activated. On big HTML pages, this can cause a significant slowdown in rendering speed.

    Because of that, from Qt 5.9 onwards, \QWE accessibility support is disabled by default
    on Linux.
    It can be re-enabled by setting the \c QTWEBENGINE_ENABLE_LINUX_ACCESSIBILITY environment
    variable to a non-empty value.

    \section1 Popups in Fullscreen Applications on Windows
    Because of a limitation in the Windows compositor, applications that show a fullscreen web
    engine view will not properly display popups or other top-level windows. The reason and
    workaround for the issue can be found at \l {Fullscreen OpenGL Based Windows} and
    \l {QWindowsWindowFunctions::setHasBorderInFullScreen}.

*/
