gtk4-layer-shell icon indicating copy to clipboard operation
gtk4-layer-shell copied to clipboard
verified publisher icon wmww

ABI break with 1.1.0

Open werdahias opened this issue 10 months ago • 5 comments

When preparing the 1.1.0 for upload to Debian I noticed that the ABI has been broken:

--- debian/libgtk4-layer-shell0.symbols (libgtk4-layer-shell0_1.1.0-1_amd64)
+++ dpkg-gensymbolseBv9dT	2025-01-31 14:48:17.296594675 +0000
@@ -1,13 +1,19 @@
 libgtk4-layer-shell.so.0 libgtk4-layer-shell0 #MINVER#
 * Build-Depends-Package: libgtk4-layer-shell-dev
- all_layer_surfaces@Base 1.0.2
- args_contains_client_facing_proxy@Base 1.0.4
+#MISSING: 1.1.0-1# all_layer_surfaces@Base 1.0.2
+#MISSING: 1.1.0-1# args_contains_client_facing_proxy@Base 1.0.4
+ cached_display@Base 1.1.0-1
  client_facing_proxy_id@Base 1.0.2
- find_layer_surface_with_wl_surface@Base 1.0.2
- gdk_anchor_hints_get_xdg_positioner_constraint_adjustment@Base 1.0.2
- gdk_gravity_get_xdg_positioner_anchor@Base 1.0.2
- gdk_gravity_get_xdg_positioner_gravity@Base 1.0.2
- get_interface_of_object_created_by_request@Base 1.0.4
+ current_display@Base 1.1.0-1
+ current_lock@Base 1.1.0-1
+#MISSING: 1.1.0-1# find_layer_surface_with_wl_surface@Base 1.0.2
+#MISSING: 1.1.0-1# gdk_anchor_hints_get_xdg_positioner_constraint_adjustment@Base 1.0.2
+#MISSING: 1.1.0-1# gdk_gravity_get_xdg_positioner_anchor@Base 1.0.2
+#MISSING: 1.1.0-1# gdk_gravity_get_xdg_positioner_gravity@Base 1.0.2
+#MISSING: 1.1.0-1# get_interface_of_object_created_by_request@Base 1.0.4
+ get_layer_shell_global_from_display@Base 1.1.0-1
+ get_session_lock_global_from_display@Base 1.1.0-1
+ get_xdg_surface_server_from_xdg_surface@Base 1.1.0-1
  gtk_layer_auto_exclusive_zone_enable@Base 1.0.2
  gtk_layer_auto_exclusive_zone_is_enabled@Base 1.0.2
  gtk_layer_get_anchor@Base 1.0.2
@@ -32,30 +38,63 @@
  gtk_layer_set_margin@Base 1.0.2
  gtk_layer_set_monitor@Base 1.0.2
  gtk_layer_set_namespace@Base 1.0.2
- gtk_layer_shell_edge_array_get_zwlr_layer_shell_v1_anchor@Base 1.0.2
- gtk_layer_shell_layer_get_zwlr_layer_shell_v1_layer@Base 1.0.2
- gtk_wayland_get_layer_shell_global@Base 1.0.2
- gtk_wayland_init_if_needed@Base 1.0.2
- gtk_window_get_layer_surface@Base 1.0.2
+#MISSING: 1.1.0-1# gtk_layer_shell_edge_array_get_zwlr_layer_shell_v1_anchor@Base 1.0.2
+#MISSING: 1.1.0-1# gtk_layer_shell_layer_get_zwlr_layer_shell_v1_layer@Base 1.0.2
+ gtk_session_lock_instance_assign_window_to_monitor@Base 1.1.0-1
+ gtk_session_lock_instance_get_type@Base 1.1.0-1
+ gtk_session_lock_instance_is_locked@Base 1.1.0-1
+ gtk_session_lock_instance_lock@Base 1.1.0-1
+ gtk_session_lock_instance_new@Base 1.1.0-1
+ gtk_session_lock_instance_unlock@Base 1.1.0-1
+ gtk_session_lock_is_supported@Base 1.1.0-1
+#MISSING: 1.1.0-1# gtk_wayland_get_layer_shell_global@Base 1.0.2
+#MISSING: 1.1.0-1# gtk_wayland_init_if_needed@Base 1.0.2
+#MISSING: 1.1.0-1# gtk_window_get_layer_surface@Base 1.0.2
+ layer_shell_global@Base 1.1.0-1
+ layer_shell_requested@Base 1.1.0-1
  layer_surface_auto_exclusive_zone_enable@Base 1.0.2
