I think the docbook deserves an introduction to how color management is
designed in Wayland, aimed at people who are familiar with pixels but
new to the topic.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
This change mentions the case where WAYLAND_SOCKET is used, which helps
people avoid just testing 'getenv(WAYLAND_DISPLAY)' to see if a
Wayland compositor is available;
Signed-off-by: Manuel Stoeckl <code@mstoeckl.com>
libwayland cannot construct these messages as it uses strlen() to
determine string lengths. libwayland is also guaranteed to misinterpret
these messages, since message handlers only get a pointer and no length.
Therefore, reject strings containing NUL bytes.
Also remove a redundant check from the unmarshalling code. The
zero-length case has already been checked for.
Signed-off-by: Demi Marie Obenour <demi@invisiblethingslab.com>
"is incompatible with the implementation in libwayland" is a common
source of confusion as evidenced by repeated discussions in IRC
channel.
Improve the wording by making clear that
- packing IDs is a protocol requirement
- there are implementations (including libwayland) that enforce it
Signed-off-by: Mikhail Gusarov <dottedmag@dottedmag.net>
The specification left the position and order of file
descriptors unspecified. Specify that
- order of file descriptors is maintained
- position of file descriptors is bounded, but loose
Signed-off-by: Mikhail Gusarov <dottedmag@dottedmag.net>
This is the style used in wayland.xml which is the only file we really
care about for git blame information. So let's adjust all others to that
style for consistency and fix editorconfig to avoid messing this up in
the future.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Meson is a next generation build system, simpler than Autotools and also faster
and more portable. Most importantly, it will make integrating ASan easier in
CI.
The goal is to maintain feature parity of the Meson build with the
Autotools build, until such time when we can drop the latter.
Add a script which generates the desired Doxygen configuration for our various
output formats and executes it using that configuration. This is not something
Meson can or should do.
Fixes: https://gitlab.freedesktop.org/wayland/wayland/issues/80
[daniels: Changed to bump version, use GitLab issues URL, remove header
checks not used in any code, remove pre-pkg-config Expat
support, added missing include paths to wayland-egl and
cpp-compile-test, added GitLab CI.
Bumped version, removed unnecessary pkg-config paths.]
[daniels: Properly install into mandir/man3 via some gross
paramaterisation, generate real stamp files.]
Pekka:
- squashed patches
- removed MAKEFLAGS from meson CI
- remove unused PACKAGE* defines
- fix up scanner dependency handling
- instead of host_scanner option, build wayland-scanner twice when cross-compiling
- changed .pc files to match more closely the autotools versions
- reorder doxygen man sources to reduce diff to autotools
- fix pkgconfig.generate syntax warnings (new in Meson)
- bump meson version to 0.47 for configure_file(copy) and run_command(check)
- move doc tool checks into doc/meson.build, needed in more places
- make all doc tools mandatory if building docs
- check dot and doxygen versions
- add build files under doc/publican
- reindent to match Weston Meson style
Simon:
- Remove install arg from configure_file
- Don't build wayland-scanner twice during cross-build
- Fix naming of the threads dependency
- Store tests in dict
- Add missing HAVE_* decls for functions
- Remove unused cc_native variable
- Make doxygen targets a dict
- Make dot_gv a dict
- Use dicts in man_pages
- Make decls use dicts
- Make generated_headers use dicts
- Align Meson version number with autotool's
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Signed-off-by: Simon Ser <contact@emersion.fr>
Out of the context it is reasonably clear that "hw" is indeed an abbreviation
for "hardware".
The use of "hw" in this place doesn't seem to be a stylistic choice, but rather
an oversight.
Signed-off-by: Paul Scharnofske <asynts@gmail.com>
When wayland-scanner encounters a new_id field with no corresponding
interface name defined, instead of emitting a function whose signature
lines up with the usual case (a uint32_t ID), it adds the interface name
as a string and the version number so that the interface can be
identified from the protcol message.
Without docs, this was previously left for the interprid wire protocol
implementor (e.g. me an hour ago) to discover when Wayland clients send
them apparently bogus messages.
I would have preferred if a different primitive type were used here
(e.g. typed_new_id) to reflect the fact that the wire protocol is
different, but I felt it unwise to add a new primitive to wayland.xml in
$current_year.
Use a more official one, served over HTTP rather than FTP.
Reviewed-by: Matheus Santana <embs@cin.ufpe.br>
Acked-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
This is a rough intro to what Xwayland is and does, with just one
implementation detail so far (Window identification).
I paid no attention to formatting details, those can be polished in
follow-ups. I just want the prose out.
I also just quickly whacked up the diagram, would be happy to see
someone replace it with a nicer one. I just didn't have time to learn
dot for now.
v2:
- typo fix
- rephrase "talking to hardware" as "driving the displays"
- mention circular dependency in intro
- add section to explain rootless and rootful modes
- remove paragraph about Xwayland protocol usage
- move TBD part to the end under a new section header
v3:
- use "advantage" and "disadvantage" instead of "pro" and "con"
- slight rewording on rootful mode and rootless mode paragraphs
- removed the paragraph about the lack of shell and special Wayland
protocol extensions
- removed the commented out list of ideas to write
v4:
- typo fixes pointed out by Yong
Cc: Olivier Fourdan <ofourdan@redhat.com>
Cc: Jonas Ådahl <jadahl@gmail.com>
Cc: Daniel Stone <daniel@fooishbar.org>
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Reviewed-by: Jonas Ådahl <jadahl@gmail.com>
In order to support system compositor instances, it is necessary to
allow clients' wl_display_connect() to find the compositor's listening
socket somewhere outside of XDG_RUNTIME_DIR. For a full account, see
the discussion beginning here:
https://lists.freedesktop.org/archives/wayland-devel/2017-November/035664.html
This change adjusts the client-side connection logic so that, if
WAYLAND_DISPLAY is formatted as an absolute pathname, the socket
connection attempt is made to just $WAYLAND_DISPLAY rather than
usual user-private location $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY.
This change is based on Davide Bettio's submission of the same concept
at:
https://lists.freedesktop.org/archives/wayland-devel/2015-August/023838.html.
v4 changes:
* Improved internal comments and some boundary-condition
error checks in test case.
* Refer to compositor as "Wayland server" rather than "Wayland
display" in wl_display_connect() doxygen comments.
* Remove redundant descriptions of parameter-interpretation
mechanics from wl_display_connect() manpage. Reworked things
to make it clear that 'name' and $WAYLAND_DISLAY are each
capable of encoding absolute server socket paths.
* Remove callout to reference implementation behavior in protocol
documented. In its place there is now a simple statement that
implementations can optionally support absolute socket paths.
v3 changes:
* Added test case.
* Clarified documentation to note that 'name' parameter to wl_display_connect()
can also be an absolute path.
v2 changes:
* Added backward incompatibility note to wl_display_connect() manpage.
* Rephased wl_display_connect() manpage changes to precisely match actual
changed behavior.
* Added mention of new absolute path behavior in wl_display_connect()
doxygen comments.
* Mentioned new absolute path interpretation of WAYLAND_DISPLAY in
protocol documentation.
Signed-off-by: Matt Hoosier <matt.hoosier@gmail.com>
Acked-by: Jonas Ådahl <jadahl@gmail.com>
Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
The docbook title was "The Wayland display server," which is inaccurate.
Change the title to "The Wayland Protocol".
Signed-off-by: Yong Bakos <ybakos@humanoriented.com>
Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Introduce the enum and bitfield attributes, which allow you to refer to the enum
you are expecting in an argument, and specify which enums are to be thought of
as bitfields.
Changes since v3:
- Fix typo ("description" -> "descriptive")
Signed-off-by: Auke Booij <auke@tulcod.com>
Reviewed-by: Nils Chr. Brause <nilschrbrause@googlemail.com>
Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
This reverts commit fb7e130217.
Developers have been trying to reduce the number of by default required
environment variables, and the mentioned commit is a step backwards in
that sense. The fundamental assumption is that a user has only one main
(Wayland) display server where all programs should connect to by
default, and do so with an a priori known socket name.
The commit also broke various use cases in the wild, some accidentally
due to other causes, some intentionally. This revert allows those use
cases to continue.
The original problem of running Weston in a window in an existing GNOME
X11 session and getting applications unintentionally launched into
Weston can be circumvented by letting Weston use a non-default socket
name, leaving wayland-0 unused.
Discussion:
http://lists.freedesktop.org/archives/wayland-devel/2015-August/023927.htmlhttp://lists.freedesktop.org/archives/wayland-devel/2015-August/023937.html
Cc: Dima Ryazanov <dima@gmail.com>
Cc: Giulio Camuffo <giuliocamuffo@gmail.com>
Cc: Daniel Stone <daniel@fooishbar.org>
Cc: Jasper St. Pierre <jstpierre@mecheye.net>
Cc: Ryo Munakata <ryomnktml@gmail.com>
Cc: Ray Strode <halfline@gmail.com>
Cc: Peter Hutterer <peter.hutterer@who-t.net>
Cc: Matthias Clasen <mclasen@redhat.com>
Cc: Sjoerd Simons <sjoerd.simons@collabora.co.uk>
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Acked-by: Ray Strode <rstrode@redhat.com>
Acked-by: Dima Ryazanov <dima@gmail.com>
Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
Acked-By: Sjoerd Simons <sjoerd.simons@collabora.co.uk>
Acked-By: Ryo Munakata <ryomnktml@gmail.com>
Acked-by: Peter Hutterer <peter.hutterer@who-t.net>
Although defaulting to wayland-0 seems convenient, it has an undesirable
side effect: clients may unintentionally connect to the wrong compositor.
Generally, it's safer to fail instead. Here's a real example:
In Fedora 22, Gtk+ prefers Wayland over X11, though the default session is still
a normal X11 Gnome session. When you launch a Gtk+ app, it will try Wayland,
fail, then try X11, and succesfully start up. That works fine.
Now suppose you launch Weston while running the Gnome session. Suddenly, all
of the Gtk+ apps launched from Gnome will show up inside Weston instead.
That's unexpected. There's also no good way to prevent that from happening
(other than perhaps setting WAYLAND_DISPLAY to an invalid value when launching
an app).
Not using wayland-0 as the default will solve that problem: an app launched
from the X11 Gnome session will use the X11 backend regardless of whether
there's a wayland compositor running at the same time.
Everything else should work as before. The compositor already sets
the WAYLAND_DISPLAY when starting the session, so the lack of the default value
should not make a difference to the user.
Signed-off-by: Dima Ryazanov <dima@gmail.com>
Acked-by: Pekka Paalanen <ppaalanen@gmail.com>
Acked-by: Giulio Camuffo <giuliocamuffo@gmail.com>
Acked-by: Daniel Stone <daniel@fooishbar.org>
Acked-by: Jasper St. Pierre <jstpierre@mecheye.net>
Reviewed-by: Ryo Munakata <ryomnktml@gmail.com>
[Pekka: dropped the wayland-server.c hunk, adjusted summary]
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
(This patch has been modified to apply atop current master)
This makes it considerably easier to edit the text and make it different
for each library.
To address previous concerns with this patch, I wrote some more complete
introductory text. This is based on my understanding of these libraries, which
may not be correct, and is pretty rudimentary for libwayland-server!
However this intro text demonstrates how to create links to the
doxygen-generated text. It looks like you cannot link to methods easily as the
link name contains a hash number, but links to objects and classes work.
Reviewed-by: Jon A. Cruz <jonc@osg.samsung.com>
Tested-by: Jon A. Cruz <jonc@osg.samsung.com>
Added xslt processing to give DocBook output diagram image maps/hot-linked
areas consistent with those automatically generated by Doxygen.
Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com>
Switches diagrams from using static PNG images to instead generate them via
simple graphviz DOT markup files.
Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com>
Just to make it slightly shorter.
Also add a dash to the doxygen links to make them look a bit more alike.
Tested-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
The repetitive parts of generating the server and client documentation are
merged, so it is easier to add another doxygen chapter: add a new line to
$publican_sources in publican/Makefile.am, and a list of C source files to
doxygen/Makefile.am.
Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
This was suggested before to make it clearer that things like wl_display
are different objects in each of them. I made these into two appendixes
because the protocol spec was already an appendix.
Reviewed-by: Bryce Harrington <b.harrington@samsung.com>
[Bryce requested minor changes, not yet here.]
Acked-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Publican isn't packaged for some distros, xmlto is a lot more common. Most of
what publican provides for us is the stylesheet anyway, so we can just use
xmlto and the publican stylesheet to get roughly the same look.
PDF and XML generation has been dropped, this needs a bit more more effort
than a mere switchover to xmlto.
The top-level directory structure imposed by publican is kept for now
(specifically the Wayland/en-US/html tree). This makes it easier to transition over
for packagers. Note that the list of files inside has changed.
CSS files are taken from publican to keep a uniform look compared to previous
documentations. Stylesheets are licensed under CC0 1.0 Universal license, see
publican/LICENSE:
1. Files in the datadir/Common_Content directory and its subdirectories are
licensed under the CC0 1.0 Universal license.
To the extent possible under law, the developers of Publican waive all
copyright and related or neighboring rights to the files contained
in the datadir/Common_Content directory and its subdirectories.
Acked-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
There have been a lot of questions asked lately about versioning of
interfaces and protocol objects. This addition to the documentation should
clear up some of those questions.
Signed-off-by: Jason Ekstrand <jason@jlekstrand.net>
The method described of alocation IDs has been wrong at least since version
1.0. This commit updates it to correspond to the way IDs are chosen in
versions >= 1.0.
Signed-off-by: Jason Ekstrand <jason@jlekstrand.net>
Originally written Tiago Vignatti <tiago.vignatti@intel.com>
Some modifications to adjust for previously merged conflicting patches and link
to the sections (instead of <emphasis>).
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Same as WaylandClientAPI.xml we now also generate WaylandServerAPI.xml for
publication. Most of this hunk is just adding a client/ or server/ into the
xml path to keep the two separate.
The change in wayland.doxygen now causes a standard doxygen call to not
generate anything - what is generated is specified through the options
passed by make.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Signed-off-by: Tiago Vignatti <tiago.vignatti@intel.com>
Reviewed-by: Peter Hutterer <peter.hutterer@who-t.net>
[re-run of search/replace after rebasing]
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
This directory was called Wayland during my early tries with publican where
the source layout was different and it needed to be set to the same name as
the publican output directory. This reason doesn't exist anymore, so re-name
it to publican to make it more obvious what's hiding in here.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
