From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <thomas.monjalon@6wind.com>
Received: from mail-wi0-f178.google.com (mail-wi0-f178.google.com
[209.85.212.178]) by dpdk.org (Postfix) with ESMTP id 128093B5
for <dev@dpdk.org>; Wed, 8 Jul 2015 18:45:30 +0200 (CEST)
Received: by widjy10 with SMTP id jy10so222480243wid.1
for <dev@dpdk.org>; Wed, 08 Jul 2015 09:45:29 -0700 (PDT)
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=1e100.net; s=20130820;
h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to
:references;
bh=NGPcTcPUJIjFUYXkKMlwvcBau+GHgFgDj0MMrnx0ksI=;
b=GmOLFUD0tyl/nPLl2yYKa+EqM9Y2YPLPzNOzLk3qoCTRVzSHgsVnm4j+alVF0iYpTV
6Y6WMttOZ5w1FJz1JJu1crbDFhgHQXmxerkiey1kYk9CiwNjkS9nN+QBR7gqsZ71ZghF
IdxKUOZnTyWS2Re1Il1obS8cnsDeUN3Glk8TY0VBNnKNSB9BVod6vJqEvrNR4pOCz5oo
w5gIydw9WMkCjHf1TVd6H6vgMfLoIpP42ntJfYh3zPghQPF6ek4IkGsQZzh9kmZL23Gj
+2DaI2nOhmuLCAbFbPLlYed9RUxJpr2CxYm0vZB6TjJudh5tbGsLcE98ntn9htgWAr3o
ctuw==
X-Gm-Message-State: ALoCoQm19QKZ6+OgvZDnqlb8qRhBx88qIZUmkclv2lLbcOW2JzY5/Y4qqt3BgCK1VBBfHf3A3ff3
X-Received: by 10.180.188.48 with SMTP id fx16mr76082194wic.35.1436373929888;
Wed, 08 Jul 2015 09:45:29 -0700 (PDT)
Received: from localhost.localdomain (136-92-190-109.dsl.ovh.fr.
[109.190.92.136])
by smtp.gmail.com with ESMTPSA id x10sm4331270wjr.25.2015.07.08.09.45.28
(version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128);
Wed, 08 Jul 2015 09:45:29 -0700 (PDT)
From: Thomas Monjalon <thomas.monjalon@6wind.com>
To: nhorman@tuxdriver.com
Date: Wed, 8 Jul 2015 18:44:16 +0200
Message-Id: <1436373856-29468-1-git-send-email-thomas.monjalon@6wind.com>
X-Mailer: git-send-email 2.4.2
In-Reply-To: <1436367323-19968-3-git-send-email-thomas.monjalon@6wind.com>
References: <1436367323-19968-3-git-send-email-thomas.monjalon@6wind.com>
Cc: dev@dpdk.org
Subject: [dpdk-dev] [PATCH v3] mk: enable next abi preview
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: patches and discussions about DPDK <dev.dpdk.org>
List-Unsubscribe: <http://dpdk.org/ml/options/dev>,
<mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://dpdk.org/ml/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <http://dpdk.org/ml/listinfo/dev>,
<mailto:dev-request@dpdk.org?subject=subscribe>
X-List-Received-Date: Wed, 08 Jul 2015 16:45:30 -0000
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>
---
v3 change:
- fix .so symbolic link to .so.x.1
config/common_bsdapp | 5 +++++
config/common_linuxapp | 5 +++++
doc/guides/guidelines/versioning.rst | 12 +++++++++---
mk/rte.lib.mk | 9 +++++----
pkg/dpdk.spec | 1 +
scripts/validate-abi.sh | 2 ++
6 files changed, 27 insertions(+), 7 deletions(-)
diff --git a/config/common_bsdapp b/config/common_bsdapp
index 78754b2..a4e3262 100644
--- a/config/common_bsdapp
+++ b/config/common_bsdapp
@@ -90,6 +90,11 @@ 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
#
CONFIG_RTE_LIBRTE_EAL=y
diff --git a/config/common_linuxapp b/config/common_linuxapp
index f5646e0..050bf35 100644
--- a/config/common_linuxapp
+++ b/config/common_linuxapp
@@ -90,6 +90,11 @@ 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
#
CONFIG_RTE_LIBRTE_EAL=y
diff --git a/doc/guides/guidelines/versioning.rst b/doc/guides/guidelines/versioning.rst
index ea789cb..8a739dd 100644
--- 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 fff62a7..f15de9b 100644
--- 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 5f6ec6a..fb71ccc 100644
--- 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 1747b8b..4476433 100755
--- 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
--
2.4.2