Debian Codegraph @

subprojects/meson-docs/docs/markdown/Wayland-module.md

raw
1 # Unstable Wayland Module
2
3 This module is available since version 0.62.0.
4
5 This module provides helper functions to find wayland protocol
6 xmls and to generate .c and .h files using wayland-scanner
7
8 **Note**: this module is unstable. It is only provided as a technology
9 preview. Its API may change in arbitrary ways between releases or it
10 might be removed from Meson altogether.
11
12 ## Quick Usage
13
14 ```meson
15 project('hello-wayland', 'c')
16
17 wl_dep = dependency('wayland-client')
18 wl_mod = import('unstable-wayland')
19
20 xml = wl_mod.find_protocol('xdg-shell')
21 xdg_shell = wl_mod.scan_xml(xml)
22
23 executable('hw', 'main.c', xdg_shell, dependencies : wl_dep)
24 ```
25
26 ## Methods
27
28 ### find_protocol
29 ```meson
30 xml = wl_mod.find_protocol(
31 'xdg-decoration',
32 state : 'unstable',
33 version : 1,
34 )
35 ```
36 This function requires one positional argument: the protocol base name.
37
38 It takes the following keyword arguments:
39 - `state` Optional arg that specifies the current state of the protocol.
40 Either `'stable'`, `'staging'`, or `'unstable'`. The default is `'stable'`.
41 - `version` The backwards incompatible version number as integer.
42 Required for staging and unstable, but not allowed for stable.
43
44 **Returns**: a [[@file]] that can be passed to [scan_xml](#scan_xml)
45
46 ### scan_xml
47 ```meson
48 generated = wl_mod.scan_xml(
49 'my-protocol.xml',
50 client : true,
51 server : true,
52 public : false,
53 include_core_only : true,
54 )
55 ```
56 This function accepts one or more arguments of either string or file type, so
57 it can be used in conjunction with `find_protocol` or not.
58
59 It takes the following keyword arguments:
60 - `public` Optional arg that specifies the scope of the generated code.
61 The default is false.
62 - `client` Optional arg that specifies if client side header file is
63 generated. The default is true.
64 - `server` Optional arg that specifies if server side header file is
65 generated. The default is false.
66 - `include_core_only` Optional arg that specifies that generated headers only include
67 `wayland-<client|server>-core.h` instead of `wayland-<client|server>.h`.
68 The default is true. Since *0.64.0*
69
70 **Returns**: a list of [[@custom_tgt]] in the order source, client side header,
71 server side header. Generated header files have the name
72 `<name>-<client|server>-protocol.h`.
73
74 ## Links
75 - [Official Wayland Documentation](https://wayland.freedesktop.org/docs/html/)
76 - [Wayland GitLab](https://gitlab.freedesktop.org/wayland)
77 - [Wayland Book](https://wayland-book.com/)