mk: enable next abi preview

When a change makes really hard to keep ABI compatibility,
instead of waiting next release to break the ABI, it is smoother
to introduce the new code as a preview and disable it when packaging.
The flag RTE_NEXT_ABI must be used to "ifdef" the new code.
When the release is out, a dynamically linked application can use
the new shared libraries with the old ABI while developpers can prepare
their application for the next ABI by reading the deprecation notice
and easily testing the new code.
When starting the next release cycle, the "ifdefs" will be removed
and the ABI break will be marked by incrementing LIBABIVER. The map
files will also be updated.

The default value is enabled to be developer compliant.
The packagers must disable it as done in pkg/dpdk.spec.
When enabled, all shared library numbers are incremented by appending
a minor .1 to the old ABI number. In the next release, only impacted
libraries will have a major +1 increment.
The impacted libraries must provide an alternative map file to use
with this option.

The ABI policy is updated.

Signed-off-by: Thomas Monjalon <thomas.monjalon@6wind.com>
Acked-by: Neil Horman <nhorman@tuxdriver.com>

diff --git a/config/common_bsdapp b/config/common_bsdapp
index 1f5d1cfbd80f8eb6cfbc09e59af89f1142d2c696..dfa61a323d241609d9c015c15371b62bfd135e7e 100644 (file)
--- a/config/common_bsdapp
+++ b/config/common_bsdapp
@@ -89,6 +89,11 @@ CONFIG_RTE_BUILD_SHARED_LIB=n
 CONFIG_RTE_BUILD_COMBINE_LIBS=n
 CONFIG_RTE_LIBNAME=intel_dpdk
 
+#
+# Use newest code breaking previous ABI
+#
+CONFIG_RTE_NEXT_ABI=y
+
 #
 # Compile Environment Abstraction Layer
 #

diff --git a/config/common_linuxapp b/config/common_linuxapp
index 7a54ff8f38555f47a9d4c3a6768679a17a921578..1732b7046cea1dca4dfa17bb3148613de3fd2cc1 100644 (file)
--- a/config/common_linuxapp
+++ b/config/common_linuxapp
@@ -89,6 +89,11 @@ CONFIG_RTE_BUILD_SHARED_LIB=n
 CONFIG_RTE_BUILD_COMBINE_LIBS=n
 CONFIG_RTE_LIBNAME="intel_dpdk"
 
+#
+# Use newest code breaking previous ABI
+#
+CONFIG_RTE_NEXT_ABI=y
+
 #
 # Compile Environment Abstraction Layer
 #

diff --git a/doc/guides/guidelines/versioning.rst b/doc/guides/guidelines/versioning.rst
index ea789cbc6dbbabe336385350455133de175b0830..8a739dd72b7adb81f3c1975e61d7e06f628a59a0 100644 (file)
--- a/doc/guides/guidelines/versioning.rst
+++ b/doc/guides/guidelines/versioning.rst
@@ -55,12 +55,18 @@ being provided. The requirements for doing so are:
 #. At least 3 acknowledgments of the need to do so must be made on the
    dpdk.org mailing list.
 
+#. The changes (including an alternative map file) must be gated with
+   the ``RTE_NEXT_ABI`` option, and provided with a deprecation notice at the
+   same time.
+   It will become the default ABI in the next release.
+
 #. A full deprecation cycle, as explained above, must be made to offer
    downstream consumers sufficient warning of the change.
 
-#. The ``LIBABIVER`` variable in the makefile(s) where the ABI changes are
-   incorporated must be incremented in parallel with the ABI changes
-   themselves.
+#. At the beginning of the next release cycle, every ``RTE_NEXT_ABI``
+   conditions will be removed, the ``LIBABIVER`` variable in the makefile(s)
+   where the ABI is changed will be incremented, and the map files will
+   be updated.
 
 Note that the above process for ABI deprecation should not be undertaken
 lightly. ABI stability is extremely important for downstream consumers of the

diff --git a/mk/rte.lib.mk b/mk/rte.lib.mk
index fff62a76796d5f82db9a3d5bfa3d50b1982271da..f15de9b00de262b4f42c770f83b56a111122526d 100644 (file)
--- a/mk/rte.lib.mk
+++ b/mk/rte.lib.mk
@@ -37,11 +37,13 @@ include $(RTE_SDK)/mk/internal/rte.depdirs-pre.mk
 
 # VPATH contains at least SRCDIR
 VPATH += $(SRCDIR)