+ layer_surface_configure_acked@Base 1.1.0-1
  layer_surface_get_namespace@Base 1.0.2
- layer_surface_handle_request@Base 1.0.2
- layer_surface_new@Base 1.0.2
+#MISSING: 1.1.0-1# layer_surface_handle_request@Base 1.0.2
+ layer_surface_install_hook@Base 1.1.0-1
+ layer_surface_invalidate_preferred_size@Base 1.1.0-1
+ layer_surface_make@Base 1.1.0-1
+#MISSING: 1.1.0-1# layer_surface_new@Base 1.0.2
  layer_surface_set_anchor@Base 1.0.2
  layer_surface_set_exclusive_zone@Base 1.0.2
  layer_surface_set_keyboard_mode@Base 1.0.2
  layer_surface_set_layer@Base 1.0.2
  layer_surface_set_margin@Base 1.0.2
- layer_surface_set_monitor@Base 1.0.2
+#MISSING: 1.1.0-1# layer_surface_set_monitor@Base 1.0.2
  layer_surface_set_name_space@Base 1.0.2
+ layer_surface_set_output@Base 1.1.0-1
+ layer_surface_uninit@Base 1.1.0-1
  libwayland_shim_clear_client_proxy_data@Base 1.0.2
  libwayland_shim_create_client_proxy@Base 1.0.2
  libwayland_shim_get_client_proxy_data@Base 1.0.2
  libwayland_shim_has_initialized@Base 1.0.2
- libwayland_shim_real_wl_proxy_add_dispatcher@Base 1.0.2
- libwayland_shim_real_wl_proxy_destroy@Base 1.0.2
- libwayland_shim_real_wl_proxy_marshal_array_flags@Base 1.0.2
- wl_proxy_add_dispatcher@Base 1.0.2
+ libwayland_shim_install_request_hook@Base 1.1.0-1
+ libwayland_shim_proxy_get_dispatcher@Base 1.1.0-1
+ libwayland_shim_proxy_get_display@Base 1.1.0-1
+ libwayland_shim_proxy_get_implementation@Base 1.1.0-1
+ libwayland_shim_proxy_get_queue@Base 1.1.0-1
+ libwayland_shim_proxy_get_user_data@Base 1.1.0-1
+ libwayland_shim_proxy_invoke_dispatcher@Base 1.1.0-1
+#MISSING: 1.1.0-1# libwayland_shim_real_wl_proxy_add_dispatcher@Base 1.0.2
+#MISSING: 1.1.0-1# libwayland_shim_real_wl_proxy_destroy@Base 1.0.2
+#MISSING: 1.1.0-1# libwayland_shim_real_wl_proxy_marshal_array_flags@Base 1.0.2
+ lock_surface_install_hook@Base 1.1.0-1
+ lock_surface_make@Base 1.1.0-1
+ lock_surface_map@Base 1.1.0-1
+ lock_surface_uninit@Base 1.1.0-1
+ session_lock_get_active_lock@Base 1.1.0-1
+ session_lock_global@Base 1.1.0-1
+ session_lock_lock@Base 1.1.0-1
+ session_lock_requested@Base 1.1.0-1
+ session_lock_unlock@Base 1.1.0-1
+ stubbed_surface_destroyed@Base 1.1.0-1
+ stubbed_surface_init@Base 1.1.0-1
+#MISSING: 1.1.0-1# wl_proxy_add_dispatcher@Base 1.0.2
  wl_proxy_destroy@Base 1.0.2
  wl_proxy_marshal@Base 1.0.2
  wl_proxy_marshal_array@Base 1.0.2
@@ -65,3 +104,64 @@
  wl_proxy_marshal_constructor@Base 1.0.2
  wl_proxy_marshal_constructor_versioned@Base 1.0.2
  wl_proxy_marshal_flags@Base 1.0.2
