QtWayland: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
(Remove ancient instructions. And replace with somewhat updated ones.)
 
(8 intermediate revisions by the same user not shown)
Line 10: Line 10:


== How can I get binaries for Qt Wayland? ==
== How can I get binaries for Qt Wayland? ==
The Qt installer does unfortunately not include binaries for Qt Wayland. You can however build it from source yourself if you want to use the latest stable version (see below).
Starting with Qt 5.11. the Qt installer should include binaries for Qt Wayland.


If you are using Qt provided by your Linux distribution there is most likely a separate package for Qt Wayland, i.e. qt5-wayland (Arch Linux), or two separate packages, i.e. qtwaylandclient5 and qtwaylandcompositor5-dev (Ubuntu 17.10). Beware that distros may ship really old versions of Qt though, and the compositor API was first released as stable with Qt 5.8.
If you are using Qt provided by your Linux distribution there is most likely a separate package for Qt Wayland, i.e. qt5-wayland (Arch Linux), or two separate packages, i.e. qtwaylandclient5 and qtwaylandcompositor5-dev (Ubuntu 17.10). Beware that distros may ship really old versions of Qt though, and the compositor API was first released as stable with Qt 5.8.
You can however also build it from source yourself in case you want to use the development version or apply custom patches. See section below.


== Where can I find the code for QtWayland? ==
== Where can I find the code for QtWayland? ==
Line 22: Line 24:
==== Ubuntu 14.04 ====
==== Ubuntu 14.04 ====


Ubuntu 14.04 contains all necessary dependencies, so it is no longer necessary to build Wayland yourself. The old instructions are available below.
Ubuntu 14.04 contains all necessary dependencies, so it is no longer necessary to build Wayland yourself.


The following packages are required (list may be incomplete)
The following packages are required (list may be incomplete)
Line 30: Line 32:
* libgles2-mesa-dev
* libgles2-mesa-dev
* libxkbcommon-dev
* libxkbcommon-dev
qtbase needs to be configured with OpenGL ES2
<code>configure -developer-build -opengl es2 [...]</code>
The compositor API is still experimental, and not built by default. To enable it, add <tt>wayland-compositor</tt> to the configuration:
<code>
cd qtwayland
qmake CONFIG+=wayland-compositor
</code>
==== Setup build environment Ubuntu 12.04 ====
The first step is to start with a reasonably modern Linux distribution. I use Ubuntu 12.04, so anything newer is just gravy.
The following instructions are based off of the tips on: http://wayland.freedesktop.org/building.html
The first thing I do is start by creating an install directory for my Wayland dependencies and create an environment file to source:
So if I wanted to install my Wayland dependencies into the folder $HOME/Apps/Wayland I would create the folder, and then create the file: <br>
''~/Apps/Wayland/wayland.sourceme_''
<code>#wayland.sourceme
WLD=$HOME/Apps/Wayland # change this to another location if you prefer
LD_LIBRARY_PATH=$WLD/lib
PKG_CONFIG_PATH=$WLD/lib/pkgconfig/:$WLD/share/pkgconfig/
ACLOCAL="aclocal -I $WLD/share/aclocal"
PATH=$WLD/bin:$PATH
XDG_RUNTIME_DIR=/tmp
export WLD LD_LIBRARY_PATH PKG_CONFIG_PATH ACLOCAL PATH XDG_RUNTIME_DIR</code>
So then source that file to set up your work environment: <br>
''source~/Apps/Wayland/wayland.sourceme''


==== Qt dependency ====
==== Qt dependency ====


