mirror of https://gitee.com/openkylin/hdf5.git
102 lines
4.6 KiB
Plaintext
102 lines
4.6 KiB
Plaintext
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
|