hdf5/debian

HDF5 for Debian, note for the mantainers
----------------------------------------

The Debian version of HDF5 is created starting from the official tarball and
adding some required patches managed by quilt. More information about quilt
use are available in /usr/share/doc/quilt/README.Debian and its documentation.

Note that starting from 1.8 HDF Group is not more providing a tarball of the
library documentation. The documentation in html format is now taken by
the HDF Group svn repository:

svn export https://svn.hdfgroup.uiuc.edu/hdf5doc/branches/hdf5_1_8_4/html

This is taken care by uscan companion script debian/orig-tar.sh.

About symbols files
-------------------
To update the symbols files on new upstream releases:
0- Rename and update the symbols files with the new sonames. This can be
   done with the script debian/update-symbols-files-soname
1- Build the package for the new release
2- Patch the symbols files from the dpkg-gensymbols output in the build log
   $ patch -p0 <path_to_build_log
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
5- Goto (2) if need be

About version scripts (debian/map_*.ver)
----------------------------------------
Their purpose is to be able to link serial and mpi flavors of libhdf5
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:
<http://bzed.de/scratchpad/soname-libtool.txt>

[Old note - for the record]
> About versioning style. In very recent times (since 1.8 series) HDF Group
> introduced a libtool SONAME versioning in the library with major/minor releases.
> Unfortunately, past experieces showed that API retention has been sometimes
> violated in the past, so current packages use a defensive approach by considering
> each release as not back-compatible. This is also motivated by the presence of
> of C++ and Fortran bindings as well as multiple MPI editions, which could imply 
> ABI breakages even for minor releases. Be defensive is more safe, definitively

Looking at the 1.8.x releases, it seems that upstream doesn't apply the
libtool versioning strategy. Instead they use it the major.medium.minor way
where:
* medium=0
* minor++ on release
* major++, minor=0 on API breaks

Considering applying this piece of advice from Julien Cristau:
> J'aurais tendance à suggérer d'utiliser le switch -version-number de
> libtool plutôt que -version-info.  Ça prend directement comme argument
> major:minor:micro, donc on se perd pas dans des calculs à la con.

Manpages
--------
$ help2man -n "helper script to compile HDF5 Fortran applications" --version-string="h5pfc (hdf5 1.8.12)" -h -help -N h5pfc >debian/man/h5pfc.1
$ help2man -n "helper script to compile HDF5 C applications" --version-string="h5pcc (hdf5 1.8.12)" -h -help -N h5pcc >debian/man/h5pcc.1
$ help2man -n "debugs an existing HDF5 file at a low level" --version-string="h5debug (hdf5 1.8.12)" -N 'bash -c "h5debug 2>&1"' >debian/man/h5debug.1

TO-DO
-----
* common manpage for h5*{c,f}c
* patch libtool usage to use -version-number instead of -version-info'?
* propose to upstream to use a separate libtool version for each language
  (C, C++, Fortran)?

 -- Francesco Paolo Lovergine <frankie@debian.org> Mon Jan 25 06:00:00 CET 2010
 -- Gilles Filippini <pini@debian.org>  Mon, 22 Dec 2014 01:50:39 +0100