From 4c973b204df272e62c3b484d436a7ae87bb4fe70 Mon Sep 17 00:00:00 2001 From: Raphael Hertzog Date: Mon, 13 Aug 2007 18:33:47 +0200 Subject: [PATCH] Updated dpkg-gensymbols's man page with lots of information Explain the new include mechanism and in which cases it can be useful. Also explain the need to keep the symbols file up-to-date. Include recommendations to verify that upstream changes the library in sane ways. This probably needs to be expanded, but probably in an external non-dpkg related document that we could point to. --- man/dpkg-gensymbols.1 | 65 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) diff --git a/man/dpkg-gensymbols.1 b/man/dpkg-gensymbols.1 index 7a76f1b4..8bd39979 100644 --- a/man/dpkg-gensymbols.1 +++ b/man/dpkg-gensymbols.1 @@ -39,6 +39,65 @@ one, \fBdpkg\-gensymbols\fR will print a diff between the two versions. Furthermore if the difference are too significant, it will even fail (you can customize how much difference you can tolerate, see the \fB\-c\fR option). +.SH MAINTAINING SYMBOLS FILES +The symbols files are really useful only if they reflect the evolution of +the package through several releases. Thus the maintainer has to update +them every time that a new symbol is added so that its associated minimal +version matches reality. To do this properly he can use the diffs contained +in the build logs. In most cases, the diff can be directly applied to his +debian/\fIpackage\fR.symbols file. +.P +Before applying any patch to the symbols file, the maintainer should +double-check that it's sane. Public symbols are not supposed to disappear, +so the patch should ideally only add new lines. +.SS Using includes +.P +When the set of exported symbols differ between architectures, it's no +more possible to use a common symbols file. Using one file per +architecture works, but it can also lead to duplication of information. +In those cases, you can factorize the common part in some external file +and include that file in your \fIpackage\fR.symbols.\fIarch\fR file by +using an include directive like this: +.PP +#include "\fIpackages\fR.symbols.common" +.P +The symbols files are read line by line, and include directives +are processed as soon as they are encountered. This means that +the content of the included file can override any content that appeared +before the include directive and that any content after the +directive can override anything contained in the included file. +.P +An included file must be a valid symbols file on its own. Thus you have +to repeat the header line containing the SONAME of the library and the +dependency template. Remember that those lines might override the header +defined previously in the main symbols file. Thus the recommended way to +handle architecture specific information is to put include directives +directly at the beginning of the symbols file: +.PP +#include "libsomething1.symbols.common" +.br +libsomething.so.1 libsomething1 #MINVER# + arch_specific_symbol@Base 1.0 +.SS Good library management +.P +A well-maintained library has the following features: +.IP \(bu 4 +its API is stable (public symbols are never dropped, only new public +symbols are added) and changes in incompatible ways only when the SONAME +changes; +.IP \(bu 4 +ideally, it uses symbol versioning to achieve ABI stability despite +internal changes and API extension; +.IP \(bu 4 +it doesn't export private symbols. +.P +While maintaining the symbols file, it's easy to notice appearance and +disappearance of symbols. But it's more difficult to catch incompatible +API and ABI change. Thus the maintainer should read thoroughly the +upstream changelog looking for cases where the rules of good library +management have been broken. If potential problems are discovered, +the upstream author should be notified as an upstream fix is always better +than a Debian specific work-around. .SH OPTIONS .TP .BI \-P package-build-dir @@ -89,6 +148,12 @@ Show the usage message and exit. Show the version and exit. . .SH "SEE ALSO" +.BR http://people.redhat.com/drepper/symbol-versioning +.br +.BR http://people.redhat.com/drepper/goodpractice.pdf +.br +.BR http://people.redhat.com/drepper/dsohowto.pdf +.br .BR deb\-symbols (5), .BR dpkg\-shlibdeps (1). . -- 2.39.5