unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

dpkg-gensymbols(1)              dpkg utilities              dpkg-gensymbols(1)



NAME
       dpkg-gensymbols  -  generate  symbols  files (shared library dependency
       information)

SYNOPSIS
       dpkg-gensymbols [options]

DESCRIPTION
       dpkg-gensymbols scans a temporary build tree  (debian/tmp  by  default)
       looking for libraries and generate a symbols file describing them. This
       file, if non-empty, is then installed in the DEBIAN subdirectory of the
       build  tree  so  that it ends up included in the control information of
       the package.

       When generating those files, it uses as input some symbols  files  pro-
       vided  by the maintainer. It looks for the following files (and use the
       first that is found):

       o   debian/package.symbols.arch

       o   debian/symbols.arch

       o   debian/package.symbols

       o   debian/symbols

       The main interest of those files is  to  provide  the  minimal  version
       associated  to each symbol provided by the libraries. Usually it corre-
       sponds 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 dpkg-gensymbols helps him.

       When the generated symbols files differ from  the  maintainer  supplied
       one,  dpkg-gensymbols will print a diff between the two versions.  Fur-
       thermore if the difference are too significant, it will even fail  (you
       can customize how much difference you can tolerate, see the -c option).

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 associ-
       ated minimal version matches reality. To do this properly  he  can  use
       the  diffs contained in the build logs. In most cases, the diff applies
       directly to his debian/package.symbols file. That said, further  tweaks
       are  usually  needed:  it's  recommended for example to drop the Debian
       revision from the minimal version so that backports with a  lower  ver-
       sion  number  but the same upstream version still satisfy the generated
       dependencies.  If the Debian revision can't be dropped because the sym-
       bol  really  got  added  by the Debian specific change, then one should
       suffix the version with "~".

       Before applying any patch to the symbols file,  the  maintainer  should
       double-check  that it's sane. Public symbols are not supposed to disap-
       pear, so the patch should ideally only add new lines.

   Using includes
       When the set of exported symbols differ between architectures, it's  no
       more  possible  to use a common symbols file. Using one file per archi-
       tecture 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 package.symbols.arch  file  by  using  an
       include directive like this:

       #include "packages.symbols.common"

       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.

       An  included  file  can repeat the header line containing the SONAME of
       the library. In that case, it  overrides  any  header  line  previously
       read.  However, in general it's best to avoid duplicating header lines.
       One way to do it is the following:

       #include "libsomething1.symbols.common"
        arch_specific_symbol@Base 1.0

   Using wildcards with versioned symbols
       Well maintained libraries have versioned  symbols  where  each  version
       corresponds  to  the  upstream  version  where the symbol got added. If
       that's the case, it's possible to write a symbols  file  with  wildcard
       entries  like  "*@GLIBC_2.0"  that would match any symbol associated to
       the version GLIBC_2.0. It's still possible to include specific  symbols
       in  the file, they'll take precedence over any matching wildcard entry.
       An example:

       libc.so.6 libc6 #MINVER#
        *@GLIBC_2.0 2.0
        [...]
        *@GLIBC_2.7 2.7
        accessATGLIBC_2.0 2.2

       The symbol accessATGLIBC_2.0 will lead to a minimal dependency on  libc6
       version  2.2  despite  the  wildcard entry *@GLIBC_2.0 which associates
       symbols versioned as GLIBC_2.0 with the minimal version 2.0.

       Note that using wildcards means that dpkg-gensymbols  can't  check  for
       symbols  that  might have disappeared and can't generate a diff between
       the maintainer-supplied symbols file  and  the  generated  one  in  the
       binary package.

   Good library management
       A well-maintained library has the following features:

       o   its  API is stable (public symbols are never dropped, only new pub-
           lic symbols are added) and changes in incompatible ways  only  when
           the SONAME changes;

       o   ideally, it uses symbol versioning to achieve ABI stability despite
           internal changes and API extension;

       o   it doesn't export private symbols.

       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.

OPTIONS
       -Ppackage-build-dir
              Scan package-build-dir instead of debian/tmp.

       -ppackage
              Define the package name. Required if more than one binary  pack-
              age is listed in debian/control (or if there's no debian/control
              file).

       -vversion
              Define the package version. Defaults to  the  version  extracted
              from  debian/changelog.  Required  if called outside of a source
              package tree.

       -elibrary-file
              Only analyze libraries explicitly listed instead of finding  all
              public  libraries.  You can use a regular expression in library-
              file to match multiple libraries with a single argument  (other-
              wise you need multiple -e).

       -Ifilename
              Use filename as reference file to generate the symbols file that
              is integrated in the package itself.

       -O     Print the generated symbols file to standard output, rather than
              being stored in the package build tree.

       -Ofilename
              Store  the  generated  symbols  file as filename. If filename 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.

       -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 dis-
              appeared. Level 4 fails if some libraries have been introduced.

              This  value  can  be  overridden  by  the  environment  variable
              DPKG_GENSYMBOLS_CHECK_LEVEL.

       -d     Enable  debug  mode.  Numerous messages are displayed to explain
              what dpkg-gensymbols does.

       -h, --help
              Show the usage message and exit.

       --version
              Show the version and exit.

SEE ALSO
       http://people.redhat.com/drepper/symbol-versioning
       http://people.redhat.com/drepper/goodpractice.pdf
       http://people.redhat.com/drepper/dsohowto.pdf
       deb-symbols(5), dpkg-shlibdeps(1).

AUTHORS
       Copyright (C) 2007 Raphal Hertzog

       This is free software; see the GNU General Public Licence version 2  or
       later for copying conditions. There is NO WARRANTY.



Debian Project                    2007-07-16                dpkg-gensymbols(1)