-ifeq ($(CONFIG_RTE_BUILD_SHARED_LIB),y)
 
+ifeq ($(CONFIG_RTE_BUILD_SHARED_LIB),y)
 LIB := $(patsubst %.a,%.so.$(LIBABIVER),$(LIB))
+ifeq ($(CONFIG_RTE_NEXT_ABI),y)
+LIB := $(LIB).1
+endif
 CPU_LDFLAGS += --version-script=$(SRCDIR)/$(EXPORT_MAP)
-
 endif
 
 
@@ -167,12 +169,11 @@ endif
 # install lib in $(RTE_OUTPUT)/lib
 #
 $(RTE_OUTPUT)/lib/$(LIB): $(LIB)
-       $(eval LIBSONAME := $(basename $(LIB)))
        @echo "  INSTALL-LIB $(LIB)"
        @[ -d $(RTE_OUTPUT)/lib ] || mkdir -p $(RTE_OUTPUT)/lib
        $(Q)cp -f $(LIB) $(RTE_OUTPUT)/lib
 ifeq ($(CONFIG_RTE_BUILD_SHARED_LIB),y)
-       $(Q)ln -s -f $< $(RTE_OUTPUT)/lib/$(LIBSONAME)
+       $(Q)ln -s -f $< $(basename $(basename $@))
 endif
 
 #

diff --git a/pkg/dpdk.spec b/pkg/dpdk.spec
index 5f6ec6a2d07ca396151f9afd37fa29d2a63a62ca..fb71ccc4566a1da0264cf7e473f10936ba9d1cb0 100644 (file)
--- a/pkg/dpdk.spec
+++ b/pkg/dpdk.spec
@@ -82,6 +82,7 @@ make O=%{target} T=%{target} config
 sed -ri 's,(RTE_MACHINE=).*,\1%{machine},' %{target}/.config
 sed -ri 's,(RTE_APP_TEST=).*,\1n,'         %{target}/.config
 sed -ri 's,(RTE_BUILD_SHARED_LIB=).*,\1y,' %{target}/.config
+sed -ri 's,(RTE_NEXT_ABI=).*,\1n,'         %{target}/.config
 sed -ri 's,(LIBRTE_VHOST=).*,\1y,'         %{target}/.config
 sed -ri 's,(LIBRTE_PMD_PCAP=).*,\1y,'      %{target}/.config
 sed -ri 's,(LIBRTE_PMD_XENVIRT=).*,\1y,'   %{target}/.config

diff --git a/scripts/validate-abi.sh b/scripts/validate-abi.sh
index 1747b8b3e19cdcd752e8900cc99ca08a80ba11c0..4476433ead979f5af00cbf696f062e5ccbed6168 100755 (executable)
--- a/scripts/validate-abi.sh
+++ b/scripts/validate-abi.sh
@@ -157,6 +157,7 @@ git checkout $TAG1
 # Make sure we configure SHARED libraries
 # Also turn off IGB and KNI as those require kernel headers to build
 sed -i -e"$ a\CONFIG_RTE_BUILD_SHARED_LIB=y" config/defconfig_$TARGET
+sed -i -e"$ a\CONFIG_RTE_NEXT_ABI=n" config/defconfig_$TARGET
 sed -i -e"$ a\CONFIG_RTE_EAL_IGB_UIO=n" config/defconfig_$TARGET
 sed -i -e"$ a\CONFIG_RTE_LIBRTE_KNI=n" config/defconfig_$TARGET
 
@@ -198,6 +199,7 @@ git checkout $TAG2
 # Make sure we configure SHARED libraries
 # Also turn off IGB and KNI as those require kernel headers to build
 sed -i -e"$ a\CONFIG_RTE_BUILD_SHARED_LIB=y" config/defconfig_$TARGET
+sed -i -e"$ a\CONFIG_RTE_NEXT_ABI=n" config/defconfig_$TARGET
 sed -i -e"$ a\CONFIG_RTE_EAL_IGB_UIO=n" config/defconfig_$TARGET
 sed -i -e"$ a\CONFIG_RTE_LIBRTE_KNI=n" config/defconfig_$TARGET