Initial pass on API stability guarantees

This introduces -DWLR_USE_UNSTABLE and adds information regarding the
stability status to all headers. I started with a conservative set of
headers to mark as stable:

- types/wlr_matrix.h
- util/edges.h
- util/log.h
- util/region.h
- xcursor.h

include/wlr/backend.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_BACKEND_H
 #define WLR_BACKEND_H
 

include/wlr/backend/drm.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_BACKEND_DRM_H
 #define WLR_BACKEND_DRM_H
 

include/wlr/backend/headless.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_BACKEND_HEADLESS_H
 #define WLR_BACKEND_HEADLESS_H
 

include/wlr/backend/interface.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_BACKEND_INTERFACE_H
 #define WLR_BACKEND_INTERFACE_H
 

include/wlr/backend/libinput.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_BACKEND_LIBINPUT_H
 #define WLR_BACKEND_LIBINPUT_H
 

include/wlr/backend/multi.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_BACKEND_MULTI_H
 #define WLR_BACKEND_MULTI_H
 

include/wlr/backend/session/interface.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_BACKEND_SESSION_INTERFACE_H
 #define WLR_BACKEND_SESSION_INTERFACE_H
 

include/wlr/interfaces/wlr_input_device.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_INTERFACES_WLR_INPUT_DEVICE_H
 #define WLR_INTERFACES_WLR_INPUT_DEVICE_H
 

include/wlr/interfaces/wlr_keyboard.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_INTERFACES_WLR_KEYBOARD_H
 #define WLR_INTERFACES_WLR_KEYBOARD_H
 

include/wlr/interfaces/wlr_output.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_INTERFACES_WLR_OUTPUT_H
 #define WLR_INTERFACES_WLR_OUTPUT_H
 

include/wlr/interfaces/wlr_pointer.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_INTERFACES_WLR_POINTER_H
 #define WLR_INTERFACES_WLR_POINTER_H
 

include/wlr/interfaces/wlr_tablet_pad.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_INTERFACES_WLR_TABLET_PAD_H
 #define WLR_INTERFACES_WLR_TABLET_PAD_H
 

include/wlr/interfaces/wlr_tablet_tool.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_INTERFACES_WLR_TABLET_TOOL_H
 #define WLR_INTERFACES_WLR_TABLET_TOOL_H
 

include/wlr/interfaces/wlr_touch.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_INTERFACES_WLR_TOUCH_H
 #define WLR_INTERFACES_WLR_TOUCH_H
 

include/wlr/render/dmabuf.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_RENDER_DMABUF_H
 #define WLR_RENDER_DMABUF_H
 

include/wlr/render/egl.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_RENDER_EGL_H
 #define WLR_RENDER_EGL_H
 

include/wlr/render/gles2.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_RENDER_GLES2_H
 #define WLR_RENDER_GLES2_H
 

include/wlr/render/interface.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_RENDER_INTERFACE_H
 #define WLR_RENDER_INTERFACE_H
 

include/wlr/render/wlr_renderer.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_RENDER_WLR_RENDERER_H
 #define WLR_RENDER_WLR_RENDERER_H
 

include/wlr/render/wlr_texture.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_RENDER_WLR_TEXTURE_H
 #define WLR_RENDER_WLR_TEXTURE_H
 

include/wlr/types/wlr_box.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_BOX_H
 #define WLR_TYPES_WLR_BOX_H
 

include/wlr/types/wlr_buffer.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_BUFFER_H
 #define WLR_TYPES_WLR_BUFFER_H
 

include/wlr/types/wlr_compositor.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_COMPOSITOR_H
 #define WLR_TYPES_WLR_COMPOSITOR_H
 

include/wlr/types/wlr_cursor.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_CURSOR_H
 #define WLR_TYPES_WLR_CURSOR_H
 

include/wlr/types/wlr_data_device.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_DATA_DEVICE_H
 #define WLR_TYPES_WLR_DATA_DEVICE_H
 

include/wlr/types/wlr_export_dmabuf_v1.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_EXPORT_DMABUF_V1_H
 #define WLR_TYPES_WLR_EXPORT_DMABUF_V1_H
 

include/wlr/types/wlr_gamma_control.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_GAMMA_CONTROL_H
 #define WLR_TYPES_WLR_GAMMA_CONTROL_H
 

include/wlr/types/wlr_idle.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_IDLE_H
 #define WLR_TYPES_WLR_IDLE_H
 

include/wlr/types/wlr_idle_inhibit_v1.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_IDLE_INHIBIT_V1_H
 #define WLR_TYPES_WLR_IDLE_INHIBIT_V1_H
 

include/wlr/types/wlr_input_device.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_INPUT_DEVICE_H
 #define WLR_TYPES_WLR_INPUT_DEVICE_H
 

include/wlr/types/wlr_input_inhibitor.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_INPUT_INHIBITOR_H
 #define WLR_TYPES_INPUT_INHIBITOR_H
 #include <wayland-server.h>

include/wlr/types/wlr_keyboard.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_KEYBOARD_H
 #define WLR_TYPES_WLR_KEYBOARD_H
 

