Re: [dpdk-dev] [PATCH v3 1/3] build: remove special versioning for non stable libraries

["Kinsella, Ray" <mdr@ashroe.eu>]

On 26/06/2020 09:16, David Marchand wrote:
> Having a special versioning for experimental/internal libraries put a
> additional maintenance cost while this status is already announced in
> MAINTAINERS and the library headers/documentation.
> Following discussions and vote at 05/20 TB meeting [1], use a single
> versioning for all libraries in DPDK.
> 
> Note: for the ABI check, an exception [2] had been added when tweaking
> this special versioning [3].
> Prefer explicit libabigail rules (which will be dropped in 20.11).
> 
> 1: https://mails.dpdk.org/archives/dev/2020-May/168450.html
> 2: https://git.dpdk.org/dpdk/commit/?id=23d7ad5db41c
> 3: https://git.dpdk.org/dpdk/commit/?id=ec2b8cd7ed69
> 
> Signed-off-by: David Marchand <david.marchand@redhat.com>
> ---
> Changes since v2:
> - added exceptions for librte_graph and librte_node missed post 20.05,
> 
> Changes since v1:
> - removed mention of special handling in ABI docs,
> 
> ---
>  buildtools/meson.build                     |  3 ---
>  config/meson.build                         | 16 +++++-------
>  devtools/check-abi.sh                      |  5 ----
>  devtools/libabigail.abignore               | 29 ++++++++++++++++++++--
>  doc/guides/contributing/abi_policy.rst     |  6 +----
>  doc/guides/contributing/abi_versioning.rst |  3 +--
>  drivers/meson.build                        | 17 +------------
>  lib/meson.build                            | 16 +-----------
>  mk/rte.lib.mk                              |  5 ----
>  9 files changed, 37 insertions(+), 63 deletions(-)
> 
> diff --git a/buildtools/meson.build b/buildtools/meson.build
> index d5f8291beb..79703b6f93 100644
> --- a/buildtools/meson.build
> +++ b/buildtools/meson.build
> @@ -18,6 +18,3 @@ else
>  endif
>  map_to_def_cmd = py3 + files('map_to_def.py')
>  sphinx_wrapper = py3 + files('call-sphinx-build.py')
> -
> -# stable ABI always starts with "DPDK_"
> -is_stable_cmd = [find_program('grep', 'findstr'), '^DPDK_']
> diff --git a/config/meson.build b/config/meson.build
> index 351e268c1f..d6d3f5271d 100644
> --- a/config/meson.build
> +++ b/config/meson.build
> @@ -25,18 +25,14 @@ major_version = '@0@.@1@'.format(pver.get(0), pver.get(1))
>  abi_version = run_command(find_program('cat', 'more'),
>  	abi_version_file).stdout().strip()
>  
> -# Regular libraries have the abi_version as the filename extension
> +# Libraries have the abi_version as the filename extension
>  # and have the soname be all but the final part of the abi_version.
> -# Experimental libraries have soname with '0.major'
> -# and the filename suffix as 0.majorminor versions,
> -# e.g. v20.1 => librte_stable.so.20.1, librte_experimental.so.0.201
> -#    sonames => librte_stable.so.20, librte_experimental.so.0.20
> -# e.g. v20.0.1 => librte_stable.so.20.0.1, librte_experimental.so.0.2001
> -#      sonames => librte_stable.so.20.0, librte_experimental.so.0.200
> +# e.g. v20.1 => librte_foo.so.20.1
> +#    sonames => librte_foo.so.20
> +# e.g. v20.0.1 => librte_foo.so.20.0.1
> +#      sonames => librte_foo.so.20.0
>  abi_va = abi_version.split('.')
> -stable_so_version = abi_va.length() == 2 ? abi_va[0] : abi_va[0] + '.' + abi_va[1]
> -experimental_abi_version = '0.' + abi_va[0] + abi_va[1] + '.' + abi_va[2]
> -experimental_so_version = experimental_abi_version
> +so_version = abi_va.length() == 2 ? abi_va[0] : abi_va[0] + '.' + abi_va[1]
>  
>  # extract all version information into the build configuration
>  dpdk_conf.set('RTE_VER_YEAR', pver.get(0).to_int())
> diff --git a/devtools/check-abi.sh b/devtools/check-abi.sh
> index dd9120e69e..e17fedbd9f 100755
> --- a/devtools/check-abi.sh
> +++ b/devtools/check-abi.sh
> @@ -44,11 +44,6 @@ for dump in $(find $refdir -name "*.dump"); do
>  		echo "Skipped glue library $name."
>  		continue
>  	fi
> -	# skip experimental libraries, with a sover starting with 0.
> -	if grep -qE "\<soname='[^']*\.so\.0\.[^']*'" $dump; then
> -		echo "Skipped experimental library $name."
> -		continue
> -	fi
>  	dump2=$(find $newdir -name $name)
>  	if [ -z "$dump2" ] || [ ! -e "$dump2" ]; then
>  		echo "Error: can't find $name in $newdir"
> diff --git a/devtools/libabigail.abignore b/devtools/libabigail.abignore
> index becbf842a5..0133f757d0 100644
> --- a/devtools/libabigail.abignore
> +++ b/devtools/libabigail.abignore
> @@ -50,9 +50,9 @@
>          name = rte_crypto_aead_algorithm_strings
>  
>  ;;;;;;;;;;;;;;;;;;;;;;
> -; Temporary exceptions for new __rte_internal marking till DPDK 20.11
> +; Temporary exceptions till DPDK 20.11
>  ;;;;;;;;;;;;;;;;;;;;;;
> -; Ignore moving OCTEONTX2 stable functions to INTERNAL tag
> +; Ignore moving OCTEONTX2 stable functions to INTERNAL
>  [suppress_file]
>  	file_name_regexp = ^librte_common_octeontx2\.
>  [suppress_file]
> @@ -77,3 +77,28 @@
>          name = rte_dpaa2_mbuf_alloc_bulk
>  [suppress_function]
>          name_regexp = ^dpaa2?_.*tach$
> +; Ignore soname changes for experimental libraries
> +[suppress_file]
> +	file_name_regexp = ^librte_bbdev\.
> +[suppress_file]
> +	file_name_regexp = ^librte_bpf\.
> +[suppress_file]
> +	file_name_regexp = ^librte_compressdev\.
> +[suppress_file]
> +	file_name_regexp = ^librte_fib\.
> +[suppress_file]
> +	file_name_regexp = ^librte_flow_classify\.
> +[suppress_file]
> +	file_name_regexp = ^librte_graph\.
> +[suppress_file]
> +	file_name_regexp = ^librte_ipsec\.
> +[suppress_file]
> +	file_name_regexp = ^librte_node\.
> +[suppress_file]
> +	file_name_regexp = ^librte_rcu\.
> +[suppress_file]
> +	file_name_regexp = ^librte_rib\.
> +[suppress_file]
> +	file_name_regexp = ^librte_telemetry\.
> +[suppress_file]
> +	file_name_regexp = ^librte_stack\.

