--- /dev/null
+.\" 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
+<library soname> <main dependency template>
+.br
+[ | <alternative dependency template> ]
+.br
+[ ... ]
+ <symbol> <mininal version>[ <id of dependency template> ]
+.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).
--- /dev/null
+.\" 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.
-.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
.
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
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.
.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.
projects / dpkg / commitdiff