Alias the accidentally exposed ABI into different functions

We rename the previously exported symbols to something else that doesn't
pollute our namespace. Then we use an assembly command to map the symbol into
the current ABI version. Once we change that one, the symbols will disappear
from the new version, creating a linker error. Sicne we don't expect anyone to
use them anyway, life will just go on normally for everyone.

This also clears up the actual symbols for use in our code if we need to.

For information on the asm command:
https://gcc.gnu.org/wiki/SymbolVersioning
https://akkadia.org/drepper/symbol-versioning
https://www.akkadia.org/drepper/dsohowto.pdf (p39)

A special "trick" is used here to hide the ABI from new versions:
Usually when defining multiple versioned symbols, one would define one as the
default one with @@
    .symver _foo1,foo@VERSION1
    .symver _foo2,foo@@version2 <-- default one

By leaving out the default one, ld doesn't know which one to link to and
fails with an unresolved symbol. rtld however can still figure it out, so
anything compiled will continue to work. This way we can make a symbol
disappear from the library for new builds but have old builds continue to
work with the new version.

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

libwacom/Makefile.am

@@ -12,7 +12,8 @@ libwacom_la_SOURCES = \
                       libwacomint.h \
                       libwacom.c \
                       libwacom-error.c \
-                      libwacom-database.c
+                      libwacom-database.c \
+                      libwacom-deprecated.c
 
 libwacom_la_LIBADD = $(GLIB_LIBS)
 libwacom_la_CFLAGS = $(AM_CPPFLAGS) $(GLIB_CFLAGS)

libwacom/libwacom-deprecated.c

@@ -0,0 +1,86 @@
+/*
+ * Copyright © 2019 Red Hat, Inc.
+ *
+ * Permission to use, copy, modify, distribute, and sell this software
+ * and its documentation for any purpose is hereby granted without
+ * fee, provided that the above copyright notice appear in all copies
+ * and that both that copyright notice and this permission notice
+ * appear in supporting documentation, and that the name of Red Hat
+ * not be used in advertising or publicity pertaining to distribution
+ * of the software without specific, written prior permission.  Red
+ * Hat makes no representations about the suitability of this software
+ * for any purpose.  It is provided "as is" without express or implied
+ * warranty.
+ *
+ * THE AUTHORS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+ * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN
+ * NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
+ * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+ * OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
+ * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
+ * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ *
+ */
+
+#ifdef HAVE_CONFIG_H
+#include "config.h"
+#endif
+
+#define _GNU_SOURCE
+#include <stdio.h>
+#include <libwacom.h>
+
+/* Deprecated symbols. Up to including libwacom 0.33, these symbols ended up
+ * in the public ABI.But not the API, the declarations were always in an
+ * internal header only.
+ *
+ * All of these have no use for the caller and in some cases only serve to
+ * corrupt memory if the caller actually invokes them. There aren't any
+ * legitimate users out there, but let's be safe anyway. For backwards
+ * compatibility, we create noop functions for those and alias
+ * them to the previously exposed public symbols.
+ *
+ * If the soname is ever bumped for an incompatible change, we can remove
+ * all these.
+ */
+#define LIBWACOM_EXPORT __attribute__ ((visibility("default")))
+
+void _match_destroy(WacomMatch *match);
+WacomMatch* _match_new(const char *name, WacomBusType bus,
+                       int vendor_id, int product_id);
+void _error_set(WacomError *error, enum WacomErrorCode code,
+                const char *msg, ...);
+void _stylus_destroy(WacomStylus *stylus);
+void _update_match(WacomDevice *device, const WacomMatch *match);
+
+LIBWACOM_EXPORT void
+_match_destroy(WacomMatch *match)
+{
+}
+asm(".symver _match_destroy,libwacom_match_destroy@LIBWACOM_0.33");
+
+
+LIBWACOM_EXPORT WacomMatch*
+_match_new(const char *name, WacomBusType bus, int vendor_id, int product_id)
+{
+	return NULL;
+}
+asm(".symver _match_new,libwacom_match_new@LIBWACOM_0.33");
+
+LIBWACOM_EXPORT void
+_error_set(WacomError *error, enum WacomErrorCode code, const char *msg, ...)
+{
+}
+asm(".symver _error_set,libwacom_error_set@LIBWACOM_0.33");
+
+LIBWACOM_EXPORT void
+_stylus_destroy(WacomStylus *stylus)
+{
+}
+asm(".symver _stylus_destroy,libwacom_stylus_destroy@LIBWACOM_0.33");
+
+LIBWACOM_EXPORT void
+_update_match(WacomDevice *device, const WacomMatch *newmatch)
+{
+}
+asm(".symver _update_match,libwacom_update_match@LIBWACOM_0.33");

libwacom/libwacom-error.c

@@ -64,18 +64,7 @@ libwacom_error_get_message(WacomError *error)
 	return error->msg;
 }
 
-/* This wasn't supposed to have been exported, but ...*/
 __attribute__ ((format (printf, 3, 4)))