+ xdg_surface_server_get_xdg_surface@Base 1.1.0-1
+ xdg_surface_server_send_configure@Base 1.1.0-1
+ xdg_surface_server_uninit@Base 1.1.0-1
+liblayer-shell-preload.so libgtk4-layer-shell0 #MINVER#
+ cached_display@Base 1.1.0-1
+ client_facing_proxy_id@Base 1.1.0-1
+ current_display@Base 1.1.0-1
+ current_lock@Base 1.1.0-1
+ get_layer_shell_global_from_display@Base 1.1.0-1
+ get_session_lock_global_from_display@Base 1.1.0-1
+ get_xdg_surface_server_from_xdg_surface@Base 1.1.0-1
+ layer_shell_global@Base 1.1.0-1
+ layer_shell_requested@Base 1.1.0-1
+ layer_surface_auto_exclusive_zone_enable@Base 1.1.0-1
+ layer_surface_configure_acked@Base 1.1.0-1
+ layer_surface_get_namespace@Base 1.1.0-1
+ layer_surface_install_hook@Base 1.1.0-1
+ layer_surface_invalidate_preferred_size@Base 1.1.0-1
+ layer_surface_make@Base 1.1.0-1
+ layer_surface_set_anchor@Base 1.1.0-1
+ layer_surface_set_exclusive_zone@Base 1.1.0-1
+ layer_surface_set_keyboard_mode@Base 1.1.0-1
+ layer_surface_set_layer@Base 1.1.0-1
+ layer_surface_set_margin@Base 1.1.0-1
+ layer_surface_set_name_space@Base 1.1.0-1
+ layer_surface_set_output@Base 1.1.0-1
+ layer_surface_uninit@Base 1.1.0-1
+ libwayland_shim_clear_client_proxy_data@Base 1.1.0-1
+ libwayland_shim_create_client_proxy@Base 1.1.0-1
+ libwayland_shim_get_client_proxy_data@Base 1.1.0-1
+ libwayland_shim_has_initialized@Base 1.1.0-1
+ libwayland_shim_install_request_hook@Base 1.1.0-1
+ libwayland_shim_proxy_get_dispatcher@Base 1.1.0-1
+ libwayland_shim_proxy_get_display@Base 1.1.0-1
+ libwayland_shim_proxy_get_implementation@Base 1.1.0-1
+ libwayland_shim_proxy_get_queue@Base 1.1.0-1
+ libwayland_shim_proxy_get_user_data@Base 1.1.0-1
+ libwayland_shim_proxy_invoke_dispatcher@Base 1.1.0-1
+ lock_surface_install_hook@Base 1.1.0-1
+ lock_surface_make@Base 1.1.0-1
+ lock_surface_map@Base 1.1.0-1
+ lock_surface_uninit@Base 1.1.0-1
+ session_lock_get_active_lock@Base 1.1.0-1
+ session_lock_global@Base 1.1.0-1
+ session_lock_lock@Base 1.1.0-1
+ session_lock_requested@Base 1.1.0-1
+ session_lock_unlock@Base 1.1.0-1
+ stubbed_surface_destroyed@Base 1.1.0-1
+ stubbed_surface_init@Base 1.1.0-1
+ wl_proxy_destroy@Base 1.1.0-1
+ wl_proxy_marshal@Base 1.1.0-1
+ wl_proxy_marshal_array@Base 1.1.0-1
+ wl_proxy_marshal_array_constructor@Base 1.1.0-1
+ wl_proxy_marshal_array_constructor_versioned@Base 1.1.0-1
+ wl_proxy_marshal_array_flags@Base 1.1.0-1
+ wl_proxy_marshal_constructor@Base 1.1.0-1
+ wl_proxy_marshal_constructor_versioned@Base 1.1.0-1
+ wl_proxy_marshal_flags@Base 1.1.0-1
+ xdg_surface_server_get_xdg_surface@Base 1.1.0-1
+ xdg_surface_server_send_configure@Base 1.1.0-1
+ xdg_surface_server_uninit@Base 1.1.0-1

Note this MISSING symbols that just disappeared. Fortunately nothing in Debian uses those symbols (as far as I can tell). Please refrain from breaking ABI like this, this causes just headaches for maintainers

werdahias avatar Jan 31 '25 14:01 werdahias

Sorry about that, I didn't realize I needed to be controlling symbol visibility. These were never exposed by public headers, and not supposed to be used externally. I will look into how to make only symbols that are part of the public API visible. Next release all the private symbols will go away, but after that it shouldn't be an issue.

wmww avatar Feb 02 '25 05:02 wmww

Does #73 look like it will solve the problem in the future?

wmww avatar Feb 05 '25 04:02 wmww

sorry, had no time to test until now

werdahias avatar Mar 09 '25 14:03 werdahias

building 1.1.0 with #73 applied still errors because some symbols were dropped:

