qt_generate_wayland_protocol_client_sources.qdoc

Go to the documentation of this file.

// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
\page qt-generate-wayland-protocol-client-sources.html
\ingroup cmake-commands-qtwaylandclient
 
\title qt_generate_wayland_protocol_client_sources
\keyword qt6_generate_wayland_protocol_client_sources
 
\summary {Generates client-side C++ bindings for a Wayland protocol .XML file}
 
The command is defined in the \c WaylandClient component of the \c Qt6 package, which
can be loaded like so:
 
\badcode
find_package(Qt6 REQUIRED COMPONENTS WaylandClient)
\endcode
 
\cmakecommandsince 6.0
 
\section1 Synopsis
 
\badcode
qt_generate_wayland_protocol_client_sources(target
                                            [PUBLIC_CODE | PRIVATE_CODE]
                                            [NO_INCLUDE_CORE_ONLY]
                                            FILES file1.xml [file2.xml ...])
\endcode
 
\versionlessCMakeCommandsNote qt6_generate_wayland_protocol_client_sources()
 
\section1 Description
 
qt_generate_wayland_protocol_client_sources() creates the build steps to run \c{wayland-scanner} and
\c{qtwaylandscanner} on one or more Wayland protocol files. The tools will in turn generate binding
code in C and C++ for implementing the protocols, and the resulting files will be built as part
of the \c target.
 
The options \c{PUBLIC_CODE} and \c{PRIVATE_CODE} (added in Qt 6.8) correspond to the \c{public-code}
and \c{private-code} options of \c{wayland-scanner}. \c{PUBLIC_CODE} will cause the symbols in the
code that is generated by \c{wayland-scanner} to be exported.
 
Before Qt 6.12, the default was \c PUBLIC_CODE. For Qt 6.12 and newer, the
default is \c PRIVATE_CODE if the Qt policy \l qt_cmake_policy_qtp0006 is set to
\c NEW. Generally, \c{PRIVATE_CODE} is strongly recommended.
 
By default, \c{wayland-scanner} is invoked with the \c{--include-core-only} argument, ensuring
that generated code includes \c{"wayland-client-core.h"}. This behavior can be disabled using
the \c{NO_INCLUDE_CORE_ONLY} option, which switches the include to \c{"wayland-client.h"}.
 
\note Using \c{NO_INCLUDE_CORE_ONLY} is generally discouraged. \c{"wayland-client.h"}
includes a pre-compiled version of the core Wayland protocol which may conflict with
newer protocol versions or other headers (like older versions of Vulkan). Only use
this option if you have a specific requirement for types not present in the core header
and are aware of the potential build-time conflicts.
 
qt_generate_wayland_protocol_client_sources() will trigger generation of the files needed to
implement the client side of the protocol. \l{qt_generate_wayland_protocol_server_sources}{qt_generate_wayland_protocol_server_sources()}
is the equivalent function for the compositor.
 
See the \l{Custom Shell} or \l{Custom Extension} examples for a demonstration of how to use these
functions.
*/