build: Add --enable-experimental-api configure option for unstable APIs

There are currently no unstable APIs, but some will be added in
following commits. They will be built and exposed in the libostree
global symbol list iff configured with --enable-experimental-api.

Distributions should not package OSTree with --enable-experimental-api.
This is designed for previewing new APIs on controlled platforms; any of
the APIs hidden behind this option may be changed or removed at any
point.

Signed-off-by: Philip Withnall <withnall@endlessm.com>

Closes: #832
Approved by: cgwalters

Makefile-libostree.am

@@ -156,7 +156,15 @@ libostree_1_la_LIBADD = libotutil.la libglnx.la libbsdiff.la libostree-kernel-ar
 libostree_1_la_LIBADD += $(bupsplitpath)
 EXTRA_libostree_1_la_DEPENDENCIES = $(top_srcdir)/src/libostree/libostree.sym
 
-EXTRA_DIST += src/libostree/libostree.sym
+EXTRA_DIST += \
+	src/libostree/libostree.sym \
+	src/libostree/libostree-experimental.sym \
+	$(NULL)
+
+if ENABLE_EXPERIMENTAL_API
+libostree_1_la_LDFLAGS += -Wl,--version-script=$(top_srcdir)/src/libostree/libostree-experimental.sym
+EXTRA_libostree_1_la_DEPENDENCIES += $(top_srcdir)/src/libostree/libostree-experimental.sym
+endif
 
 if USE_LIBARCHIVE
 libostree_1_la_CFLAGS += $(OT_DEP_LIBARCHIVE_CFLAGS)

Makefile-tests.am

@@ -34,6 +34,7 @@ TESTS_ENVIRONMENT += OT_TESTS_DEBUG=1 \
 	GI_TYPELIB_PATH=$$(cd $(top_builddir) && pwd)$${GI_TYPELIB_PATH:+:$$GI_TYPELIB_PATH} \
 	LD_LIBRARY_PATH=$$(cd $(top_builddir)/.libs && pwd)$${LD_LIBRARY_PATH:+:$${LD_LIBRARY_PATH}} \
 	PATH=$$(cd $(top_builddir)/tests && pwd):$${PATH} \
+	OSTREE_FEATURES="$(OSTREE_FEATURES)" \
 	$(NULL)
 if BUILDOPT_ASAN
 TESTS_ENVIRONMENT += OT_SKIP_READDIR_RAND=1 G_SLICE=always-malloc

apidoc/Makefile.am

@@ -120,6 +120,7 @@ include $(top_srcdir)/gtk-doc.make
 EXTRA_DIST += \
 	version.xml \
 	ostree-sections.txt \
+	ostree-experimental-sections.txt \
 	$(NULL)
 
 -include $(top_srcdir)/git.mk

configure.ac

@@ -429,6 +429,22 @@ AS_IF([test "x$found_introspection" = xyes && test x$using_asan != xyes], [
 ], [have_gjs=no])
 AM_CONDITIONAL(BUILDOPT_GJS, test x$have_gjs = xyes)
 
