debian: Add dpkg's symbols file

  There are muiltiple standards of listing symbols throughout the Linux
ecosystem. For `dpkg`, a d/package.symbols file tracks symbols, and in
which version they were added in. This is then used to allow dependency
checks/resolution.

See man:dpkg-gensymbols(1) for details about the generation,
and man:dpkg-shlibdeps(1) for how the symbols file ends up being used.

This commit adds a d/libloc1.symbols file, containing the current state
of the symbols. There is now also a d/gensymbols.sh script, which
generates this symbols file. The script tries to determine what Git
tags need to be checked for changes in symbols, by looking at current
maximum version referenced in symbols file.

After checking tags, the current revision is also processed, to allow
building symbols file for a yet unreleased version (prior to tagging it).
This is to allow symbols changes to be included in a tag.

Do keep in mind, that for the workflow above, when running the script,
the d/changelog file should contain information about what version the
current revision will be released at (potentially tagged as UNRELEASED
in the d/changelog file). Otherwise, if there is no version tagged,
the `dpkg-gensymbols` tool will use the old version information,
in turn incorrectly attributing new symbols to an old version.
---
 debian/gensymbols.sh   |  50 +++++++++++++++
 debian/libloc1.symbols | 134 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 184 insertions(+)
 create mode 100755 debian/gensymbols.sh
 create mode 100644 debian/libloc1.symbols
  

Hello Valters,

Thank you very much for working on this patch. I merged it.

Best,
-Michael