Can't help feeling on this, that are swapping one headache for another. 
We are adding the cost of maintaining a bloated libabigail.abignore.

I still maintain, that if we marked libraries as "experimental" in the filename.
It serve both as obvious reminder, and simpifies this maintenance - no bloated libabigail.abiignore. 

I agree that there is no need for special versioning. 

> diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
> index ee17ccb200..1b2fa27865 100644
> --- a/doc/guides/contributing/abi_policy.rst
> +++ b/doc/guides/contributing/abi_policy.rst
> @@ -28,7 +28,6 @@ General Guidelines
>     once approved these will form part of the next ABI version.
>  #. Libraries or APIs marked as :ref:`experimental <experimental_apis>` may
>     change without constraint, as they are not considered part of an ABI version.
> -   Experimental libraries have the major ABI version ``0``.
>  #. Updates to the :ref:`minimum hardware requirements <hw_rqmts>`, which drop
>     support for hardware which was previously supported, should be treated as an
>     ABI change.
> @@ -331,7 +330,4 @@ Libraries
>  ~~~~~~~~~
>  
>  Libraries marked as ``experimental`` are entirely not considered part of an ABI
> -version, and may change without warning at any time. Experimental libraries
> -always have a major ABI version of ``0`` to indicate they exist outside of
> -:ref:`abi_versioning` , with the minor version incremented with each ABI change
> -to library.
> +version, and may change without warning at any time.
> diff --git a/doc/guides/contributing/abi_versioning.rst b/doc/guides/contributing/abi_versioning.rst
> index e96fde340f..31a9205572 100644
> --- a/doc/guides/contributing/abi_versioning.rst
> +++ b/doc/guides/contributing/abi_versioning.rst
> @@ -112,8 +112,7 @@ how this may be done.
>  
>  At the same time, the major ABI version is changed atomically across all
>  libraries by incrementing the major version in the ABI_VERSION file. This is
> -done globally for all libraries that declare a stable ABI. For libraries marked
> -as EXPERIMENTAL, their major ABI version is always set to 0.
> +done globally for all libraries.