include/wlr/types/wlr_layer_shell.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_LAYER_SHELL_H
 #define WLR_TYPES_WLR_LAYER_SHELL_H
 #include <stdbool.h>

include/wlr/types/wlr_linux_dmabuf_v1.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_LINUX_DMABUF_H
 #define WLR_TYPES_WLR_LINUX_DMABUF_H
 

include/wlr/types/wlr_list.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_LIST_H
 #define WLR_TYPES_WLR_LIST_H
 

include/wlr/types/wlr_matrix.h

@@ -1,20 +1,57 @@
+/*
+ * This is a stable interface of wlroots. Future changes will be limited to:
+ *
+ * - New functions
+ * - New struct members
+ * - New enum members
+ *
+ * Note that wlroots does not make an ABI compatibility promise - in the future,
+ * the layout and size of structs used by wlroots may change, requiring code
+ * depending on this header to be recompiled (but not edited).
+ *
+ * Breaking changes are announced by email and follow a 1-year deprecation
+ * schedule. Send an email to ~sircmpwn/wlroots-announce+subscribe@lists.sr.ht
+ * to receive these announcements.
+ */
+
 #ifndef WLR_TYPES_WLR_MATRIX_H
 #define WLR_TYPES_WLR_MATRIX_H
 
 #include <wayland-server.h>
 #include <wlr/types/wlr_box.h>
 
+/** Writes the identity matrix into mat */
 void wlr_matrix_identity(float mat[static 9]);
+
+/** mat ← a × b */
 void wlr_matrix_multiply(float mat[static 9], const float a[static 9],
 	const float b[static 9]);
+
 void wlr_matrix_transpose(float mat[static 9], const float a[static 9]);
+
+/** Writes a 2D translation matrix to mat of magnitude (x, y) */
 void wlr_matrix_translate(float mat[static 9], float x, float y);
+
+/** Writes a 2D scale matrix to mat of magnitude (x, y) */
 void wlr_matrix_scale(float mat[static 9], float x, float y);
+
+/** Writes a 2D rotation matrix to mat at an angle of rad radians */
 void wlr_matrix_rotate(float mat[static 9], float rad);
+
+/** Writes a transformation matrix which applies the specified
+ *  wl_output_transform to mat */
 void wlr_matrix_transform(float mat[static 9],
 	enum wl_output_transform transform);
+
+/** Writes a 2D orthographic projection matrix to mat of (width, height) with a
+ *  specified wl_output_transform*/
 void wlr_matrix_projection(float mat[static 9], int width, int height,
 	enum wl_output_transform transform);
+
+/** Shortcut for the various matrix operations involved in projecting the
+ *  specified wlr_box onto a given orthographic projection with a given
+ *  rotation. The result is written to mat, which can be applied to each
+ *  coordinate of the box to get a new coordinate from [-1,1]. */
 void wlr_matrix_project_box(float mat[static 9], const struct wlr_box *box,
 	enum wl_output_transform transform, float rotation,
 	const float projection[static 9]);

include/wlr/types/wlr_output.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_OUTPUT_H
 #define WLR_TYPES_WLR_OUTPUT_H
 

include/wlr/types/wlr_output_damage.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_OUTPUT_DAMAGE_H
 #define WLR_TYPES_WLR_OUTPUT_DAMAGE_H
 

include/wlr/types/wlr_output_layout.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_OUTPUT_LAYOUT_H
 #define WLR_TYPES_WLR_OUTPUT_LAYOUT_H
 

include/wlr/types/wlr_pointer.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_POINTER_H
 #define WLR_TYPES_WLR_POINTER_H
 

include/wlr/types/wlr_primary_selection.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_PRIMARY_SELECTION_H
 #define WLR_TYPES_WLR_PRIMARY_SELECTION_H
 

include/wlr/types/wlr_region.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_REGION_H
 #define WLR_TYPES_WLR_REGION_H
 

include/wlr/types/wlr_screencopy_v1.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_SCREENCOPY_V1_H
 #define WLR_TYPES_WLR_SCREENCOPY_V1_H
 

include/wlr/types/wlr_screenshooter.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_SCREENSHOOTER_H
 #define WLR_TYPES_WLR_SCREENSHOOTER_H
 

include/wlr/types/wlr_seat.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_SEAT_H
 #define WLR_TYPES_WLR_SEAT_H
 

include/wlr/types/wlr_server_decoration.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_SERVER_DECORATION_H
 #define WLR_TYPES_WLR_SERVER_DECORATION_H
 

include/wlr/types/wlr_surface.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_SURFACE_H
 #define WLR_TYPES_WLR_SURFACE_H
 

include/wlr/types/wlr_tablet_pad.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_TABLET_PAD_H
 #define WLR_TYPES_WLR_TABLET_PAD_H
 

include/wlr/types/wlr_tablet_tool.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_TABLET_TOOL_H
 #define WLR_TYPES_TABLET_TOOL_H
 

include/wlr/types/wlr_tablet_v2.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_TABLET_V2_H
 #define WLR_TYPES_WLR_TABLET_V2_H
 

