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