Currently, you need to build the latest Qt (stable branch) (see http://lists.qt-project.org/pipermail/development/2013-December/014789.html ) WITHOUT using the wayland.sourceme environment. The modules you need at the very least are: <br>
You need Qt5.8 or newer for the compositor API. The modules you need at the very least are: <br>
qtbase <br>
qtbase <br>
qtdeclarative
qtdeclarative
If you face linker errors related to libGL and undefined references, it may be necessary to compile Qt5 and link it with the self compiled mesa. Maybe due to the way that mesa was compiled and installed, the configure script will require to explicitly define the version of OpenGL to be used with: ./configure -opengl es2


==== Building the QtWayland module ====
==== Building the QtWayland module ====


Once you have a working build of Qt 5, then pull down the latest QtWayland module code and configure with "qmake" this time using the wayland.sourceme environment. Make sure that you use the version of qmake that you get with Qt 5 here. This will make sure that the Wayland platform plugin and QtCompositor API are build using your special versions of OpenGL and Wayland.
Once you have a working build of Qt 5, then pull down the latest QtWayland module code and configure with "qmake". Make sure that you use the version of qmake that you get with Qt 5 here.


<code>source ~/Apps/Wayland/wayland.sourceme
<code>git clone git://code.qt.io/qt/qtwayland.git
git clone git://code.qt.io/qt/qtwayland.git
cd qtwayland
cd qtwayland
git checkout v5.10.0 # replace with your qt version
qmake
qmake
make
make
Line 95: Line 63:
==== Running example compositors ====
==== Running example compositors ====


The QtWayland module provides a couple of example compositors that demonstrate how the QtCompositor API works. These are built in the examples folder of the QtWayland module if you add "wayland-compositor" to the CONFIG variable when starting qmake, as in :
The QtWayland module provides a couple of example compositors that demonstrate how the Qt Wayland Compositor API works. These are built in the examples folder of the QtWayland module. You may need to explicitly build them (depending on how you configured Qt):
<code>qmake CONFIG+=wayland-compositor</code>
<code>cd qtwayland
make sub-examples</code>


These examples represent the server side of Wayland, so they do not use the wayland platform plugin, but rather whatever platform you need to run on. Generally this is going to be either ''eglfs'', ''kms'', or if you want to run in X11 ''xcb''.
These examples represent the server side of Wayland, so they do not use the wayland platform plugin, but rather whatever platform you need to run on. Generally this is going to be either ''eglfs'', ''kms'', or if you want to run in X11 ''xcb''. You can also run a nested compositor if you run the compositor on the ''wayland'' platform plugin.


If you wanted to run the qml-compositor in X11 you would run the following:
If you wanted to run the pure-qml compositor in X11 you would run the following:


<code>source ~/Apps/Wayland/wayland.sourceme
<code>cd qtwayland/examples/wayland/pure-qml
cd qtwayland/examples/qml-compositor
./pure-qml -platform xcb</code>
./qml-compositor -platform xcb</code>


And now that you have a Wayland compositor running, you can connect and display Wayland clients.
And now that you have a Wayland compositor running, you can connect and display Wayland clients.
Line 112: Line 80:
Compositors can be implemented using QML, or you can use the C++ API if you need more low-level control.
Compositors can be implemented using QML, or you can use the C++ API if you need more low-level control.


* QML-based: See minimal-qml and pure-qml.
* QML-based: See minimal-qml and pure-qml. [https://www.youtube.com/watch?v=9vWMUTvFgdU Tutorial], [https://www.youtube.com/watch?v=mIg1P3i2ZfI talk]
* C++-based: See the minimal-cpp and qwindow-compositor examples.
* C++-based: See the minimal-cpp and qwindow-compositor examples.


The project file will need to use the compositor module (i.e. add in the .pro file '''QT += waylandcompositor'''). It is interesting to comment that at time of writing, there are some QML related APIs only available by adding a define in the project file (i.e. '''DEFINES += QT_COMPOSITOR_QUICK''').
The project file will need to use the compositor module (i.e. add in the .pro file '''QT += waylandcompositor''').
 
== Troubleshooting ==
 
=== libGL linker issues ===
If you face linker errors related to libGL and undefined references, it may be necessary to compile Qt5 and link it with the self compiled mesa. Maybe due to the way that mesa was compiled and installed, the configure script will require to explicitly define the version of OpenGL to be used with: ./configure -opengl es2

Latest revision as of 13:14, 28 March 2019

En Ar Bg De El Es Fa Fi Fr Hi Hu It Ja Kn Ko Ms Nl Pl Pt Ru Sq Th Tr Uk Zh

What is QtWayland?

QtWayland is a Qt 5 module that wraps the functionality of Wayland. QtWayland is separated into a client and server side. The client side is the wayland platform plugin, and provides a way to run Qt applications as Wayland clients. The server side is the Qt Wayland Compositor API, and allows users to write their own Wayland compositors.

What is Wayland

Wayland is a protocol for a compositor to talk to its clients as well as a C library implementation of that protocol. For more detailed information you should visit the Wayland project homepage

How can I get binaries for Qt Wayland?

Starting with Qt 5.11. the Qt installer should include binaries for Qt Wayland.

If you are using Qt provided by your Linux distribution there is most likely a separate package for Qt Wayland, i.e. qt5-wayland (Arch Linux), or two separate packages, i.e. qtwaylandclient5 and qtwaylandcompositor5-dev (Ubuntu 17.10). Beware that distros may ship really old versions of Qt though, and the compositor API was first released as stable with Qt 5.8.

You can however also build it from source yourself in case you want to use the development version or apply custom patches. See section below.

Where can I find the code for QtWayland?

Qt Wayland Repo

How do I build QtWayland?

Ubuntu 14.04

Ubuntu 14.04 contains all necessary dependencies, so it is no longer necessary to build Wayland yourself.

The following packages are required (list may be incomplete)

  • libwayland-dev
  • libwayland-egl1-mesa
  • libwayland-server0
  • libgles2-mesa-dev
  • libxkbcommon-dev

Qt dependency

You need Qt5.8 or newer for the compositor API. The modules you need at the very least are:
qtbase
qtdeclarative

Building the QtWayland module

Once you have a working build of Qt 5, then pull down the latest QtWayland module code and configure with "qmake". Make sure that you use the version of qmake that you get with Qt 5 here.

git clone git://code.qt.io/qt/qtwayland.git
cd qtwayland
git checkout v5.10.0 # replace with your qt version
qmake
make
make install

How do I use QtWayland?

Run Qt applications as Wayland clients

When you build the QtWayland module, you should get a new platform plugin for wayland. To use it you must first already have a Wayland compositor running. This could be either the Weston reference compositor provided by the Wayland project, or a Qt example compositor provided by QtWayland. Regardless the only thing you need to do as an application developer to run your GUI application as a wayland client is tell the application to use the right platform plugin:

./application -platform wayland

or:

export QT_QPA_PLATFORM=wayland
./application

Create and Run your own Wayland Compositor with Qt5

Running example compositors

The QtWayland module provides a couple of example compositors that demonstrate how the Qt Wayland Compositor API works. These are built in the examples folder of the QtWayland module. You may need to explicitly build them (depending on how you configured Qt):

cd qtwayland
make sub-examples

These examples represent the server side of Wayland, so they do not use the wayland platform plugin, but rather whatever platform you need to run on. Generally this is going to be either eglfs, kms, or if you want to run in X11 xcb. You can also run a nested compositor if you run the compositor on the wayland platform plugin.

If you wanted to run the pure-qml compositor in X11 you would run the following:

cd qtwayland/examples/wayland/pure-qml
./pure-qml -platform xcb

And now that you have a Wayland compositor running, you can connect and display Wayland clients.

Creating your own compositor

Compositors can be implemented using QML, or you can use the C++ API if you need more low-level control.

  • QML-based: See minimal-qml and pure-qml. Tutorial, talk
  • C++-based: See the minimal-cpp and qwindow-compositor examples.

The project file will need to use the compositor module (i.e. add in the .pro file QT += waylandcompositor).

Troubleshooting

libGL linker issues

If you face linker errors related to libGL and undefined references, it may be necessary to compile Qt5 and link it with the self compiled mesa. Maybe due to the way that mesa was compiled and installed, the configure script will require to explicitly define the version of OpenGL to be used with: ./configure -opengl es2