README.md
1libgwater
2=========
3
4libgwater provides several GSources to integrate various events to the GLib main loop.
5
6
7Composition of a GSource
8------------------------
9
10Each GSource is composed of three parts:
11
12- An m4 macro for Autoconf: `GW_CHECK_<SOURCE_NAME>`
13 It takes two optional arguments:
14
15 1. Additionnal `pkg-config` packages to check
16 2. Additionnal headers to check
17
18- A `Makefile.am` snippet for Automake: `libgwater/<source-name>.mk`
19
20 You have to include it in your `Makefile.am`. It defines two variables:
21
22 - `GW_<SOURCE_NAME>_CFLAGS`: contains all the needed `CFLAGS` (including those from the `pkg-config` packages you passed to the m4 macro)
23 - `GW_<SOURCE_NAME>_LIBS`: contains all the needed `LIBS` (including those from the `pkg-config` packages you passed to the m4 macro)
24
25 This snippet is using Automake 1.14 features and Libtool. If you do not use both in your project, you need to adapt and ship it in your project.
26
27- A really basic API:
28 - A `GWater<SourceName>Source` opaque struct
29 - One or more `g_water_<source_name>_source_new()` constructor for said struct
30 - One free function `g_water_<source_name>_source_free()`
31 - Usually a getter, to access the underlaying struct used by the communication library
32
33Non-Autotools setup are not covered upstream but should be easy enough to use.
34
35
36Example usage of XCB GSource
37----------------------------
38
391. Create your project with Autotools files
40
412. Add libgwater as a Git submodule
42 ```shell
43 git submodule add git://github.com/sardemff7/libgwater
44 ```
45
463. Add the m4 macro call to your `configure.ac` (with an additionnal package, `xcb-util`)
47 ```m4
48 GW_CHECK_XCB([xcb-util])
49 ```
50
514. Make sure aclocal will find the m4 file by adding the directory to `ACLOCAL_AMFLAGS` in your `Makefile.am`
52 ```Makefile
53 ACLOCAL_AMFLAGS = -I libgwater ${ACLOCAL_FLAGS}
54 ```
55
565. Include the `Makefile.am` snippet
57 ```Makefile
58 include $(top_srcdir)/libgwater/xcb.mk
59 ```
60
616. Use the `Makefile.am` variables
62 ```Makefile
63 xcb_example_client_SOURCES = client.c
64 xcb_example_client_CFLAGS = $(GW_XCB_CFLAGS)
65 xcb_example_client_LDADD = $(GW_XCB_LIBS)
66 ```
67
687. Use the GSource in your `client.c`
69 ```c
70 #include <glib.h>
71 #include <libgwater-xcb.h>
72
73 gboolean
74 callback(xcb_generic_event_t *event, gpointer user_data)
75 {
76 if ( event == NULL )
77 {
78 /* Error occured */
79 return FALSE;
80 }
81 return TRUE;
82 }
83
84 int
85 main()
86 {
87 GWaterXcbSource *source;
88 GMainLoop *loop;
89
90 loop = g_main_loop_new(NULL, FALSE);
91 source = g_water_xcb_source_new(NULL, NULL, NULL, callback, NULL, NULL);
92
93 g_main_loop_run(loop);
94 g_main_loop_unref(loop);
95
96 g_xcb_source_free(source);
97
98 return 0;
99 }
100 ```
101
102
103Dependencies
104------------
105
106- Common dependencies
107 - GLib 2.36 (or newer)
108- Wayland source
109 - libwayland 1.1.91 (or newer)
110- XCB source
111 - libxcb
112- MPD source
113 - libmpdclient2
114- ALSA Mixer source
115 - alsa-lib
116- Netlink protocol source
117 - libnl-3.0
118- Windows source
119 - `Windows.h`
120
121
122Licence
123-------
124
125libgwater is licenced under the terms of the [MIT license](//opensource.org/licenses/MIT)
126
127
128Author / Contact
129----------------
130
131Quentin “Sardem FF7” Glidic (sardemff7+libgwater@sardemff7.net) — [My other Free Software projects](//www.sardemff7.net/)
132