> On 11 Jun 2021, at 08:51, Valters Jansons <valter.jansons@gmail.com> wrote:
> 
> There are muiltiple standards of listing symbols throughout the Linux
> ecosystem. For `dpkg`, a d/package.symbols file tracks symbols, and in
> which version they were added in. This is then used to allow dependency
> checks/resolution.
> 
> See man:dpkg-gensymbols(1) for details about the generation,
> and man:dpkg-shlibdeps(1) for how the symbols file ends up being used.
> 
> This commit adds a d/libloc1.symbols file, containing the current state
> of the symbols. There is now also a d/gensymbols.sh script, which
> generates this symbols file. The script tries to determine what Git
> tags need to be checked for changes in symbols, by looking at current
> maximum version referenced in symbols file.
> 
> After checking tags, the current revision is also processed, to allow
> building symbols file for a yet unreleased version (prior to tagging it).
> This is to allow symbols changes to be included in a tag.
> 
> Do keep in mind, that for the workflow above, when running the script,
> the d/changelog file should contain information about what version the
> current revision will be released at (potentially tagged as UNRELEASED
> in the d/changelog file). Otherwise, if there is no version tagged,
> the `dpkg-gensymbols` tool will use the old version information,
> in turn incorrectly attributing new symbols to an old version.
> ---
> debian/gensymbols.sh   |  50 +++++++++++++++
> debian/libloc1.symbols | 134 +++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 184 insertions(+)
> create mode 100755 debian/gensymbols.sh
> create mode 100644 debian/libloc1.symbols
> 
> diff --git a/debian/gensymbols.sh b/debian/gensymbols.sh
> new file mode 100755
> index 0000000..8523556
> --- /dev/null
> +++ b/debian/gensymbols.sh
> @@ -0,0 +1,50 @@
> +#!/bin/bash
> +SYMBOLS_PKG=libloc1
> +LOCAL_FILE=debian/libloc1.symbols
> +TEMP_FILE="$(mktemp --tmpdir libloc1.XXXXXX.symbols)"
> +trap "rm -f ${TEMP_FILE}" EXIT
> +
> +generate () {
> +  intltoolize --force --automake
> +  autoreconf --install --symlink
> +  ./configure CFLAGS='-g -O0' --prefix=/usr --sysconfdir=/etc --libdir=/usr/lib
> +
> +  make
> +
> +  dpkg-gensymbols -p"$SYMBOLS_PKG" -O"$TEMP_FILE" -esrc/.libs/libloc.so.*
> +  sed -i -E -e 's/( [0-9\.]+)-.+$/\1/' "$TEMP_FILE"
> +
> +  make clean
> +}
> +
> +main () {
> +  local maxver='0.0.0'
> +  if [ -f "$LOCAL_FILE" ]; then
> +    cp "$LOCAL_FILE" "$TEMP_FILE"
> +    maxver="$(grep -E '^ ' "$LOCAL_FILE" | cut -d' ' -f3 | sort -Vru | head -n1)"
> +    echo "Latest version checked: $maxver"
> +  fi
> +
> +
> +  local tag
> +  for tag in $(git tag -l --sort=version:refname)
> +  do
> +    if [ "$(echo -e "${maxver}\n${tag}" | sort -Vr | head -n1)" == "$maxver" ]; then
> +      echo "Tag $tag -- skip"
> +      continue
> +    fi
> +
> +    echo "Tag $tag -- checking"
> +    git switch --quiet --detach "$tag" || return 1
> +    generate || return 1
> +    git switch --quiet - || return 1
> +  done
> +
> +  echo "Current -- checking"
> +  generate || return 1
> +
> +  mv "$TEMP_FILE" "$LOCAL_FILE"
> +  chmod 644 "$LOCAL_FILE"
> +}
> +
> +main "$@" || exit $?
> diff --git a/debian/libloc1.symbols b/debian/libloc1.symbols
> new file mode 100644
> index 0000000..74b70b5
> --- /dev/null
> +++ b/debian/libloc1.symbols
> @@ -0,0 +1,134 @@
> +libloc.so.1 libloc1 #MINVER#
> +* Build-Depends-Package: libloc-dev
> + LIBLOC_1@LIBLOC_1 0.9.4
> + LIBLOC_PRIVATE@LIBLOC_PRIVATE 0.9.4
> + loc_as_cmp@LIBLOC_1 0.9.4
> + loc_as_get_name@LIBLOC_1 0.9.4
> + loc_as_get_number@LIBLOC_1 0.9.4
> + loc_as_list_append@LIBLOC_1 0.9.5
> + loc_as_list_clear@LIBLOC_1 0.9.5
> + loc_as_list_contains@LIBLOC_1 0.9.5
> + loc_as_list_contains_number@LIBLOC_1 0.9.5
> + loc_as_list_empty@LIBLOC_1 0.9.5
> + loc_as_list_get@LIBLOC_1 0.9.5
> + loc_as_list_new@LIBLOC_1 0.9.5
> + loc_as_list_ref@LIBLOC_1 0.9.5
> + loc_as_list_size@LIBLOC_1 0.9.5
> + loc_as_list_unref@LIBLOC_1 0.9.5
> + loc_as_new@LIBLOC_1 0.9.4
> + loc_as_ref@LIBLOC_1 0.9.4
> + loc_as_set_name@LIBLOC_1 0.9.4
> + loc_as_unref@LIBLOC_1 0.9.4
> + loc_country_cmp@LIBLOC_1 0.9.4
> + loc_country_code_is_valid@LIBLOC_1 0.9.4
> + loc_country_get_code@LIBLOC_1 0.9.4
> + loc_country_get_continent_code@LIBLOC_1 0.9.4
> + loc_country_get_name@LIBLOC_1 0.9.4
> + loc_country_list_append@LIBLOC_1 0.9.5
> + loc_country_list_clear@LIBLOC_1 0.9.5
> + loc_country_list_contains@LIBLOC_1 0.9.5
> + loc_country_list_contains_code@LIBLOC_1 0.9.5
> + loc_country_list_empty@LIBLOC_1 0.9.5
> + loc_country_list_get@LIBLOC_1 0.9.5
> + loc_country_list_new@LIBLOC_1 0.9.5
> + loc_country_list_ref@LIBLOC_1 0.9.5
> + loc_country_list_size@LIBLOC_1 0.9.5
> + loc_country_list_unref@LIBLOC_1 0.9.5
> + loc_country_new@LIBLOC_1 0.9.4
> + loc_country_ref@LIBLOC_1 0.9.4
> + loc_country_set_continent_code@LIBLOC_1 0.9.4
> + loc_country_set_name@LIBLOC_1 0.9.4
> + loc_country_unref@LIBLOC_1 0.9.4
> + loc_database_count_as@LIBLOC_1 0.9.4
> + loc_database_created_at@LIBLOC_1 0.9.4
> + loc_database_enumerator_get_asns@LIBLOC_1 0.9.5
> + loc_database_enumerator_get_countries@LIBLOC_1 0.9.5
> + loc_database_enumerator_new@LIBLOC_1 0.9.4
> + loc_database_enumerator_next_as@LIBLOC_1 0.9.4
> + loc_database_enumerator_next_country@LIBLOC_1 0.9.4
> + loc_database_enumerator_next_network@LIBLOC_1 0.9.4
> + loc_database_enumerator_ref@LIBLOC_1 0.9.4
> + loc_database_enumerator_set_asns@LIBLOC_1 0.9.5
> + loc_database_enumerator_set_countries@LIBLOC_1 0.9.5
> + loc_database_enumerator_set_family@LIBLOC_1 0.9.4
> + loc_database_enumerator_set_flag@LIBLOC_1 0.9.4
> + loc_database_enumerator_set_string@LIBLOC_1 0.9.4
> + loc_database_enumerator_unref@LIBLOC_1 0.9.4
> + loc_database_get_as@LIBLOC_1 0.9.4
> + loc_database_get_country@LIBLOC_1 0.9.4
> + loc_database_get_description@LIBLOC_1 0.9.4
> + loc_database_get_license@LIBLOC_1 0.9.4
> + loc_database_get_vendor@LIBLOC_1 0.9.4
> + loc_database_lookup@LIBLOC_1 0.9.4
> + loc_database_lookup_from_string@LIBLOC_1 0.9.4
> + loc_database_new@LIBLOC_1 0.9.4
> + loc_database_ref@LIBLOC_1 0.9.4
> + loc_database_unref@LIBLOC_1 0.9.4
> + loc_database_verify@LIBLOC_1 0.9.4
> + loc_discover_latest_version@LIBLOC_1 0.9.4
> + loc_get_log_priority@LIBLOC_1 0.9.4
> + loc_network_address_family@LIBLOC_1 0.9.4
> + loc_network_cmp@LIBLOC_1 0.9.5
> + loc_network_exclude@LIBLOC_1 0.9.5
> + loc_network_exclude_list@LIBLOC_1 0.9.5
> + loc_network_format_first_address@LIBLOC_1 0.9.4
> + loc_network_format_last_address@LIBLOC_1 0.9.4
> + loc_network_get_asn@LIBLOC_1 0.9.4
> + loc_network_get_country_code@LIBLOC_1 0.9.4
> + loc_network_get_first_address@LIBLOC_1 0.9.5
> + loc_network_get_last_address@LIBLOC_1 0.9.5
> + loc_network_has_flag@LIBLOC_1 0.9.4
> + loc_network_is_subnet@LIBLOC_1 0.9.5
> + loc_network_list_clear@LIBLOC_1 0.9.5
> + loc_network_list_contains@LIBLOC_1 0.9.5
> + loc_network_list_dump@LIBLOC_1 0.9.5
> + loc_network_list_empty@LIBLOC_1 0.9.5
> + loc_network_list_get@LIBLOC_1 0.9.5
> + loc_network_list_merge@LIBLOC_1 0.9.5
> + loc_network_list_new@LIBLOC_1 0.9.5
> + loc_network_list_pop@LIBLOC_1 0.9.5
> + loc_network_list_pop_first@LIBLOC_1 0.9.5
> + loc_network_list_push@LIBLOC_1 0.9.5
> + loc_network_list_ref@LIBLOC_1 0.9.5
> + loc_network_list_size@LIBLOC_1 0.9.5
> + loc_network_list_unref@LIBLOC_1 0.9.5
> + loc_network_match_address@LIBLOC_1 0.9.5
> + loc_network_match_asn@LIBLOC_1 0.9.4
> + loc_network_match_country_code@LIBLOC_1 0.9.4
> + loc_network_match_flag@LIBLOC_1 0.9.4
> + loc_network_new@LIBLOC_1 0.9.4
> + loc_network_new_from_string@LIBLOC_1 0.9.4
> + loc_network_overlaps@LIBLOC_1 0.9.5
> + loc_network_prefix@LIBLOC_1 0.9.5
> + loc_network_ref@LIBLOC_1 0.9.4
> + loc_network_set_asn@LIBLOC_1 0.9.4
> + loc_network_set_country_code@LIBLOC_1 0.9.4
> + loc_network_set_flag@LIBLOC_1 0.9.4
> + loc_network_str@LIBLOC_1 0.9.4
> + loc_network_subnets@LIBLOC_1 0.9.5
> + loc_network_unref@LIBLOC_1 0.9.4
> + loc_new@LIBLOC_1 0.9.4
> + loc_ref@LIBLOC_1 0.9.4
> + loc_set_log_fn@LIBLOC_1 0.9.4
> + loc_set_log_priority@LIBLOC_1 0.9.4
> + loc_stringpool_add@LIBLOC_PRIVATE 0.9.4
> + loc_stringpool_dump@LIBLOC_PRIVATE 0.9.4
> + loc_stringpool_get@LIBLOC_PRIVATE 0.9.4
> + loc_stringpool_get_size@LIBLOC_PRIVATE 0.9.4
> + loc_stringpool_new@LIBLOC_PRIVATE 0.9.4
> + loc_stringpool_ref@LIBLOC_PRIVATE 0.9.4
> + loc_stringpool_unref@LIBLOC_PRIVATE 0.9.4
> + loc_unref@LIBLOC_1 0.9.4
> + loc_writer_add_as@LIBLOC_1 0.9.4
> + loc_writer_add_country@LIBLOC_1 0.9.4
> + loc_writer_add_network@LIBLOC_1 0.9.4
> + loc_writer_get_description@LIBLOC_1 0.9.4
> + loc_writer_get_license@LIBLOC_1 0.9.4
> + loc_writer_get_vendor@LIBLOC_1 0.9.4
> + loc_writer_new@LIBLOC_1 0.9.4
> + loc_writer_ref@LIBLOC_1 0.9.4
> + loc_writer_set_description@LIBLOC_1 0.9.4
> + loc_writer_set_license@LIBLOC_1 0.9.4
> + loc_writer_set_vendor@LIBLOC_1 0.9.4
> + loc_writer_unref@LIBLOC_1 0.9.4
> + loc_writer_write@LIBLOC_1 0.9.4
> -- 
> 2.32.0
>