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.

No more html docs after release 1.10.2. Quoting upstream:
> The latest documentation is on the support portal only, which is freely
> available. However, it's not easily downloadable.
> We are no longer updating the User's Guide/Reference Manual in the hdf5doc
> repo, and there is now only one version of the documentation. See the
> history at the end of an API to determine when it was introduced.

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 complicated:
* 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.

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

 -- Francesco Paolo Lovergine <frankie@debian.org> Mon Jan 25 06:00:00 CET 2010
 -- Gilles Filippini <pini@debian.org>  Wed, 10 Apr 2019 13:19:06 +0200
