From c9244b1bb2152954ecadb27f9285ae51d1055d6d Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Mon, 1 May 2017 10:59:33 +0100 Subject: [PATCH] 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 Closes: #832 Approved by: cgwalters --- Makefile-libostree.am | 10 +++++++- Makefile-tests.am | 1 + apidoc/Makefile.am | 1 + apidoc/ostree-experimental-sections.txt | 0 configure.ac | 19 +++++++++++++- src/libostree/libostree-experimental.sym | 32 ++++++++++++++++++++++++ tests/test-symbols.sh | 14 ++++++++--- 7 files changed, 72 insertions(+), 5 deletions(-) create mode 100644 apidoc/ostree-experimental-sections.txt create mode 100644 src/libostree/libostree-experimental.sym diff --git a/Makefile-libostree.am b/Makefile-libostree.am index 0a114884..8d44b61c 100644 --- a/Makefile-libostree.am +++ b/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) diff --git a/Makefile-tests.am b/Makefile-tests.am index ab7750d2..14e30b46 100644 --- a/Makefile-tests.am +++ b/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 diff --git a/apidoc/Makefile.am b/apidoc/Makefile.am index 730a4c33..f3405fb0 100644 --- a/apidoc/Makefile.am +++ b/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 diff --git a/apidoc/ostree-experimental-sections.txt b/apidoc/ostree-experimental-sections.txt new file mode 100644 index 00000000..e69de29b diff --git a/configure.ac b/configure.ac index dbcc99ea..6acd0b3c 100644 --- a/configure.ac +++ b/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" ], [ diff --git a/src/libostree/libostree-experimental.sym b/src/libostree/libostree-experimental.sym new file mode 100644 index 00000000..7ca23a15 --- /dev/null +++ b/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 + */ + +/* 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; +*/ diff --git a/tests/test-symbols.sh b/tests/test-symbols.sh index 55157c07..3ee018b0 100755 --- a/tests/test-symbols.sh +++ b/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 -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 +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-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'