Re: [dpdk-dev] [PATCH v5 02/10] buildtools: add script for updating symbols abi version

[David Marchand <david.marchand@redhat.com>]

On Thu, Oct 24, 2019 at 11:46 AM Anatoly Burakov
<anatoly.burakov@intel.com> wrote:
>
> From: Pawel Modrak <pawelx.modrak@intel.com>
>
> Add a script that automatically merges all stable ABI's under one
> ABI section with the new version, while leaving experimental
> section exactly as it is.
>
> Signed-off-by: Pawel Modrak <pawelx.modrak@intel.com>
> Signed-off-by: Anatoly Burakov <anatoly.burakov@intel.com>
> Acked-by: Bruce Richardson <bruce.richardson@intel.com>
> ---
>
> Notes:
>     v3:
>     - Add comments to regex patterns
>
>     v2:
>     - Reworked script to be pep8-compliant and more reliable
>
>  buildtools/update_version_map_abi.py | 170 +++++++++++++++++++++++++++
>  1 file changed, 170 insertions(+)
>  create mode 100755 buildtools/update_version_map_abi.py
>
> diff --git a/buildtools/update_version_map_abi.py b/buildtools/update_version_map_abi.py
> new file mode 100755
> index 0000000000..50283e6a3d
> --- /dev/null
> +++ b/buildtools/update_version_map_abi.py
> @@ -0,0 +1,170 @@
> +#!/usr/bin/env python
> +# SPDX-License-Identifier: BSD-3-Clause
> +# Copyright(c) 2019 Intel Corporation
> +
> +"""
> +A Python program to update the ABI version and function names in a DPDK
> +lib_*_version.map file. Called from the buildtools/update_abi.sh utility.
> +"""
> +
> +from __future__ import print_function
> +import argparse
> +import sys
> +import re
> +
> +
> +def __parse_map_file(f_in):
> +    # match function name, followed by semicolon, followed by EOL, optionally
> +    # with whitespace inbetween each item
> +    func_line_regex = re.compile(r"\s*"
> +                                 r"(?P<func>[a-zA-Z_0-9]+)"
> +                                 r"\s*"
> +                                 r";"
> +                                 r"\s*"
> +                                 r"$")
> +    # match section name, followed by opening bracked, followed by EOL,
> +    # optionally with whitespace inbetween each item
> +    section_begin_regex = re.compile(r"\s*"
> +                                     r"(?P<version>[a-zA-Z0-9_\.]+)"
> +                                     r"\s*"
> +                                     r"{"
> +                                     r"\s*"
> +                                     r"$")
> +    # match closing bracket, optionally followed by section name (for when we
> +    # inherit from another ABI version), followed by semicolon, followed by
> +    # EOL, optionally with whitespace inbetween each item
> +    section_end_regex = re.compile(r"\s*"
> +                                   r"}"
> +                                   r"\s*"
> +                                   r"(?P<parent>[a-zA-Z0-9_\.]+)?"
> +                                   r"\s*"
> +                                   r";"
> +                                   r"\s*"
> +                                   r"$")
> +
> +    # for stable ABI, we don't care about which version introduced which
> +    # function, we just flatten the list. there are dupes in certain files, so
> +    # use a set instead of a list
> +    stable_lines = set()
> +    # copy experimental section as is
> +    experimental_lines = []
> +    is_experimental = False
> +
> +    # gather all functions
> +    for line in f_in:
> +        # clean up the line
> +        line = line.strip('\n').strip()
> +
> +        # is this an end of section?
> +        match = section_end_regex.match(line)
> +        if match:
> +            # whatever section this was, it's not active any more
> +            is_experimental = False
> +            continue
> +
> +        # if we're in the middle of experimental section, we need to copy
> +        # the section verbatim, so just add the line
> +        if is_experimental:
> +            experimental_lines += [line]
> +            continue
> +
> +        # skip empty lines
> +        if not line:
> +            continue
> +
> +        # is this a beginning of a new section?
> +        match = section_begin_regex.match(line)
> +        if match:
> +            cur_section = match.group("version")
> +            # is it experimental?
> +            is_experimental = cur_section == "EXPERIMENTAL"
> +            continue
> +
> +        # is this a function?
> +        match = func_line_regex.match(line)
> +        if match:
> +            stable_lines.add(match.group("func"))
> +
> +    return stable_lines, experimental_lines
> +
> +
> +def __regenerate_map_file(f_out, abi_version, stable_lines,
> +                          experimental_lines):
> +    # print ABI version header
> +    print("DPDK_{} {{".format(abi_version), file=f_out)

Some libraries are entirely experimental (librte_bpf for example).

https://patchwork.dpdk.org/patch/62018/
+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 version of ``0`` to indicate they exist outside of
+:ref:`abi_versioning` , with the minor version incremented with each ABI change
+to library.

So you must create a DPDK_XX "stable" block only if the map file
contained a non empty "stable" block before.


--
David Marchand