libdpkg: Require users to define LIBDPKG_VOLATILE_API

The exposed API is not yet finished, make the users explicitly
acknowledge this fact by requiring them to define this preprocessor
symbol.

configure.ac

@@ -125,6 +125,7 @@ DPKG_CHECK_COMPAT_FUNCS([getopt getopt_long obstack_free \
                          scandir alphasort unsetenv])
 AC_CHECK_FUNCS([strtoul isascii bcopy memcpy lchown setsid getdtablesize])
 
+AC_DEFINE(LIBDPKG_VOLATILE_API, 1, [Acknowledge the volatility of the API.])
 DPKG_COMPILER_WARNINGS
 DPKG_COMPILER_OPTIMISATIONS
 DPKG_LINKER_OPTIMISATIONS

debian/changelog

@@ -126,6 +126,8 @@ dpkg (1.15.6) UNRELEASED; urgency=low
     way pkg.m4 is handling it now. Closes: #551118
   * Dynamically link against all external libraries. This includes libbz2
     and zlib for dpkg-deb and and libselinux for dpkg on GNU/Linux.
+  * Mark the libdpkg.a API as volatile and require any possible users to set
+    LIBDPKG_VOLATILE_API to acknowledge that fact.
 
   [ Modestas Vainius ]
   * Implement symbol patterns (Closes: #563752). From now on, it is possible to

doc/README.api

@@ -2,6 +2,17 @@ This is an (incomplete) list of currently provided APIs by dpkg, and
 their supported status.
 
 
+What: libdpkg.a (C static library)
+Status: volatile
+Description:
+ The API provided by this library is highly volatile, still in the process
+ of being cleaned up. It's only supposed to be used internally by dpkg for
+ now. Header files, functions, variables and types might get renamed,
+ removed or change semantics. If you still have a need to use it, which
+ you'd be doing anyway, say by locally building dpkg to get the library,
+ then define the C preprocessor macro LIBDPKG_VOLATILE_API in your build
+ to acknowledge that fact.
+
 What: Dpkg (perl modules)
 Status: testing
 Description:

lib/dpkg/macros.h

@@ -21,6 +21,10 @@
 #ifndef LIBDPKG_MACROS_H
 #define LIBDPKG_MACROS_H
 
+#ifndef LIBDPKG_VOLATILE_API
+#error "The libdpkg API is to be considered volatile, please read 'README.api'."
+#endif
+
 /* Language definitions. */
 
 #if HAVE_C_ATTRIBUTE