dpkg-gensymbols: warning: new libraries appeared in the symbols file: liblayer-shell-preload.so
dpkg-gensymbols: warning: some new symbols appeared in the symbols file: see diff output below
dpkg-gensymbols: error: some symbols or patterns disappeared in the symbols file: see diff output below
dpkg-gensymbols: warning: debian/libgtk4-layer-shell0/DEBIAN/symbols doesn't match completely debian/libgtk4-layer-shell0.symbols
--- debian/libgtk4-layer-shell0.symbols (libgtk4-layer-shell0_1.1.0-2_amd64)
+++ dpkg-gensymbolsHsyEoi	2025-03-09 14:30:53.579524101 +0000
@@ -1,13 +1,13 @@
 libgtk4-layer-shell.so.0 libgtk4-layer-shell0 #MINVER#
 * Build-Depends-Package: libgtk4-layer-shell-dev
- all_layer_surfaces@Base 1.0.2
- args_contains_client_facing_proxy@Base 1.0.4
- client_facing_proxy_id@Base 1.0.2
- find_layer_surface_with_wl_surface@Base 1.0.2
- gdk_anchor_hints_get_xdg_positioner_constraint_adjustment@Base 1.0.2
- gdk_gravity_get_xdg_positioner_anchor@Base 1.0.2
- gdk_gravity_get_xdg_positioner_gravity@Base 1.0.2
- get_interface_of_object_created_by_request@Base 1.0.4
+#MISSING: 1.1.0-2# all_layer_surfaces@Base 1.0.2
+#MISSING: 1.1.0-2# args_contains_client_facing_proxy@Base 1.0.4
+#MISSING: 1.1.0-2# client_facing_proxy_id@Base 1.0.2
+#MISSING: 1.1.0-2# find_layer_surface_with_wl_surface@Base 1.0.2
+#MISSING: 1.1.0-2# gdk_anchor_hints_get_xdg_positioner_constraint_adjustment@Base 1.0.2
+#MISSING: 1.1.0-2# gdk_gravity_get_xdg_positioner_anchor@Base 1.0.2
+#MISSING: 1.1.0-2# gdk_gravity_get_xdg_positioner_gravity@Base 1.0.2
+#MISSING: 1.1.0-2# get_interface_of_object_created_by_request@Base 1.0.4
  gtk_layer_auto_exclusive_zone_enable@Base 1.0.2
  gtk_layer_auto_exclusive_zone_is_enabled@Base 1.0.2
  gtk_layer_get_anchor@Base 1.0.2
@@ -32,30 +32,37 @@
  gtk_layer_set_margin@Base 1.0.2
  gtk_layer_set_monitor@Base 1.0.2
  gtk_layer_set_namespace@Base 1.0.2