+# Do we enable building experimental (non-stable) API?
+# The OSTREE_ENABLE_EXPERIMENTAL_API #define is used internally and in public
+# headers, so any consumer of libostree who wants to use experimental API must
+#    #define OSTREE_ENABLE_EXPERIMENTAL_API 1
+# before including libostree headers. This means the name in the AC_DEFINE below
+# is public API.
+AC_ARG_ENABLE([experimental-api],
+  [AS_HELP_STRING([--enable-experimental-api],
+                  [Enable unstable experimental API in libostree [default=no]])],,
+  [enable_experimental_api=no])
+AS_IF([test x$enable_experimental_api = xyes],
+  [AC_DEFINE([OSTREE_ENABLE_EXPERIMENTAL_API],[1],[Define if experimental API should be enabled])
+   OSTREE_FEATURES="$OSTREE_FEATURES experimental"]
+)
+AM_CONDITIONAL([ENABLE_EXPERIMENTAL_API],[test x$enable_experimental_api = xyes])
+
 AC_CONFIG_FILES([
 Makefile
 apidoc/Makefile
@@ -461,7 +477,8 @@ echo "
     gjs-based tests:                              $have_gjs
     dracut:                                       $with_dracut
     mkinitcpio:                                   $with_mkinitcpio
-    Static compiler for ostree-prepare-root:      $with_static_compiler"
+    Static compiler for ostree-prepare-root:      $with_static_compiler
+    Experimental API                              $enable_experimental_api"
 AS_IF([test x$with_builtin_grub2_mkconfig = xyes], [
     echo "    builtin grub2-mkconfig (instead of system):   $with_builtin_grub2_mkconfig"
 ], [

src/libostree/libostree-experimental.sym

@@ -0,0 +1,32 @@
+/*
+ * Copyright © 2017 Endless Mobile, Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ * Boston, MA 02111-1307, USA.
+ *
+ * Authors:
+ *  - Philip Withnall <withnall@endlessm.com>
+ */
+
+/* Symbols in this file are added to the build if OSTree is configured with
+ * --enable-experimental-api. They are not stable or officially supported, and
+ * might disappear or change in future releases. */
+
+/*
+LIBOSTREE_2017.6_EXPERIMENTAL {
+global:
+  some_symbol;
+} LIBOSTREE_2017.6;
+*/

tests/test-symbols.sh

@@ -21,9 +21,17 @@ set -euo pipefail
 
 echo '1..2'
 
+if echo "$OSTREE_FEATURES" | grep --quiet --no-messages "experimental"; then
+  experimental_sym="${G_TEST_SRCDIR}/src/libostree/libostree-experimental.sym"
+  experimental_sections="${G_TEST_SRCDIR}/apidoc/ostree-experimental-sections.txt"
+else
+  experimental_sym=""
+  experimental_sections=""
+fi
+
 echo "Verifying all expected symbols are actually exported..."
-grep ' ostree_[A-Za-z0-9_]*;' ${G_TEST_SRCDIR}/src/libostree/libostree.sym | sed -e 's,^ *\([A-Za-z0-9_]*\);,\1,' | sort -u > expected-symbols.txt
+grep --no-filename ' ostree_[A-Za-z0-9_]*;' ${G_TEST_SRCDIR}/src/libostree/libostree.sym $experimental_sym | sed -e 's,^ *\([A-Za-z0-9_]*\);,\1,' | sort -u > expected-symbols.txt
-eu-readelf -a ${G_TEST_BUILDDIR}/.libs/libostree-1.so | grep 'FUNC.*GLOBAL.*DEFAULT.*@@LIBOSTREE_' | sed -e 's,^.* \(ostree_[A-Za-z0-9_]*\)@@LIBOSTREE_[0-9_.]*,\1,' |sort -u > found-symbols.txt
+eu-readelf -a ${G_TEST_BUILDDIR}/.libs/libostree-1.so | grep 'FUNC.*GLOBAL.*DEFAULT.*@@LIBOSTREE_' | sed -e 's,^.* \(ostree_[A-Za-z0-9_]*\)@@LIBOSTREE_[0-9A-Z_.]*,\1,' |sort -u > found-symbols.txt
 diff -u expected-symbols.txt found-symbols.txt
 echo "ok exports"
 
@@ -31,7 +39,7 @@ echo "ok exports"
 grep -E -v '(ostree_cmd__private__)|(ostree_fetcher_config_flags_get_type)' found-symbols.txt > expected-documented.txt
 
 echo "Verifying all public symbols are documented:"
-grep '^ostree_' ${G_TEST_SRCDIR}/apidoc/ostree-sections.txt |sort -u > found-documented.txt
+grep '^ostree_' ${G_TEST_SRCDIR}/apidoc/ostree-sections.txt $experimental_sections |sort -u > found-documented.txt
 diff -u expected-documented.txt found-documented.txt
 
 echo 'ok documented symbols'