-LIBWACOM_EXPORT void
-libwacom_error_set(WacomError *error, enum WacomErrorCode code, const char *msg, ...)
-{
-	if (!error)
-		return;
-
-	error->code = code;
-	asprintf(&error->msg, "%s has been deprecated\n", __func__);
-}
-
 void
 set_error(WacomError *error, enum WacomErrorCode code, const char *msg, ...)
 {

libwacom/libwacom.c

@@ -873,14 +873,6 @@ libwacom_destroy(WacomDevice *device)
 	libwacom_unref(device);
 }
 
-LIBWACOM_EXPORT void
-libwacom_match_destroy(WacomMatch *match)
-{
-	/* This function intentionally does nothing. It was accidentally
-	 * exported but never intended to be used by callers, only our
-	 * internal database may destroy a match */
-}
-
 WacomMatch*
 libwacom_match_ref(WacomMatch *match)
 {
@@ -901,12 +893,6 @@ libwacom_match_unref(WacomMatch *match)
 	return NULL;
 }
 
-LIBWACOM_EXPORT WacomMatch*
-libwacom_match_new(const char *name, WacomBusType bus, int vendor_id, int product_id)
-{
-	return NULL;
-}
-
 WacomMatch*
 libwacom_match_create(const char *name, WacomBusType bus, int vendor_id, int product_id)
 {
@@ -929,14 +915,6 @@ libwacom_match_create(const char *name, WacomBusType bus, int vendor_id, int pro
 	return match;
 }
 
-LIBWACOM_EXPORT void
-libwacom_update_match(WacomDevice *device, const WacomMatch *newmatch)
-{
-	/* This function intentionally does nothing. It was accidentally
-	 * exported but never intended to be used by callers, only our
-	 * internal database may destroy a match */
-}
-
 void
 libwacom_add_match(WacomDevice *device, WacomMatch *newmatch)
 {
@@ -1313,14 +1291,6 @@ libwacom_print_stylus_description (int fd, const WacomStylus *stylus)
 	dprintf(fd, "Type=%s\n", type);
 }
 
-LIBWACOM_EXPORT void
-libwacom_stylus_destroy(WacomStylus *stylus)
-{
-	/* This function intentionally does nothing. It was accidentally
-	 * exported but never intended to be used by callers, only our
-	 * internal database may destroy a stylus */
-}
-
 WacomStylus*
 libwacom_stylus_ref(WacomStylus *stylus)
 {

libwacom/libwacomint.h

@@ -126,19 +126,6 @@ struct _WacomError {
 	char *msg;
 };
 
-/* Note: these functions accidentally became part of the ABI, do not modify */
-LIBWACOM_DEPRECATED void
-libwacom_error_set(WacomError *error, enum WacomErrorCode code, const char *msg, ...);
-LIBWACOM_DEPRECATED void
-libwacom_stylus_destroy(WacomStylus *stylus);
-LIBWACOM_DEPRECATED void
-libwacom_update_match(WacomDevice *device, const WacomMatch *match);
-LIBWACOM_DEPRECATED WacomMatch*
-libwacom_match_new(const char *name, WacomBusType bus, int vendor_id, int product_id);
-LIBWACOM_DEPRECATED
-void libwacom_match_destroy(WacomMatch *match);
-/* End of ABI */
-
 WacomDevice* libwacom_ref(WacomDevice *device);
 WacomDevice* libwacom_unref(WacomDevice *device);
 WacomStylus* libwacom_stylus_ref(WacomStylus *stylus);

test/test-deprecated.c

@@ -31,6 +31,27 @@
 
 #include "libwacom.h"
 
+/**
+ * The normal symbols are hidden now when linking against a new library.
+ * We know which version they're in though so we can remap them for this
+ * test - if we get an unresolved symbol something has gone wrong.
+ */
+asm(".symver libwacom_match_destroy,libwacom_match_destroy@LIBWACOM_0.33");
+asm(".symver libwacom_match_new,libwacom_match_new@LIBWACOM_0.33");
+asm(".symver libwacom_error_set,libwacom_error_set@LIBWACOM_0.33");
+asm(".symver libwacom_update_match,libwacom_update_match@LIBWACOM_0.33");
+asm(".symver libwacom_stylus_destroy,libwacom_stylus_destroy@LIBWACOM_0.33");
+
+/* Only generally matches the real functions, but since they're all noops
+ * anyway it doesn't matter that we only have generic pointers. The basic
+ * signatures are the same.
+ */
+extern void libwacom_match_destroy(void*);
+void* libwacom_match_new(void *, int, int, int);
+void libwacom_error_set(void *error, int, char *, ...);
+void libwacom_stylus_destroy(void *);
+void libwacom_update_match(void *, const void *);
+
 int main(void) {
     const char *syms[] = {
         "libwacom_match_destroy",
@@ -48,8 +69,16 @@ int main(void) {
 
     for (const char **s = syms; *s; s++) {
         sym = dlsym(lib, *s);
-        assert(sym != NULL);
+        assert(sym == NULL);
     }
 
+    /* These are all noops, so all we're looking for is not getting a linker
+     * error */
+    libwacom_match_destroy(NULL);
+    libwacom_match_new(NULL, 0, 0, 0);
+    libwacom_error_set(NULL, 0, NULL);
+    libwacom_stylus_destroy(NULL);
+    libwacom_update_match(NULL, NULL);
+
     return 0;
 }