- gtk_layer_shell_edge_array_get_zwlr_layer_shell_v1_anchor@Base 1.0.2
- gtk_layer_shell_layer_get_zwlr_layer_shell_v1_layer@Base 1.0.2
- gtk_wayland_get_layer_shell_global@Base 1.0.2
- gtk_wayland_init_if_needed@Base 1.0.2
- gtk_window_get_layer_surface@Base 1.0.2
- layer_surface_auto_exclusive_zone_enable@Base 1.0.2
- layer_surface_get_namespace@Base 1.0.2
- layer_surface_handle_request@Base 1.0.2
- layer_surface_new@Base 1.0.2
- layer_surface_set_anchor@Base 1.0.2
- layer_surface_set_exclusive_zone@Base 1.0.2
- layer_surface_set_keyboard_mode@Base 1.0.2
- layer_surface_set_layer@Base 1.0.2
- layer_surface_set_margin@Base 1.0.2
- layer_surface_set_monitor@Base 1.0.2
- layer_surface_set_name_space@Base 1.0.2
- libwayland_shim_clear_client_proxy_data@Base 1.0.2
- libwayland_shim_create_client_proxy@Base 1.0.2
- libwayland_shim_get_client_proxy_data@Base 1.0.2
- libwayland_shim_has_initialized@Base 1.0.2
- libwayland_shim_real_wl_proxy_add_dispatcher@Base 1.0.2
- libwayland_shim_real_wl_proxy_destroy@Base 1.0.2
- libwayland_shim_real_wl_proxy_marshal_array_flags@Base 1.0.2
- wl_proxy_add_dispatcher@Base 1.0.2
+#MISSING: 1.1.0-2# gtk_layer_shell_edge_array_get_zwlr_layer_shell_v1_anchor@Base 1.0.2
+#MISSING: 1.1.0-2# gtk_layer_shell_layer_get_zwlr_layer_shell_v1_layer@Base 1.0.2
+ gtk_session_lock_instance_assign_window_to_monitor@Base 1.1.0-2
+ gtk_session_lock_instance_get_type@Base 1.1.0-2
+ gtk_session_lock_instance_is_locked@Base 1.1.0-2
+ gtk_session_lock_instance_lock@Base 1.1.0-2
+ gtk_session_lock_instance_new@Base 1.1.0-2
+ gtk_session_lock_instance_unlock@Base 1.1.0-2
+ gtk_session_lock_is_supported@Base 1.1.0-2
+#MISSING: 1.1.0-2# gtk_wayland_get_layer_shell_global@Base 1.0.2
+#MISSING: 1.1.0-2# gtk_wayland_init_if_needed@Base 1.0.2
+#MISSING: 1.1.0-2# gtk_window_get_layer_surface@Base 1.0.2
+#MISSING: 1.1.0-2# layer_surface_auto_exclusive_zone_enable@Base 1.0.2
+#MISSING: 1.1.0-2# layer_surface_get_namespace@Base 1.0.2
+#MISSING: 1.1.0-2# layer_surface_handle_request@Base 1.0.2
+#MISSING: 1.1.0-2# layer_surface_new@Base 1.0.2
+#MISSING: 1.1.0-2# layer_surface_set_anchor@Base 1.0.2
+#MISSING: 1.1.0-2# layer_surface_set_exclusive_zone@Base 1.0.2
+#MISSING: 1.1.0-2# layer_surface_set_keyboard_mode@Base 1.0.2
+#MISSING: 1.1.0-2# layer_surface_set_layer@Base 1.0.2
+#MISSING: 1.1.0-2# layer_surface_set_margin@Base 1.0.2
+#MISSING: 1.1.0-2# layer_surface_set_monitor@Base 1.0.2
+#MISSING: 1.1.0-2# layer_surface_set_name_space@Base 1.0.2
+#MISSING: 1.1.0-2# libwayland_shim_clear_client_proxy_data@Base 1.0.2
+#MISSING: 1.1.0-2# libwayland_shim_create_client_proxy@Base 1.0.2
+#MISSING: 1.1.0-2# libwayland_shim_get_client_proxy_data@Base 1.0.2
+#MISSING: 1.1.0-2# libwayland_shim_has_initialized@Base 1.0.2
+#MISSING: 1.1.0-2# libwayland_shim_real_wl_proxy_add_dispatcher@Base 1.0.2
+#MISSING: 1.1.0-2# libwayland_shim_real_wl_proxy_destroy@Base 1.0.2
+#MISSING: 1.1.0-2# libwayland_shim_real_wl_proxy_marshal_array_flags@Base 1.0.2
+#MISSING: 1.1.0-2# wl_proxy_add_dispatcher@Base 1.0.2
  wl_proxy_destroy@Base 1.0.2
  wl_proxy_marshal@Base 1.0.2
  wl_proxy_marshal_array@Base 1.0.2
@@ -65,3 +72,13 @@
  wl_proxy_marshal_constructor@Base 1.0.2
  wl_proxy_marshal_constructor_versioned@Base 1.0.2
  wl_proxy_marshal_flags@Base 1.0.2
+liblayer-shell-preload.so libgtk4-layer-shell0 #MINVER#
+ wl_proxy_destroy@Base 1.1.0-2
+ wl_proxy_marshal@Base 1.1.0-2
+ wl_proxy_marshal_array@Base 1.1.0-2
+ wl_proxy_marshal_array_constructor@Base 1.1.0-2
+ wl_proxy_marshal_array_constructor_versioned@Base 1.1.0-2
+ wl_proxy_marshal_array_flags@Base 1.1.0-2
+ wl_proxy_marshal_constructor@Base 1.1.0-2
+ wl_proxy_marshal_constructor_versioned@Base 1.1.0-2
+ wl_proxy_marshal_flags@Base 1.1.0-2

Note the MISSING lines. Another question that came up: Is liblayer-shell-preload supposed to be used with libgtk-layershell0 (like as a plugin) ?

werdahias avatar Mar 09 '25 14:03 werdahias

These symbols are NOT coming back. They were never part of the API, they were never supposed to be used, and since they aren't in any public header files they should not be being used by anything. The point is to do things right going forwards by only exporting symbols that are actually part of the API, but this means dropping all the unstable internal symbols.

No, liblayer-shell-preload is to be used by end users to make programs (GTK or otherwise) that don't have support for layer shell built in use Layer Shell. If a program is built with gtk4-layer-shell then using liblayer-shell-preload with it is unnecessary, and likely won't work. liblayer-shell-preload should not be linked to by other programs, and as such does not need to be versioned (no 0 suffix). Possibly it belongs in its own package since it has a different usecase? Not sure what the normal way to split things up is. You can read more about it here

wmww avatar Mar 10 '25 19:03 wmww