include/wlr/types/wlr_touch.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_TOUCH_H
 #define WLR_TYPES_WLR_TOUCH_H
 

include/wlr/types/wlr_virtual_keyboard_v1.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_VIRTUAL_KEYBOARD_V1_H
 #define WLR_TYPES_WLR_VIRTUAL_KEYBOARD_V1_H
 

include/wlr/types/wlr_wl_shell.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_WL_SHELL_H
 #define WLR_TYPES_WLR_WL_SHELL_H
 

include/wlr/types/wlr_xcursor_manager.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_XCURSOR_MANAGER_H
 #define WLR_TYPES_WLR_XCURSOR_MANAGER_H
 

include/wlr/types/wlr_xdg_output.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_XDG_OUTPUT_H
 #define WLR_TYPES_WLR_XDG_OUTPUT_H
 #include <wayland-server.h>

include/wlr/types/wlr_xdg_shell.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_XDG_SHELL_H
 #define WLR_TYPES_WLR_XDG_SHELL_H
 #include <wlr/types/wlr_box.h>

include/wlr/types/wlr_xdg_shell_v6.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_TYPES_WLR_XDG_SHELL_V6_H
 #define WLR_TYPES_WLR_XDG_SHELL_V6_H
 

include/wlr/util/edges.h

@@ -1,3 +1,19 @@
+/*
+ * This is a stable interface of wlroots. Future changes will be limited to:
+ *
+ * - New functions
+ * - New struct members
+ * - New enum members
+ *
+ * Note that wlroots does not make an ABI compatibility promise - in the future,
+ * the layout and size of structs used by wlroots may change, requiring code
+ * depending on this header to be recompiled (but not edited).
+ *
+ * Breaking changes are announced by email and follow a 1-year deprecation
+ * schedule. Send an email to ~sircmpwn/wlroots-announce+subscribe@lists.sr.ht
+ * to receive these announcements.
+ */
+
 #ifndef WLR_UTIL_EDGES_H
 #define WLR_UTIL_EDGES_H
 

include/wlr/util/log.h

@@ -1,3 +1,19 @@
+/*
+ * This is a stable interface of wlroots. Future changes will be limited to:
+ *
+ * - New functions
+ * - New struct members
+ * - New enum members
+ *
+ * Note that wlroots does not make an ABI compatibility promise - in the future,
+ * the layout and size of structs used by wlroots may change, requiring code
+ * depending on this header to be recompiled (but not edited).
+ *
+ * Breaking changes are announced by email and follow a 1-year deprecation
+ * schedule. Send an email to ~sircmpwn/wlroots-announce+subscribe@lists.sr.ht
+ * to receive these announcements.
+ */
+
 #ifndef WLR_UTIL_LOG_H
 #define WLR_UTIL_LOG_H
 

include/wlr/util/region.h

@@ -1,6 +1,21 @@
+/*
+ * This is a stable interface of wlroots. Future changes will be limited to:
+ *
+ * - New functions
+ * - New struct members
+ * - New enum members
+ *
+ * Note that wlroots does not make an ABI compatibility promise - in the future,
+ * the layout and size of structs used by wlroots may change, requiring code
+ * depending on this header to be recompiled (but not edited).
+ *
+ * Breaking changes are announced by email and follow a 1-year deprecation
+ * schedule. Send an email to ~sircmpwn/wlroots-announce+subscribe@lists.sr.ht
+ * to receive these announcements.
+ */
+
 #ifndef WLR_UTIL_REGION_H
 #define WLR_UTIL_REGION_H
-
 #include <pixman.h>
 #include <wayland-server.h>
 

include/wlr/xcursor.h

@@ -24,8 +24,19 @@
  */
 
 /*
- * This is adapted from wayland-cursor, but with the wl_shm client stuff removed
+ * This is a stable interface of wlroots. Future changes will be limited to:
- * so we can use it on the compositor, too.
+ *
+ * - New functions
+ * - New struct members
+ * - New enum members
+ *
+ * Note that wlroots does not make an ABI compatibility promise - in the future,
+ * the layout and size of structs used by wlroots may change, requiring code
+ * depending on this header to be recompiled (but not edited).
+ *
+ * Breaking changes are announced by email and follow a 1-year deprecation
+ * schedule. Send an email to ~sircmpwn/wlroots-announce+subscribe@lists.sr.ht
+ * to receive these announcements.
  */
 
 #ifndef WLR_XCURSOR_H

include/wlr/xwayland.h

@@ -1,3 +1,11 @@
+/*
+ * This an unstable interface of wlroots. No guarantees are made regarding the
+ * future consistency of this API.
+ */
+#ifndef WLR_USE_UNSTABLE
+#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
+#endif
+
 #ifndef WLR_XWAYLAND_H
 #define WLR_XWAYLAND_H
 

meson.build

@@ -29,6 +29,10 @@ add_project_link_arguments(
 	'-Wl,-rpath,@0@'.format(meson.build_root()),
 	language: 'c',
 )
+add_project_arguments(
+	'-DWLR_USE_UNSTABLE',
+	language: 'c',
+)
 
 conf_data = configuration_data()