142 lines
6.2 KiB
Plaintext
142 lines
6.2 KiB
Plaintext
Wayland protocols
|
|
-----------------
|
|
|
|
wayland-protocols contains Wayland protocols that add functionality not
|
|
available in the Wayland core protocol. Such protocols either add
|
|
completely new functionality, or extend the functionality of some other
|
|
protocol either in Wayland core, or some other protocol in
|
|
wayland-protocols.
|
|
|
|
A protocol in wayland-protocols consists of a directory containing a set
|
|
of XML files containing the protocol specification, and a README file
|
|
containing detailed state and a list of maintainers.
|
|
|
|
Protocol directory tree structure
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
Protocols may be 'stable', 'unstable' or 'deprecated', and the interface
|
|
and protocol names as well as place in the directory tree will reflect
|
|
this.
|
|
|
|
A stable protocol is a protocol which has been declared stable by
|
|
the maintainers. Changes to such protocols will always be backward
|
|
compatible.
|
|
|
|
An unstable protocol is a protocol currently under development and this
|
|
will be reflected in the protocol and interface names. See <<Unstable
|
|
naming convention>>.
|
|
|
|
A deprecated protocol is a protocol that has either been replaced by some
|
|
other protocol, or declared undesirable for some other reason. No more
|
|
changes will be made to a deprecated protocol.
|
|
|
|
Depending on which of the above states the protocol is in, the protocol
|
|
is placed within the toplevel directory containing the protocols with the
|
|
same state. Stable protocols are placed in the +stable/+ directory,
|
|
unstable protocols are placed in the +unstable/+ directory, and
|
|
deprecated protocols are placed in the +deprecated/+ directory.
|
|
|
|
Protocol development procedure
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
To propose a new protocol, create a patch adding the relevant files and
|
|
Makefile.am entry to the wayland-protocols git repository with the
|
|
explanation and motivation in the commit message. Then send the patch to
|
|
the wayland-devel@lists.freedesktop.org mailing list using
|
|
'git send-email' with the subject prefix 'RFC wayland-protocols' or
|
|
'PATCH wayland-protocols' depending on what state the protocol is in.
|
|
|
|
To propose changes to existing protocols, create a patch with the
|
|
changes and send it to the list mentioned above while also CC:ing the
|
|
maintainers mentioned in the README file. Use the same rule for adding a
|
|
subject prefix as above and method for sending the patch.
|
|
|
|
If the changes are backward incompatible changes to an unstable protocol,
|
|
see <<Unstable protocol changes>>.
|
|
|
|
Interface naming convention
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
All protocols should avoid using generic namespaces or no namespaces in
|
|
the protocol interface names in order to minimize risk that the generated
|
|
C API collides with other C API. Interface names that may collide with
|
|
interface names from other protocols should also be avoided.
|
|
|
|
For generic protocols not limited to certain configurations (such as
|
|
specific desktop environment or operating system) the +wp_+ prefix
|
|
should be used on all interfaces in the protocol.
|
|
|
|
For operating system specific protocols, the interfaces should be
|
|
prefixed with both +wp_+ and the operating system, for example
|
|
+wp_linux_+, or +wp_freebsd_+, etc.
|
|
|
|
Unstable naming convention
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
Unstable protocols have a special naming convention in order to make it
|
|
possible to make discoverable backward incompatible changes.
|
|
|
|
An unstable protocol has at least two versions: the major version, which
|
|
represents backward incompatible changes, and the minor version, which
|
|
represents backward compatible changes to the interfaces in the protocol.
|
|
|
|
The major version is part of the XML file name, the protocol name in the
|
|
XML, and interface names in the protocol.
|
|
|
|
Minor versions are the version attributes of the interfaces in the XML.
|
|
There may be more than one minor version per protocol, if there are more
|
|
than one global.
|
|
|
|
The XML file and protocol name also has the word 'unstable' in them, and
|
|
all of the interfaces in the protocol are prefixed with +z+ and
|
|
suffixed with the major version number.
|
|
|
|
For example, an unstable protocol called foo-bar with major version 2
|
|
containing the two interfaces wp_foo and wp_bar both minor version 1 will
|
|
be placed in the directory +unstable/foo-bar/+ consisting of one file
|
|
called +README+ and one called +foo-bar-unstable-v2.xml+. The XML file
|
|
will consist of two interfaces called +zwp_foo_v2+ and +zwp_bar_v2+ with
|
|
the +version+ attribute set to +1+.
|
|
|
|
Unstable protocol changes
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
During the development of a new protocol it is possible that backward
|
|
incompatible changes are needed. Such a change needs to be represented
|
|
in the major and minor versions of the protocol.
|
|
|
|
Assuming a backward incompatible change is needed, the procedure for how to
|
|
do so is the following:
|
|
|
|
. Make a copy of the XML file with the major version increased by +1+.
|
|
. Increase the major version number in the protocol XML by +1+.
|
|
. Increase the major version number in all of the interfaces in the
|
|
XML by +1+.
|
|
. Reset the minor version number (interface version attribute) of all
|
|
the interfaces to +1+.
|
|
|
|
Backward compatible changes within a major unstable version can be done
|
|
in the regular way as done in core Wayland or in stable protocols.
|
|
|
|
Declaring a protocol stable
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
Once it is decided that a protocol should be declared stable, meaning no
|
|
more backward incompatible changes will ever be allowed, one last
|
|
breakage is needed.
|
|
|
|
The procedure of doing this is the following:
|
|
|
|
. Create a new directory in the +stable/+ toplevel directory with the
|
|
same name as the protocol directory in the +unstable/+ directory.
|
|
. Copy the final version of the XML that is the version that was
|
|
decided to be declared stable into the new directory. The target name
|
|
should be the same name as the protocol directory but with the +.xml+
|
|
suffix.
|
|
. Rename the name of the protocol in the XML by removing the
|
|
'unstable' part and the major version number.
|
|
. Remove the +z+ prefix and the major version number suffix from all
|
|
of the interfaces in the protocol.
|
|
. Reset all of the interface version attributes to +1+.
|
|
. Update the +README+ file in the unstable directory and create a new
|
|
+README+ file in the new directory.
|
|
|
|
Releases
|
|
~~~~~~~~
|
|
Each release of wayland-protocols finalizes the version of the protocols
|
|
to their state they had at that time.
|