[hdf5] 05/08: Update debian/README.source regarding symbols tracking

[Gilles Filippini]

This is an automated email from the git hooks/post-receive script.

pini pushed a commit to branch master
in repository hdf5.

commit f155ba034e81fcdc918b006c9ef96136813db0b7
Author: Gilles Filippini <pini at debian.org>
Date:   Fri Jun 26 14:53:32 2015 +0200

    Update debian/README.source regarding symbols tracking
---
 debian/README.source | 38 +++++++++++++++++++++++++++++---------
 1 file changed, 29 insertions(+), 9 deletions(-)

diff --git a/debian/README.source b/debian/README.source
index 6cce239..1ab104a 100644
--- a/debian/README.source
+++ b/debian/README.source
@@ -16,18 +16,14 @@ This is taken care by uscan companion script debian/orig-tar.sh.
 About symbols files
 -------------------
 To update the symbols files on new upstream releases:
-1- Build the package for the new release with symbols files untouched
+1- Build the package for the new release with symbols files untouched (but
+   the soname in case it was bumped)
 2- Patch the symbols files from the dpkg-gensymbols output in the build log
    $ patch -p0 <path_to_build_log
-3- Use the debian/sort-symbols script on the symbol files to unmangle and
-   sort C++ symbols
+3- Use the debian/process-symbols-files script to unmangle and sort C++
+   symbols, and generate the version scripts (debian/map_*.ver)
 4- Rebuild the package and check that no diff are reported by dpkg-gensymbols
-
-There was a non backward-compatible change in the C++ API between releases
-1.8.11 and 1.8.12 with no soname bump. Since there is no packages in sid
-using this C++ library, we don't bother.
-
-The script debian/check-dep-on-hdf5-cpp is used to check these dependencies.
+5- Goto (2) if need be
 
 About version scripts (debian/map_*.ver)
 ----------------------------------------
@@ -37,6 +33,30 @@ into the same executable.
 I use the helper script make-version-scripts to generate them. I don't
 care about identifying local symbols for now.
 
+About C++ symbols tracking
+--------------------------
+Tracking C++ versioned symbols is complacated:
+* Firstly we need to track them under their unmangled form to be arch
+  independant.
+* Secondly I discovered after many /try fail repeat/ that dpkg-gensymbols
+  wants the verbose unmangled symbols (output from 'c++filt' command)
+  while version scripts want the non verbose ones (output from
+  'c++filt -i' command).
+* Finaly the patches generated by dpkg-gensymbols don't allow any
+  comment in the symbols files and requires a specific sorting order
+  (bug #773718).
+All these concerns are handled by three helper scripts:
+* debian/process-symbols-files
+* debian/sort-symbols
+* debian/make-version-scripts
+The entry point being debian/process-symbols-files.
+
+There was a non backward-compatible change in the C++ API between releases
+1.8.11 and 1.8.12 with no soname bump. Since there is no packages in sid
+using this C++ library, we didn't bother.
+
+The script debian/check-dep-on-hdf5-cpp is used to check these dependencies.
+
 About shared libraries versioning and SONAME
 --------------------------------------------
 Worth reading to get the picture about libtool versioning:

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-grass/hdf5.git