Documentation changes are 100% OK. 
Acked-by: Ray Kinsella <mdr@ashroe.eu>

>  Minor ABI versions
>  ~~~~~~~~~~~~~~~~~~
> diff --git a/drivers/meson.build b/drivers/meson.build
> index cfb6a833c9..d1b59a4bac 100644
> --- a/drivers/meson.build
> +++ b/drivers/meson.build
> @@ -124,21 +124,6 @@ foreach class:dpdk_driver_classes
>  					output: out_filename,
>  					depends: [pmdinfogen, tmp_lib])
>  
> -			version_map = '@0@/@1@/@2@_version.map'.format(
> -					meson.current_source_dir(),
> -					drv_path, lib_name)
> -
> -			is_stable = run_command(is_stable_cmd,
> -				files(version_map)).returncode() == 0
> -
> -			if is_stable
> -				lib_version = abi_version
> -				so_version = stable_so_version
> -			else
> -				lib_version = experimental_abi_version
> -				so_version = experimental_so_version
> -			endif
> -
>  			# now build the static driver
>  			static_lib = static_library(lib_name,
>  				sources,
> @@ -183,7 +168,7 @@ foreach class:dpdk_driver_classes
>  				c_args: cflags,
>  				link_args: lk_args,
>  				link_depends: lk_deps,
> -				version: lib_version,
> +				version: abi_version,
>  				soversion: so_version,
>  				install: true,
>  				install_dir: driver_install_path)
> diff --git a/lib/meson.build b/lib/meson.build
> index d190d84eff..d646f33e07 100644
> --- a/lib/meson.build
> +++ b/lib/meson.build
> @@ -107,20 +107,6 @@ foreach l:libraries
>  				cflags += '-DRTE_USE_FUNCTION_VERSIONING'
>  			endif
>  
> -			version_map = '@0@/@1@/rte_@2@_version.map'.format(
> -					meson.current_source_dir(), dir_name, name)
> -
> -			is_stable = run_command(is_stable_cmd,
> -					files(version_map)).returncode() == 0
> -
> -			if is_stable
> -				lib_version = abi_version
> -				so_version = stable_so_version
> -			else
> -				lib_version = experimental_abi_version
> -				so_version = experimental_so_version
> -			endif
> -
>  			# first build static lib
>  			static_lib = static_library(libname,
>  					sources,
> @@ -179,7 +165,7 @@ foreach l:libraries
>  					include_directories: includes,
>  					link_args: lk_args,
>  					link_depends: lk_deps,
> -					version: lib_version,
> +					version: abi_version,
>  					soversion: so_version,
>  					install: true)
>  			shared_dep = declare_dependency(link_with: shared_lib,
> diff --git a/mk/rte.lib.mk b/mk/rte.lib.mk
> index 682b590dba..229ae16814 100644
> --- a/mk/rte.lib.mk
> +++ b/mk/rte.lib.mk
> @@ -13,11 +13,6 @@ VPATH += $(SRCDIR)
>  
>  LIBABIVER ?= $(shell cat $(RTE_SRCDIR)/ABI_VERSION)
>  SOVER := $(basename $(LIBABIVER))
> -ifeq ($(shell grep -s "^DPDK_" $(SRCDIR)/$(EXPORT_MAP)),)
> -# EXPERIMENTAL ABI is versioned as 0.major+minor, e.g. 0.201 for 20.1 ABI
> -LIBABIVER := 0.$(shell echo $(LIBABIVER) | awk 'BEGIN { FS="." }; { print $$1$$2"."$$3 }')
> -SOVER := $(LIBABIVER)
> -endif
>  
>  ifeq ($(CONFIG_RTE_BUILD_SHARED_LIB),y)
>  SONAME := $(patsubst %.a,%.so.$(SOVER),$(LIB))
>