summaryrefslogtreecommitdiffstats
path: root/src/webengine/doc/src/qtwebengine-platform-notes.qdoc
blob: 57e3ce6a8531bf7dd8eb21f40b56e798fd6ac411 (plain)
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
/****************************************************************************
**
** Copyright (C) 2016 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 Qt WebEngine module.

    \section1 Building Qt WebEngine 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 - Requirements}
    \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 Qt WebEngine 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:

    \list
        \li \l Python 2.7.5 or later. Python 3 is not supported.
        \li Bison, Flex
        \li GPerf
    \endlist

    \section2 Windows

    On Windows, Visual Studio 2015 and Windows 10 SDK are required.

    \section2 Linux

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

    Qt WebEngine 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.9 or later
        \li Xcode 5.1 or later
        \li \macos 10.10 SDK or later
    \endlist

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

    \section1 Mac App Store Compatibility

    By default, Qt WebEngine uses private \macos API, which might cause an application to be
    rejected when submitted to the Mac App Store. To configure Qt WebEngine not to use these API
    calls, Qt has to be reconfigured with the \c -appstore-compliant switch.

    However, this will cause some behavioral changes, such as:

    \list
        \li The \macos Kill Ring functionality will no longer work (emacs-like copy pasting).
        \li Certain Chromium sandboxing cleanup is not done.
        \li Text areas will be painted with a different style.
        \li Text fields might be painted with a different style on Mountain Lion (\macos 10.8).
    \endlist

    \section1 macOS Airplay Support on MacBooks with Dual GPUs

    To make Qt WebEngine 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

    Qt WebEngine provides out-of-the-box sandboxing support for Chromium render processes on Linux
    and \macos. Sandboxing is currently not supported on Windows due to a limitation in how
    the sandbox is set up and how it interacts with the host process provided by the Qt WebEngine
    libraries.

    On \macos, there are no special requirements for enabling sandbox support.

    On Linux, the kernel has to support the anonymous namespaces feature (kernel version >= 3.8)
    and seccomp-bpf feature (kernel version >= 3.5). Setuid sandboxes are not supported and are thus
    disabled.

    To explicitly disable sandboxing, the \c QTWEBENGINE_DISABLE_SANDBOX environment variable can be
    set to 1 or alternatively the \c{--no-sandbox} command line argument can be passed to the user
    application executable.

    \section1 Accessibility and Performance

    Qt WebEngine 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, Qt WebEngine 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.

*/