man/deb-symbols.pod

   1 # dpkg manual page - deb-symbols(5)
   2 #
   3 # Copyright © 2007-2012 Raphaël Hertzog <hertzog@debian.org>
   4 # Copyright © 2011, 2013-2015 Guillem Jover <guillem@debian.org>
   5 #
   6 # This is free software; you can redistribute it and/or modify
   7 # it under the terms of the GNU General Public License as published by
   8 # the Free Software Foundation; either version 2 of the License, or
   9 # (at your option) any later version.
  10 #
  11 # This is distributed in the hope that it will be useful,
  12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 # GNU General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU General Public License
  17 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
  18
  19 =encoding utf8
  20
  21 =head1 NAME
  22
  23 deb-symbols - Debian's extended shared library information file
  24
  25 =head1 SYNOPSIS
  26
  27 B<DEBIAN/symbols>
  28
  29 =head1 DESCRIPTION
  30
  31 The symbol files are shipped in Debian binary packages, and its format
  32 is a subset of the template symbol files used by L<dpkg-gensymbols(1)>
  33 in Debian source packages, see L<deb-src-symbols(5)>.
  34
  35 The format for an extended shared library dependency information entry
  36 in these files is:
  37
  38 Z<>
  39  I<library-soname> I<main-dependency-template>
  40  [| I<alternative-dependency-template>]
  41  [...]
  42  [* I<field-name>: I<field-value>]
  43  [...]
  44   I<symbol> I<minimal-version> [I<id-of-dependency-template>]
  45
  46 The I<library-soname> is exactly the value of the SONAME field
  47 as exported by L<objdump(1)>.
  48 A I<dependency-template> is a
  49 dependency where I<#MINVER#> is dynamically replaced either by
  50 a version check like “(E<gt>= I<minimal-version>)” or by nothing (if
  51 an unversioned dependency is deemed sufficient).
  52
  53 Each exported I<symbol> (listed as I<name>@I<version>, with
  54 I<version> being “Base” if the library is not versioned) is associated
  55 to a I<minimal-version> of its dependency template (the main dependency
  56 template is always used and will end up being combined with the dependency
  57 template referenced by I<id-of-dependency-template> if present).
  58 The
  59 first alternative dependency template is numbered 1, the second one 2,
  60 etc.
  61 Each column is separated by exactly a single whitespace.
  62
  63 Each entry for a library can also have some fields of meta-information.
  64 Those fields are stored on lines starting with an asterisk.
  65 Currently,
  66 the only valid fields are:
  67
  68 =over
  69
  70 =item B<Build-Depends-Package>
  71
  72 It indicates the name of the “-dev” package associated to the library
  73 and is used by B<dpkg-shlibdeps> to make sure that the dependency
  74 generated is at least as strict as the corresponding build dependency
  75 (since dpkg 1.14.13).
  76
  77 =item B<Build-Depends-Packages>
  78
  79 The same as B<Build-Depends-Package> but accepts a comma-separated
  80 list of package names (since dpkg 1.20.0).
  81 This field will override any B<Build-Depends-Package> field present,
  82 and is mostly useful with “-dev” packages and metapackages depending
  83 on these, say for a transition period.
  84
  85 =item B<Allow-Internal-Symbol-Groups>
  86
  87 It indicates what internal symbol groups should be ignored, as a whitespace
  88 separated list, so that the symbols contained in those groups get
  89 included in the output file (since dpkg 1.20.1).
  90 This should only be necessary for toolchain
  91 packages providing those internal symbols.
  92 The available groups are
  93 system dependent, for ELF and GNU-based systems these are B<aeabi>
  94 and B<gomp>.
  95
  96 =item B<Ignore-Blacklist-Groups>
  97
  98 A deprecated alias for B<Allow-Internal-Symbol-Groups> (since dpkg 1.20.1,
  99 supported since dpkg 1.17.6).
 100
 101 =back
 102
 103 =head1 EXAMPLES
 104
 105 =head2 Simple symbols file
 106
 107  libftp.so.3 libftp3 #MINVER#
 108   DefaultNetbuf@Base 3.1-1-6
 109   FtpAccess@Base 3.1-1-6
 110   [...]
 111
 112 =head2 Advanced symbols file
 113
 114  libGL.so.1 libgl1
 115  | libgl1-mesa-glx #MINVER#
 116  * Build-Depends-Package: libgl1-mesa-dev
 117   publicGlSymbol@Base 6.3-1
 118   [...]
 119   implementationSpecificSymbol@Base 6.5.2-7 1
 120   [...]
 121
 122 =head1 SEE ALSO
 123
 124 L<https://wiki.debian.org/Projects/ImprovedDpkgShlibdeps>,
 125 L<deb-src-symbols(5)>,
 126 L<dpkg-shlibdeps(1)>,
 127 L<dpkg-gensymbols(1)>.