From fad6a8ea7f34fb073fabae2da819063a2781ad98 Mon Sep 17 00:00:00 2001 From: Raphael Hertzog Date: Mon, 16 Jul 2007 22:47:50 +0000 Subject: [PATCH] Complete and update the manual pages for the new symbols stuff * Update dpkg-shlibdeps(1). * Create manual page dpkg-gensymbols(1) for the new command. * Create deb-symbols(5) to describe the format of the symbols file. * Updated the Makefile.am to include the new manual pages. --- man/Makefile.am | 2 + man/deb-symbols.5 | 52 +++++++++++++++++ man/dpkg-gensymbols.1 | 99 ++++++++++++++++++++++++++++++++ man/dpkg-shlibdeps.1 | 129 +++++++++++++++++++++++++++++++++++------- 4 files changed, 260 insertions(+), 22 deletions(-) create mode 100644 man/deb-symbols.5 create mode 100644 man/dpkg-gensymbols.1 diff --git a/man/Makefile.am b/man/Makefile.am index 2a35185d..8f501eb1 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -42,6 +42,7 @@ dist_man_MANS = \ deb-control.5 \ deb-shlibs.5 \ deb-substvars.5 \ + deb-symbols.5 \ deb-old.5 \ deb-override.5 \ deb.5 \ @@ -53,6 +54,7 @@ dist_man_MANS = \ dpkg-divert.8 \ dpkg-genchanges.1 \ dpkg-gencontrol.1 \ + dpkg-gensymbols.1 \ dpkg-name.1 \ dpkg-parsechangelog.1 \ dpkg-query.1 \ diff --git a/man/deb-symbols.5 b/man/deb-symbols.5 new file mode 100644 index 00000000..6dd84fa6 --- /dev/null +++ b/man/deb-symbols.5 @@ -0,0 +1,52 @@ +.\" Author: Raphael Hertzog +.TH deb\-symbols 5 "2007-07-16" "Debian Project" "dpkg utilities" +.SH NAME +deb\-symbols \- Debian's extended shared library information file +. +.SH SYNOPSIS +symbols +. +.SH DESCRIPTION +The format for an extended shared library dependency information entry +in these files is: +.PP +
+.br +[ | ] +.br +[ ... ] + [ ] +.P +The \fIlibrary soname\fR is exactly the value of the SONAME field +as exported by \fBobjdump\fR. A \fIdependency template\fR is a +dependency where \fI#MINVER#\fR is dynamically replaced either by +a version check like "(>= \fIminimal version\fR)" or by nothing (if +an unversionned dependency is deemed sufficient). +.P +Each exported \fIsymbol\fR (listed as \fIname\fR@\fIversion\fR, with +\fIversion\fR being "Base" if the library is not versioned) is associated +to a \fIminimal version\fR of its dependency template (the main dependency +template is used if \fIid of dependency template\fR is not present). The +first alternative dependency template is numbered 1, the second one 2, +etc. +.SH EXAMPLES +.SS Simple symbols file +.PP +libftp.so.3 libftp3 #MINVER# + DefaultNetbuf@Base 3.1-1-6 + FtpAccess@Base 3.1-1-6 + [...] +.SS Advanced symbols file +.PP +libGL.so.1 libgl1 +.br +| libgl1-mesa-glx #MINVER# + publicGlSymbol@Base 6.3-1 + [...] + implementationSpecificSymbol@Base 6.5.2-7 1 + [...] +.SH SEE ALSO +.BR http://wiki.debian.org/Projects/ImprovedDpkgShlibdeps +.br +.BR dpkg\-shlibdeps (1), +.BR dpkg\-gensymbols (1). diff --git a/man/dpkg-gensymbols.1 b/man/dpkg-gensymbols.1 new file mode 100644 index 00000000..3ea4e1dc --- /dev/null +++ b/man/dpkg-gensymbols.1 @@ -0,0 +1,99 @@ +.\" Author: Raphael Hertzog +.TH dpkg\-gensymbols 1 "2007-07-16" "Debian Project" "dpkg utilities" +.SH NAME +dpkg\-gensymbols \- generate symbols files (shared library dependency information) +. +.SH SYNOPSIS +.B dpkg\-gensymbols +.RI [ options ] +. +.SH DESCRIPTION +.B dpkg\-gensymbols +scans a temporary build tree (debian/tmp by default) looking for libraries +and generate a \fIsymbols\fR file describing them. This file is then +installed in the DEBIAN subdirectory of the build tree so that it ends up +included in the control information of the package. +.P +When generating those files, it uses as input some symbols files +provided by the maintainer. It looks for the following files (and use the +first that is found): +.IP \(bu 4 +debian/\fIpackage\fR.symbols.\fIarch\fR +.IP \(bu 4 +debian/symbols.\fIarch\fR +.IP \(bu 4 +debian/\fIpackage\fR.symbols +.IP \(bu 4 +debian/symbols +.P +The main interest of those files is to provide the minimal version +associated to each symbol provided by the libraries. Usually it +corresponds to the first version of that package that provided the symbol, +but it can be manually incremented by the maintainer if the ABI of the +symbol is extended without breaking backwards compatibility. It's the +responsibility of the maintainer to keep those files up-to-date and +accurate, but \fBdpkg\-gensymbols\fR helps him. +.P +When the generated symbols files differ from the maintainer supplied +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 OPTIONS +.TP +.BI \-P package-build-dir +Scan \fIpackage-build-dir\fR instead of debian/tmp. +.TP +.BI \-p package +Define the package name. Required if more than one binary package is listed in +debian/control (or if there's no debian/control file). +.TP +.BI \-v version +Define the package version. Defaults to the version extracted from +debian/changelog. Required if called outside of a source package tree. +.TP +.BI \-e library-file +Only analyze libraries explicitely listed instead of finding all public +libraries. You can use a regular expression in \fIlibrary-file\fR to match +multiple libraries with a single argument (otherwise you need multiple +\fB\-e\fR). +.TP +.B \-O +Print the generated symbols file to standard output, rather than being +stored in the package build tree. +.TP +.BI \-O filename +Store the generated symbols file as \fIfilename\fR. If \fIfilename\fR is +pre-existing, its content is used as basis for the generated symbols file. +You can use this feature to update a symbols file so that it matches a +newer upstream version of your library. +.TP +.BI \-c [0-4] +Define the checks to do when comparing the generated symbols file +with the file used as starting point. By default the level is 1. +Increasing levels do more checks and include all checks of lower levels. +Level 0 disables all checks. Level 1 fails if some symbols have +disappeared. Level 2 fails if some new symbols have been introduced. +Level 3 fails if some libraries have disappeared. Level 4 fails if some +libraries have been introduced. +.TP +.BI \-d +Enable debug mode. Numerous messages are displayed to explain what +.B dpkg\-gensymbols +does. +.TP +.BR \-h ", " \-\-help +Show the usage message and exit. +.TP +.BR \-\-version +Show the version and exit. +. +.SH "SEE ALSO" +.BR deb\-symbols (5), +.BR dpkg\-shlibdeps (1). +. +.SH AUTHORS +Copyright (C) 2007 Raphaël Hertzog +.sp +This is free software; see the GNU General Public Licence version 2 or later +for copying conditions. There is NO WARRANTY. diff --git a/man/dpkg-shlibdeps.1 b/man/dpkg-shlibdeps.1 index 143025c6..e6c3898c 100644 --- a/man/dpkg-shlibdeps.1 +++ b/man/dpkg-shlibdeps.1 @@ -1,4 +1,4 @@ -.TH dpkg\-shlibdeps 1 "2007-06-12" "Debian Project" "dpkg utilities" +.TH dpkg\-shlibdeps 1 "2007-07-16" "Debian Project" "dpkg utilities" .SH NAME dpkg\-shlibdeps \- generate shared library substvar dependencies . @@ -21,18 +21,76 @@ where is a dependency field name. Any other variables starting .I shlibs: are removed from the file. +.P .B dpkg\-shlibdeps -will read shared library dependency information from -.BR debian/shlibs.local , -.BR /etc/dpkg/shlibs.override , -the -.B shlibs -control area file of the package containing the file which -.B objdump -reports as satisfying the library dependency, or -.BR /etc/dpkg/shlibs.default . -The first match will be used. -. +has two possible sources of information to generate dependency +information. Either +.I symbols +files or +.I shlibs +files. For each binary that +.B dpkg\-shlibdeps +analyzes, it finds out the list of libraries that it's linked with. +Then, for each library, it looks up either the +.I symbols +file, or the +.I shlibs +file (if the former doesn't exist). Both files are supposed to be provided +by the library package and should thus be available as +/var/lib/dpkg/info/\fIpackage\fR.\fIsymbols\fR +or /var/lib/dpkg/info/\fIpackage\fR.\fIshlibs\fR. The package name is +identified in two steps: find the library file on the system (looking in +the same directories that \fBld.so\fR would use), then use +.BI "dpkg -S " library\-file +to lookup the package providing the library. +.SS Symbols files +Symbols files contain finer-grained dependency information by providing +the minimum dependency for each symbol that the library exports. The +script tries to find a symbols file associated to a library package +in the following places (first match is used): +.IP debian/*/DEBIAN/symbols +Shared library information generated by the current build process that also invoked +.BR dpkg\-shlibdeps . +They are generated by +.BR dpkg\-gensymbols (1). +.IP /etc/dpkg/symbols/\fIpackage\fR.symbols.\fIarch\fR +.IP /etc/dpkg/symbols/\fIpackage\fR.symbols +Per-system overriding shared library dependency information. +\fIarch\fR is the architecture of the current system (obtained by +.BR "dpkg-architecture -qDEB_HOST_ARCH" ). +.IP \fIadmindir\fR/info/\fIpackage\fR.symbols +Package-provided shared library dependency information. +Unless overriden, \fIadmindir\fR is /var/lib/dpkg. +.P +While scanning the symbols used by all binaries, +.B dpkg\-shlibdeps +remembers the (biggest) minimal version needed for each library. At the end +of the process, it is able to write out the minimal dependency for every +library used (provided that the information of the \fIsymbols\fR files are +accurate). +.SS Shlibs files +Shlibs files associate directly a library to a dependency (without looking +at the symbols). It's thus often stronger than really needed but very safe +and easy to handle. +.P +The dependencies for a library are looked up in several places. The first +file providing informations for the library of interest is used: +.IP debian/shlibs.local +Package-local overriding shared library dependency information. +.IP /etc/dpkg/shlibs.override +Per-system overriding shared library dependency information. +.IP debian/*/DEBIAN/shlibs +Shared library information generated by the current build process that also invoked +.BR dpkg\-shlibdeps . +.IP \fIadmindir\fR/info/\fIpackage\fR.shlibs +Package-provided shared library dependency information. +Unless overriden, \fIadmindir\fR is /var/lib/dpkg. +.IP /etc/dpkg/shlibs.default +Per-system default shared library dependency information. +.P +The extracted dependencies are then directly used (except if they are +filtered out because they have been identified as duplicate, or as weaker +than another dependency). .SH OPTIONS .B dpkg\-shlibdeps interprets non-option arguments as executable names, just as if they'd @@ -103,6 +161,11 @@ Write substitution variables in the default is .BR debian/substvars . .TP +.BI \-v +Enable verbose mode. Numerous messages are displayed to explain what +.B dpkg\-shlibdeps +does. +.TP .BI \-\-admindir= dir Change the location of the \fBdpkg\fR database. The default location is \fI/var/lib/dpkg\fP. @@ -113,24 +176,46 @@ Show the usage message and exit. .BR \-\-version Show the version and exit. . -.SH FILES +.SH WARNINGS +Since +.B dpkg\-shlibdeps +analyzes the set of symbols used by each binary of the generated package, +it is able to emit warnings in several cases. They inform you of things +that can be improved in the package. In most cases, those improvements +concern the upstream sources directly. By order of decreasing importance, +here are the various warnings that you can encounter: .TP -.B debian/shlibs.local -Package-local overriding shared library dependency information. +.BI symbol " sym" " used by " binary " found in none of the libraries." +The indicated symbol has not been found in the libraries linked with the +binary. The \fIbinary\fR is most likely a library and it needs to be linked +with an additional library during the build process (option \fB-l\fR\fIlibrary\fR +of the linker). .TP -.B /etc/dpkg/shlibs.override -Per-system overriding shared library dependency information. -.TP -.B /etc/dpkg/shlibs.default -Per-system default shared library dependency information. -. +.IB binary " shouldn't be linked with " library " (it uses none of its symbols)." +The \fIbinary\fR is linked to a library that it doesn't need. It's not a +problem but some small performance improvements in binary load time +can be obtained by not linking this library to this binary. + +Furthermore, in some cases, this will lead to a non-versionned dependency +on the library that could have been avoided if the binary was only linked +against the library that it really uses. The exception to this rule is +when several binaries are linked against the same set of libraries but +each binary only uses a subset of those. You will have warnings on +individual binaries, but the set of libraries needed at the package level +is the same whether you fix the binaries or not. .SH "SEE ALSO" -.BR deb\-shlibs (5). +.BR deb\-shlibs (5), +.BR deb\-symbols (5), +.BR dpkg-gensymbols (1). . .SH AUTHORS Copyright (C) 1995-1996 Ian Jackson .br Copyright (C) 2000 Wichert Akkerman +.br +Copyright (C) 2006 Frank Lichtenheld +.br +Copyright (C) 2007 Raphaël Hertzog .sp This is free software; see the GNU General Public Licence version 2 or later for copying conditions. There is NO WARRANTY. -- 2.39.5