man/dpkg-gensymbols.pod

   1 # dpkg manual page - dpkg-gensymbols(1)
   2 #
   3 # Copyright © 2007-2011 Raphaël Hertzog <hertzog@debian.org>
   4 # Copyright © 2009-2010 Modestas Vainius <modestas@vainius.eu>
   5 # Copyright © 2012-2015 Guillem Jover <guillem@debian.org>
   6 #
   7 # This is free software; you can redistribute it and/or modify
   8 # it under the terms of the GNU General Public License as published by
   9 # the Free Software Foundation; either version 2 of the License, or
  10 # (at your option) any later version.
  11 #
  12 # This is distributed in the hope that it will be useful,
  13 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15 # GNU General Public License for more details.
  16 #
  17 # You should have received a copy of the GNU General Public License
  18 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
  19
  20 =encoding utf8
  21
  22 =head1 NAME
  23
  24 dpkg-gensymbols - generate symbols files (shared library dependency information)
  25
  26 =head1 SYNOPSIS
  27
  28 B<dpkg-gensymbols>
  29 [I<option>...]
  30
  31 =head1 DESCRIPTION
  32
  33 B<dpkg-gensymbols>
  34 scans a temporary build tree (debian/tmp by default) looking for libraries
  35 and generates a I<symbols> file describing them. This file, if
  36 non-empty, is then installed in the DEBIAN subdirectory of the build tree
  37 so that it ends up included in the control information of the package.
  38
  39 When generating those files, it uses as input some symbols files
  40 provided by the maintainer. It looks for the following files (and uses the
  41 first that is found):
  42
  43 =over
  44
  45 =item *
  46
  47 debian/I<package>.symbols.I<arch>
  48
  49 =item *
  50
  51 debian/symbols.I<arch>
  52
  53 =item *
  54
  55 debian/I<package>.symbols
  56
  57 =item *
  58
  59 debian/symbols
  60
  61 =back
  62
  63 The main interest of those files is to provide the minimal version
  64 associated to each symbol provided by the libraries. Usually it
  65 corresponds to the first version of that package that provided the symbol,
  66 but it can be manually incremented by the maintainer if the ABI of the
  67 symbol is extended without breaking backwards compatibility. It's the
  68 responsibility of the maintainer to keep those files up-to-date and
  69 accurate, but B<dpkg-gensymbols> helps with that.
  70
  71 When the generated symbols files differ from the maintainer supplied
  72 one, B<dpkg-gensymbols> will print a diff between the two versions.
  73 Furthermore if the difference is too significant, it will even fail (you
  74 can customize how much difference you can tolerate, see the B<-c>
  75 option).
  76
  77 =head1 MAINTAINING SYMBOLS FILES
  78
  79 The base interchange format of the symbols file is described in
  80 B<deb-symbols>(5), which is used by the symbols files included in
  81 binary packages. These are generated from template symbols files
  82 with a format based on the former, described in B<deb-src-symbols>(5)
  83 and included in source packages.
  84
  85 The symbols files are really useful only if they reflect the evolution of
  86 the package through several releases. Thus the maintainer has to update
  87 them every time that a new symbol is added so that its associated minimal
  88 version matches reality.
  89
  90 The diffs contained in the build logs can be used as a starting point,
  91 but the maintainer, additionally, has to make sure that the behaviour
  92 of those symbols has not changed in a way that would make anything
  93 using those symbols and linking against the new version, stop working
  94 with the old version.
  95
  96 In most cases, the diff applies directly to the
  97 debian/I<package>.symbols file. That said, further tweaks are usually
  98 needed: it's recommended for example to drop the Debian revision
  99 from the minimal version so that backports with a lower version number
 100 but the same upstream version still satisfy the generated dependencies.
 101 If the Debian revision can't be dropped because the symbol really got
 102 added by the Debian specific change, then one should suffix the version
 103 with ‘B<~>’.
 104
 105 Before applying any patch to the symbols file, the maintainer should
 106 double-check that it's sane. Public symbols are not supposed to disappear,
 107 so the patch should ideally only add new lines.
 108
 109 Note that you can put comments in symbols files.
 110
 111 Do not forget to check if old symbol versions need to be increased.
 112 There is no way B<dpkg-gensymbols> can warn about this. Blindly
 113 applying the diff or assuming there is nothing to change if there is
 114 no diff, without checking for such changes, can lead to packages with
 115 loose dependencies that claim they can work with older packages they
 116 cannot work with. This will introduce hard to find bugs with (partial)
 117 upgrades.
 118
 119 =head2 Good library management
 120
 121 A well-maintained library has the following features:
 122
 123 =over
 124
 125 =item *
 126
 127 its API is stable (public symbols are never dropped, only new public
 128 symbols are added) and changes in incompatible ways only when the SONAME
 129 changes;
 130
 131 =item *
 132
 133 ideally, it uses symbol versioning to achieve ABI stability despite
 134 internal changes and API extension;
 135
 136 =item *
 137
 138 it doesn't export private symbols (such symbols can be tagged optional as
 139 workaround).
 140
 141 =back
 142
 143 While maintaining the symbols file, it's easy to notice appearance and
 144 disappearance of symbols. But it's more difficult to catch incompatible
 145 API and ABI change. Thus the maintainer should read thoroughly the
 146 upstream changelog looking for cases where the rules of good library
 147 management have been broken. If potential problems are discovered,
 148 the upstream author should be notified as an upstream fix is always better
 149 than a Debian specific work-around.
 150
 151 =head1 OPTIONS
 152
 153 =over
 154
 155 =item B<-P>I<package-build-dir>
 156
 157 Scan I<package-build-dir> instead of debian/tmp.
 158
 159 =item B<-p>I<package>
 160
 161 Define the package name. Required if more than one binary package is listed in
 162 debian/control (or if there's no debian/control file).
 163
 164 =item B<-v>I<version>
 165
 166 Define the package version. Defaults to the version extracted from
 167 debian/changelog. Required if called outside of a source package tree.
 168
 169 =item B<-e>I<library-file>
 170
 171 Only analyze libraries explicitly listed instead of finding all public
 172 libraries. You can use shell patterns used for pathname expansions (see
 173 the B<File::Glob>(3perl) manual page for details) in I<library-file>
 174 to match multiple libraries with a single argument (otherwise you need
 175 multiple B<-e>).
 176
 177 =item B<-l>I<directory>
 178
 179 Prepend
 180 I<directory>
 181 to the list of directories to search for private shared libraries
 182 (since dpkg 1.19.1). This option can be used multiple times.
 183
 184 B<Note>: Use this option instead of setting B<LD_LIBRARY_PATH>,
 185 as that environment variable is used to control the run-time linker
 186 and abusing it to set the shared library paths at build-time can be
 187 problematic when cross-compiling for example.
 188
 189 =item B<-I>I<filename>
 190
 191 Use I<filename> as reference file to generate the symbols file
 192 that is integrated in the package itself.
 193
 194 =item B<-O>[I<filename>]
 195
 196 Print the generated symbols file to standard output or to I<filename>
 197 if specified, rather than to
 198 B<debian/tmp/DEBIAN/symbols>
 199 (or
 200 I<package-build-dir>B</DEBIAN/symbols>
 201 if
 202 B<-P>
 203 was used). If I<filename> is pre-existing, its contents are used as
 204 basis for the generated symbols file.
 205 You can use this feature to update a symbols file so that it matches a
 206 newer upstream version of your library.
 207
 208 =item B<-t>
 209
 210 Write the symbol file in template mode rather than the format compatible with
 211 B<deb-symbols>(5). The main difference is that in the template mode symbol
 212 names and tags are written in their original form contrary to the
 213 post-processed symbol names with tags stripped in the compatibility mode.
 214 Moreover, some symbols might be omitted when writing a standard
 215 B<deb-symbols>(5) file (according to the tag processing rules) while all
 216 symbols are always written to the symbol file template.
 217
 218 =item B<-c>I<[0-4]>
 219
 220 Define the checks to do when comparing the generated symbols file with the
 221 template file used as starting point. By default the level is 1. Increasing
 222 levels do more checks and include all checks of lower levels.
 223
 224 =over
 225
 226 =item Level 0
 227
 228 Never fails.
 229
 230 =item Level 1
 231
 232 Fails if some symbols have disappeared.
 233
 234 =item Level 2
 235
 236 Fails if some new symbols have been introduced.
 237
 238 =item Level 3
 239
 240 Fails if some libraries have disappeared.
 241
 242 =item Level 4
 243
 244 Fails if some libraries have been introduced.
 245
 246 =back
 247
 248 This value can be overridden by the environment variable
 249 B<DPKG_GENSYMBOLS_CHECK_LEVEL>.
 250
 251 =item B<-q>
 252
 253 Keep quiet and never generate a diff between generated symbols file and the
 254 template file used as starting point or show any warnings about new/lost
 255 libraries or new/lost symbols. This option only disables informational output
 256 but not the checks themselves (see B<-c> option).
 257
 258 =item B<-a>I<arch>
 259
 260 Assume I<arch> as host architecture when processing symbol files. Use this
 261 option to generate a symbol file or diff for any architecture provided its
 262 binaries are already available.
 263
 264 =item B<-d>
 265
 266 Enable debug mode. Numerous messages are displayed to explain what
 267 B<dpkg-gensymbols>
 268 does.
 269
 270 =item B<-V>
 271
 272 Enable verbose mode. The generated symbols file contains deprecated
 273 symbols as comments. Furthermore in template mode, pattern symbols
 274 are followed by comments listing real symbols that have matched the
 275 pattern.
 276
 277 =item B<-?>, B<--help>
 278
 279 Show the usage message and exit.
 280
 281 =item B<--version>
 282
 283 Show the version and exit.
 284
 285 =back
 286
 287 =head1 ENVIRONMENT
 288
 289 =over
 290
 291 =item B<DPKG_GENSYMBOLS_CHECK_LEVEL>
 292
 293 Overrides the command check level, even if the B<-c> command-line
 294 argument was given (note that this goes against the common convention
 295 of command-line arguments having precedence over environment variables).
 296
 297 =item B<DPKG_COLORS>
 298
 299 Sets the color mode (since dpkg 1.18.5).
 300 The currently accepted values are: B<auto> (default), B<always> and
 301 B<never>.
 302
 303 =item B<DPKG_NLS>
 304
 305 If set, it will be used to decide whether to activate Native Language Support,
 306 also known as internationalization (or i18n) support (since dpkg 1.19.0).
 307 The accepted values are: B<0> and B<1> (default).
 308
 309 =back
 310
 311 =head1 SEE ALSO
 312
 313 L<https://people.redhat.com/drepper/symbol-versioning>,
 314 L<https://people.redhat.com/drepper/goodpractice.pdf>,
 315 L<https://people.redhat.com/drepper/dsohowto.pdf>,
 316 B<deb-src-symbol>(5),
 317 B<deb-symbols>(5),
 318 B<dpkg-shlibdeps>(1).