Without this, DocBook picks the output encoding and on some setups
we end up with ISO-8859-1. Tested by booting a fresh Alpine VM,
verifying that the generated HTML is using the incorrect charset,
applying the patch, and verifying that the generated HTML is fixed.
Signed-off-by: Simon Ser <contact@emersion.fr>
Fail when tests/documentation is enabled without libraries. Fail
when neither scanner nor libraries is enabled, because we don't
build anything in that case.
Signed-off-by: Simon Ser <contact@emersion.fr>
meson.build_root() returns the parent's build directory if Wayland is
a subproject. This fails with:
error: tag OUTPUT_DIRECTORY: Output directory '<parent-build-dir>/doc/doxygen' does not exist and cannot be created
Instead, use meson.project_build_root(), which returns the subproject's
build directory.
Signed-off-by: Simon Ser <contact@emersion.fr>
Fixes the following warning:
WARNING: You should add the boolean check kwarg to the run_command call.
It currently defaults to false,
but it will default to true in future releases of meson.
See also: https://github.com/mesonbuild/meson/issues/9300
Signed-off-by: Simon Ser <contact@emersion.fr>
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 setting makes Docbook section IDs consistent, and should allow
Wayland builds that include documentation to be fully reproducible.
Signed-off-by: Alyssa Ross <hi@alyssa.is>
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>
There is only one page written. Having manually-written man pages duplicates
information with doc comments. Besides, man pages are already generated by
Doxygen.
Signed-off-by: Simon Ser <contact@emersion.fr>
Closes: https://gitlab.freedesktop.org/wayland/wayland/-/issues/156
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>
Make considers a variable called VPATH when trying to satisfy
dependencies, e.g. for a target 'foo', it will consider the target
extant if VPATH is '../../bar' and '../../bar/foo' exists.
Part of the doc build, the '$(alldirs)' target, exists to create the
target directories if they do not exist. For example, before generating
xml/wayland-architecture.png, it will ensure the 'xml' target is
considered up-to-date thanks to the target dependency.
Creating $(srcdir)/doc/doxygen/xml thus means that the 'xml' dependency
will be satisfied, so we'll never create the output directory, and the
doc build will fail.
Change the alldirs target list to be absolute paths, so VPATH will not
be consulted and defeat the entire point of what we're trying to do.
This fixes the Meson build, where we later create
doc/doxygen/xml/meson.build.
Signed-off-by: Daniel Stone <daniels@collabora.com>
Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.com>
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.
The docbook-xsl package includes all the stylesheets required to build
the docs without internet access.
Test:
One way to emulate missing style sheets is to move /etc/xml/catalog file
to a different location. Doing so should cause configure to fail with
"checking for docbook stylesheets... no"
v2: add AC_MSG_RESULT (Pekka)
Signed-off-by: Harish Krupo <harishkrupo@gmail.com>
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>
Gitlab expects a CONTRIBUTING.md in the root directory, so move our
guide there.
Conversion to proper markup is a follow-up patch.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Reviewed-by: Peter Hutterer <peter.hutterer@who-t.net>
Reviewed-by: Daniel Stone <daniels@collabora.com>
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>
There is a lot of files created with .so links to non-installed
files, making most of installed pages useless. The files
referenced in .so links are not suitable for installation nor
do they contain any useful information for them to be worth
fixing.
Signed-off-by: Armin Krezović <krezovic.armin@gmail.com>
Acked-by: Daniel Stone <daniels@collabora.com>
This documents all the public API related to wl_event_loop and
wl_event_source objects.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Reviewed-by: Yong Bakos <ybakos@humanoriented.com>
[Pekka: fixed typos pointed by Yong]
[Pekka: fixed typos pointed by Christopher]
Reviewed-By: Christopher James Halse Rogers <christopher.halse.rogers@canonical.com>
With recent versions of graphviz, generation of the diagrams in the documentation
fails with:
/usr/bin/dot -Tpng -oxml/x-architecture.png dot/x-architecture.gv
Warning: flat edge between adjacent nodes one of which has a record shape - replace records with HTML-like labels
Edge xserver -> comp
Error: getsplinepoints: no spline points available for edge (xserver,comp)
Error: lost xserver comp edge
Error: lost xserver comp edge
Error: lost comp xserver edge
Error: lost comp xserver edge
http://www.graphviz.org/content/i-havent-been-able-render-these-files-graphviz-226 indicates
that the error message basically means that the authors of graphviz consider record-style
labels to be deprecated and are no longer fixing errors with them. This patch changes
the labels to be in the HTML style, which seems to require duplicating style between all
the nodes, but it's not like these files are often edited.
The result is not exactly the same but is quite similar.
Reviewed-by: Armin Krezović <krezovic.armin@gmail.com>
Tested-by: Armin Krezović <krezovic.armin@gmail.com>
All fd.o projects are now covered by the Contributor Covenant. Include a
reference to this in the Contributing doc, making it clear that we are
all expected to behave like human beings.
Signed-off-by: Daniel Stone <daniels@collabora.com>
Reviewed-by: Yong Bakos <ybakos@humanoriented.com>
Acked-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Acked-by: Jonas Ådahl <jadahl@gmail.com>
Documentation generation via doxygen includes wayland-util.c in its file
list. Although functions are documented in wayland-util.h, doxygen is
not automatically using the same documentation for functions in
wayland-util.c. In addition, everything listed in the doxygen page for
wayland-util.c is documented in the page for wayland-util.h and the
pages for corresponding structures. As such, the doxygen page for
wayland-util.c has no value, and is redundant.
Remove the doxygen page for wayland-util.c.
Signed-off-by: Yong Bakos <ybakos@humanoriented.com>
Acked-by: Peter Hutterer <peter.hutterer@who-t.net>
Doxygen truncates a WL_PRINTF function attribute, and there does not
seem to be any workaround[1]. When using the attribute like this:
typedef void (*wl_log_func_t)(const char *, va_list) WL_PRINTF(1, 0);
Doxygen generates something that looks like this:
typedef void (*wl_log_func_t)(const char *, va_list) WL_PRINTF(1,
Configure doxygen to consider WL_PRINTF(x,y) as predefined, so it does
not display the attribute at all in the generated documentation.
[1] https://bugzilla.gnome.org/show_bug.cgi?id=774741
Signed-off-by: Yong Bakos <ybakos@humanoriented.com>
Reviewed-by: Peter Hutterer <peter.hutterer@who-t.net>
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>
The Wayland docbook and the doxygen html docs had been presenting
wl_display_get_additional_shm_formats as part of the public API, but the
prototype for this function is in wayland-private.h.
Add a \private annotation to the doc comment, preventing doxygen from
publishing this function as public.
Add logic to the publican xsl to only transform elements with a "prot"
attribute value of "public".
Signed-off-by: Yong Bakos <ybakos@humanoriented.com>
Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
The enum attribute, for which scanner support was introduced in
1771299, can be used to link message arguments to <enum>s. However,
some arguments refer to <enum>s in a different <interface>.
This adds scanner support for referring to an <enum> in a different
<interface> using dot notation. It also sets the attributes in this
style in the wayland XML protocol (wl_shm_pool::create_buffer::format
to wl_shm::format, and wl_surface::set_buffer_transform::transform to
wl_output::transform), and updates the documentation XSL so that this
new style is supported.
Changes since v2:
- add object:: prefix for all enumerations in the documentation
- fix whitespace in scanner.c
- minor code fixup to return early and avoid casts in scanner.c
Changes since v1:
- several implementation bugs fixed
Signed-off-by: Auke Booij <auke@tulcod.com>
Reviewed-by: Nils Christopher Brause <nilschrbrause@googlemail.com>
Reviewed-by: Bill Spitzak <spitzak@gmail.com>
[Pekka: rebased across cde251a124]
[Pekka: wrap lines and space fixes in scanner.c]
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
And insert "client" or "server" into the PROJECT_NAME to know which one we
have.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
This switches the scanner to generate doxygen-compatible tags for the
generated protocol headers, and hooks up the doxygen build to generate server
and client-side API documentation. That documentation is now in
Client/ and Server/, respectively.
GENERATE_HTML is on by default and must be disabled for the xml/man targets to
avoid messing up the new documentation. We disable all three three targets in
the doxyfile (xml and man default to NO anyway) to make it obvious that they
need to be set in the per-target instructions.
Each protocol is a separate doxygen @page, with each interface a @subpage.
Wayland only has one protocol, wayland-protocols will have these nested.
Each protocol page has a list of interfaces and the copyright and description
where available.
All interfaces are grouped by doxygen @defgroup and @ingroups and appear in
"Modules" in the generated output. Each interface subpage has the description
and a link to the actual API doc.
Function, struct and #defines are documented in doxygen style and associated
with the matching interface.
Note that pages and groups have fixed HTML file names and are directly
linkable/bookmark-able.
The @mainpage is a separate file that's included at build time. It doesn't
contain much other than links to where the interesting bits are. It's a static
file though that supports markdown, so we can extend it easily in the future.
For doxygen we need the new options EXTRACT_ALL and OPTIMIZE_OUTPUT_FOR_C so
it scans C code properly. EXTRACT_STATIC is needed since most of the protocol
hooks are static.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
When the scanner changes, we need to rebuild
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
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>
Add general guidelines for using Patchwork, as we heavily rely on it
nowadays.
v2:
- mention also Xwayland and libinput patch management
- reword "if not found in Patchwork"
- reword "Not applicable"
- mention pwclient
Cc: Bryce Harrington <bryce@osg.samsung.com>
Cc: Olivier Fourdan <ofourdan@redhat.com>
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
Reviewed-by: Olivier Fourdan <ofourdan@redhat.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>
