1dpkg-gensymbols(1)                dpkg suite                dpkg-gensymbols(1)
2
3
4

NAME

6       dpkg-gensymbols  -  generate  symbols  files (shared library dependency
7       information)
8

SYNOPSIS

10       dpkg-gensymbols [option...]
11

DESCRIPTION

13       dpkg-gensymbols scans a temporary build tree  (debian/tmp  by  default)
14       looking  for  libraries  and  generates a symbols file describing them.
15       This file, if non-empty, is then installed in the  DEBIAN  subdirectory
16       of  the  build  tree  so  that  it  ends  up  included  in  the control
17       information of the package.
18
19       When generating those files,  it  uses  as  input  some  symbols  files
20       provided  by the maintainer. It looks for the following files (and uses
21       the first that is found):
22
23       ·   debian/package.symbols.arch
24
25       ·   debian/symbols.arch
26
27       ·   debian/package.symbols
28
29       ·   debian/symbols
30
31       The main interest of those files is  to  provide  the  minimal  version
32       associated  to  each  symbol  provided  by  the  libraries.  Usually it
33       corresponds to the first version of  that  package  that  provided  the
34       symbol, but it can be manually incremented by the maintainer if the ABI
35       of the symbol is extended  without  breaking  backwards  compatibility.
36       It's  the  responsibility  of the maintainer to keep those files up-to-
37       date and accurate, but dpkg-gensymbols helps with that.
38
39       When the generated symbols files differ from  the  maintainer  supplied
40       one,  dpkg-gensymbols  will  print  a  diff  between  the two versions.
41       Furthermore if the difference is too significant,  it  will  even  fail
42       (you  can  customize  how  much difference you can tolerate, see the -c
43       option).
44

MAINTAINING SYMBOLS FILES

46       The symbols files are really useful only if they reflect the  evolution
47       of  the  package  through  several releases. Thus the maintainer has to
48       update them every  time  that  a  new  symbol  is  added  so  that  its
49       associated minimal version matches reality.  The diffs contained in the
50       build logs can be  used  as  a  starting  point,  but  the  maintainer,
51       additionally,  has to make sure that the behaviour of those symbols has
52       not changed in a way that would make anything using those  symbols  and
53       linking against the new version, stop working with the old version.  In
54       most cases, the diff applies  directly  to  the  debian/package.symbols
55       file.  That  said,  further tweaks are usually needed: it's recommended
56       for example to drop the Debian revision from  the  minimal  version  so
57       that  backports  with  a  lower  version  number  but the same upstream
58       version still  satisfy  the  generated  dependencies.   If  the  Debian
59       revision  can't  be  dropped because the symbol really got added by the
60       Debian specific change, then one should suffix the version with ‘~’.
61
62       Before applying any patch to the symbols file,  the  maintainer  should
63       double-check  that  it's  sane.  Public  symbols  are  not  supposed to
64       disappear, so the patch should ideally only add new lines.
65
66       Note that you can put comments in symbols files: any line with  ‘#’  as
67       the  first  character  is a comment except if it starts with ‘#include’
68       (see section Using includes).   Lines  starting  with  ‘#MISSING:’  are
69       special comments documenting symbols that have disappeared.
70
71       Do  not  forget  to  check if old symbol versions need to be increased.
72       There is no way dpkg-gensymbols can warn about this.  Blindly  applying
73       the  diff  or  assuming there is nothing to change if there is no diff,
74       without checking for such changes, can  lead  to  packages  with  loose
75       dependencies  that  claim they can work with older packages they cannot
76       work with. This  will  introduce  hard  to  find  bugs  with  (partial)
77       upgrades.
78
79   Using #PACKAGE# substitution
80       In   some   rare   cases,  the  name  of  the  library  varies  between
81       architectures.  To avoid hardcoding the name  of  the  package  in  the
82       symbols  file, you can use the marker #PACKAGE#. It will be replaced by
83       the real  package  name  during  installation  of  the  symbols  files.
84       Contrary  to  the  #MINVER#  marker,  #PACKAGE#  will never appear in a
85       symbols file inside a binary package.
86
87   Using symbol tags
88       Symbol tagging is useful for marking symbols that are special  in  some
89       way.   Any  symbol can have an arbitrary number of tags associated with
90       it. While all tags are  parsed  and  stored,  only  some  of  them  are
91       understood  by  dpkg-gensymbols  and  trigger  special  handling of the
92       symbols. See subsection Standard symbol tags  for  reference  of  these
93       tags.
94
95       Tag  specification comes right before the symbol name (no whitespace is
96       allowed in between). It always starts with an opening bracket  (,  ends
97       with  a  closing  bracket ) and must contain at least one tag. Multiple
98       tags are separated by the | character. Each tag can optionally  have  a
99       value  which  is  separated  form  the tag name by the = character. Tag
100       names and values can be arbitrary strings except  they  cannot  contain
101       any  of  the  special  )  |  = characters. Symbol names following a tag
102       specification can optionally be quoted with either ' or " characters to
103       allow  whitespaces in them. However, if there are no tags specified for
104       the symbol, quotes are  treated  as  part  of  the  symbol  name  which
105       continues up until the first space.
106
107        (tag1=i am marked|tag name with space)"tagged quoted symbol"@Base 1.0
108        (optional)tagged_unquoted_symbol@Base 1.0 1
109        untagged_symbol@Base 1.0
110
111       The  first  symbol in the example is named tagged quoted symbol and has
112       two tags: tag1 with value i am marked and tag name with space that  has
113       no value. The second symbol named tagged_unquoted_symbol is only tagged
114       with the tag named optional. The last  symbol  is  an  example  of  the
115       normal untagged symbol.
116
117       Since  symbol  tags are an extension of the deb-symbols(5) format, they
118       can only be part of the symbols files used in  source  packages  (those
119       files  should then be seen as templates used to build the symbols files
120       that are embedded in binary packages). When dpkg-gensymbols  is  called
121       without  the  -t option, it will output symbols files compatible to the
122       deb-symbols(5) format: it fully  processes  symbols  according  to  the
123       requirements  of  their  standard  tags  and  strips  all tags from the
124       output. On the contrary, in template mode (-t) all  symbols  and  their
125       tags  (both  standard  and unknown ones) are kept in the output and are
126       written in their original form as they were loaded.
127
128   Standard symbol tags
129       optional
130              A symbol marked as optional can disappear from  the  library  at
131              any  time  and  that  will  never cause dpkg-gensymbols to fail.
132              However, disappeared optional symbols will  continuously  appear
133              as  MISSING  in  the  diff  in  each new package revision.  This
134              behaviour serves as a reminder for the maintainer  that  such  a
135              symbol  needs  to  be removed from the symbol file or readded to
136              the library. When the  optional  symbol,  which  was  previously
137              declared as MISSING, suddenly reappears in the next revision, it
138              will be upgraded back to the “existing” status with its  minimum
139              version unchanged.
140
141              This  tag  is  useful  for symbols which are private where their
142              disappearance do not cause ABI breakage. For  example,  most  of
143              C++  template  instantiations  fall into this category. Like any
144              other tag, this one may also have an arbitrary value:  it  could
145              be used to indicate why the symbol is considered optional.
146
147       arch=architecture-list
148       arch-bits=architecture-bits
149       arch-endian=architecture-endianness
150              These  tags allow one to restrict the set of architectures where
151              the symbol is supposed to exist. The arch-bits  and  arch-endian
152              tags  are  supported since dpkg 1.18.0. When the symbols list is
153              updated with the symbols discovered in the  library,  all  arch-
154              specific   symbols   which  do  not  concern  the  current  host
155              architecture are treated as if they did not exist. If  an  arch-
156              specific  symbol matching the current host architecture does not
157              exist in the library,  normal  procedures  for  missing  symbols
158              apply  and  it  may  cause dpkg-gensymbols to fail. On the other
159              hand, if the arch-specific symbol  is  found  when  it  was  not
160              supposed  to exist (because the current host architecture is not
161              listed in the tag or does not match the endianness and bits), it
162              is  made  arch neutral (i.e. the arch, arch-bits and arch-endian
163              tags are dropped and the symbol will appear in the diff  due  to
164              this change), but it is not considered as new.
165
166              When  operating  in  the  default non-template mode, among arch-
167              specific  symbols  only  those  that  match  the  current   host
168              architecture  are  written to the symbols file. On the contrary,
169              all arch-specific symbols (including those from foreign  arches)
170              are always written to the symbol file when operating in template
171              mode.
172
173              The format of architecture-list is the same as the one  used  in
174              the  Build-Depends field of debian/control (except the enclosing
175              square brackets []). For example, the first symbol from the list
176              below  will  be  considered  only  on  alpha, any-amd64 and ia64
177              architectures, the second only on linux architectures, while the
178              third one anywhere except on armel.
179
180               (arch=alpha any-amd64 ia64)64bit_specific_symbol@Base 1.0
181               (arch=linux-any)linux_specific_symbol@Base 1.0
182               (arch=!armel)symbol_armel_does_not_have@Base 1.0
183
184              The architecture-bits is either 32 or 64.
185
186               (arch-bits=32)32bit_specific_symbol@Base 1.0
187               (arch-bits=64)64bit_specific_symbol@Base 1.0
188
189              The architecture-endianness is either little or big.
190
191               (arch-endian=little)little_endian_specific_symbol@Base 1.0
192               (arch-endian=big)big_endian_specific_symbol@Base 1.0
193
194              Multiple restrictions can be chained.
195
196               (arch-bits=32|arch-endian=little)32bit_le_symbol@Base 1.0
197
198       ignore-blacklist
199              dpkg-gensymbols has an internal blacklist of symbols that should
200              not appear in symbols files  as  they  are  usually  only  side-
201              effects  of implementation details of the toolchain. If for some
202              reason, you really want one of those symbols to be  included  in
203              the   symbols   file,   you   should   tag   the   symbol   with
204              ignore-blacklist.  It  can  be  necessary  for  some  low  level
205              toolchain libraries like libgcc.
206
207       c++    Denotes c++ symbol pattern. See Using symbol patterns subsection
208              below.
209
210       symver Denotes symver (symbol version) symbol pattern. See Using symbol
211              patterns subsection below.
212
213       regex  Denotes   regex   symbol  pattern.  See  Using  symbol  patterns
214              subsection below.
215
216   Using symbol patterns
217       Unlike a standard symbol specification, a pattern  may  cover  multiple
218       real  symbols  from  the library. dpkg-gensymbols will attempt to match
219       each pattern against each real symbol that does  not  have  a  specific
220       symbol  counterpart  defined  in  the  symbol  file. Whenever the first
221       matching pattern is found, all its tags and properties will be used  as
222       a  basis  specification of the symbol. If none of the patterns matches,
223       the symbol will be considered as new.
224
225       A pattern is considered lost if it does not match  any  symbol  in  the
226       library.  By  default this will trigger a dpkg-gensymbols failure under
227       -c1 or higher level. However, if the failure is undesired, the  pattern
228       may be marked with the optional tag. Then if the pattern does not match
229       anything, it will only appear in the diff as  MISSING.  Moreover,  like
230       any  symbol,  the  pattern may be limited to the specific architectures
231       with the arch tag. Please refer  to  Standard  symbol  tags  subsection
232       above for more information.
233
234       Patterns  are  an extension of the deb-symbols(5) format hence they are
235       only valid in symbol file templates. Pattern  specification  syntax  is
236       not  any  different  from the one of a specific symbol. However, symbol
237       name part of the specification serves as an expression  to  be  matched
238       against  name@version of the real symbol. In order to distinguish among
239       different pattern types, a pattern will  typically  be  tagged  with  a
240       special tag.
241
242       At the moment, dpkg-gensymbols supports three basic pattern types:
243
244       c++
245          This  pattern is denoted by the c++ tag. It matches only C++ symbols
246          by their demangled symbol name (as emitted by  c++filt(1)  utility).
247          This  pattern is very handy for matching symbols which mangled names
248          might vary across  different  architectures  while  their  demangled
249          names  remain  the  same.  One  group of such symbols is non-virtual
250          thunks which have architecture specific offsets  embedded  in  their
251          mangled  names.  A  common  instance  of  this  case  is  a  virtual
252          destructor which under diamond inheritance needs a non-virtual thunk
253          symbol.  For  example, even if _ZThn8_N3NSB6ClassDD1Ev@Base on 32bit
254          architectures  will  probably  be  _ZThn16_N3NSB6ClassDD1Ev@Base  on
255          64bit ones, it can be matched with a single c++ pattern:
256
257          libdummy.so.1 libdummy1 #MINVER#
258           [...]
259           (c++)"non-virtual thunk to NSB::ClassD::~ClassD()@Base" 1.0
260           [...]
261
262          The  demangled name above can be obtained by executing the following
263          command:
264
265           $ echo '_ZThn8_N3NSB6ClassDD1Ev@Base' | c++filt
266
267          Please note that while mangled name is  unique  in  the  library  by
268          definition,  this  is  not  necessarily  true for demangled names. A
269          couple of distinct real symbols may have the  same  demangled  name.
270          For  example,  that's  the  case  with  non-virtual thunk symbols in
271          complex inheritance configurations or  with  most  constructors  and
272          destructors  (since  g++  typically  generates  two real symbols for
273          them). However, as these collisions happen on the  ABI  level,  they
274          should not degrade quality of the symbol file.
275
276       symver
277          This pattern is denoted by the symver tag. Well maintained libraries
278          have  versioned  symbols  where  each  version  corresponds  to  the
279          upstream version where the symbol got added. If that's the case, you
280          can use a symver pattern to  match  any  symbol  associated  to  the
281          specific version. For example:
282
283          libc.so.6 libc6 #MINVER#
284           (symver)GLIBC_2.0 2.0
285           [...]
286           (symver)GLIBC_2.7 2.7
287           access@GLIBC_2.0 2.2
288
289          All  symbols  associated  with versions GLIBC_2.0 and GLIBC_2.7 will
290          lead to minimal  version  of  2.0  and  2.7  respectively  with  the
291          exception  of the symbol access@GLIBC_2.0. The latter will lead to a
292          minimal dependency on libc6 version 2.2 despite being in  the  scope
293          of  the  "(symver)GLIBC_2.0"  pattern  because specific symbols take
294          precedence over patterns.
295
296          Please note that while  old  style  wildcard  patterns  (denoted  by
297          "*@version" in the symbol name field) are still supported, they have
298          been deprecated by new style syntax "(symver|optional)version".  For
299          example,     "*@GLIBC_2.0     2.0"     should    be    written    as
300          "(symver|optional)GLIBC_2.0 2.0" if the same behaviour is needed.
301
302       regex
303          Regular expression patterns are denoted by the regex tag. They match
304          by the perl regular expression specified in the symbol name field. A
305          regular expression is matched as it is, therefore do not  forget  to
306          start  it  with the ^ character or it may match any part of the real
307          symbol name@version string. For example:
308
309          libdummy.so.1 libdummy1 #MINVER#
310           (regex)"^mystack_.*@Base$" 1.0
311           (regex|optional)"private" 1.0
312
313          Symbols      like      "mystack_new@Base",      "mystack_push@Base",
314          "mystack_pop@Base"  etc.  will be matched by the first pattern while
315          e.g. "ng_mystack_new@Base" won't.  The second pattern will match all
316          symbols  having the string "private" in their names and matches will
317          inherit optional tag from the pattern.
318
319       Basic patterns listed above can be combined where it  makes  sense.  In
320       that  case,  they  are  processed  in  the  order in which the tags are
321       specified. For example, both
322
323        (c++|regex)"^NSA::ClassA::Private::privmethod\d\(int\)@Base" 1.0
324        (regex|c++)N3NSA6ClassA7Private11privmethod\dEi@Base 1.0
325
326       will  match  symbols  "_ZN3NSA6ClassA7Private11privmethod1Ei@Base"  and
327       "_ZN3NSA6ClassA7Private11privmethod2Ei@Base".  When  matching the first
328       pattern, the raw symbol is first demangled  as  C++  symbol,  then  the
329       demangled  name is matched against the regular expression. On the other
330       hand, when matching the second pattern, regular expression  is  matched
331       against the raw symbol name, then the symbol is tested if it is C++ one
332       by attempting to demangle it. A  failure  of  any  basic  pattern  will
333       result  in  the  failure of the whole pattern.  Therefore, for example,
334       "__N3NSA6ClassA7Private11privmethod\dEi@Base" will not match either  of
335       the patterns because it is not a valid C++ symbol.
336
337       In  general,  all  patterns are divided into two groups: aliases (basic
338       c++ and symver)  and  generic  patterns  (regex,  all  combinations  of
339       multiple  basic  patterns).  Matching  of basic alias-based patterns is
340       fast (O(1)) while generic patterns are O(N) (N - generic pattern count)
341       for  each  symbol.  Therefore, it is recommended not to overuse generic
342       patterns.
343
344       When multiple patterns match the same real symbol, aliases (first  c++,
345       then  symver) are preferred over generic patterns. Generic patterns are
346       matched in the order they are found in the symbol file  template  until
347       the  first  success.   Please  note, however, that manual reordering of
348       template  file  entries  is  not  recommended  because  dpkg-gensymbols
349       generates diffs based on the alphanumerical order of their names.
350
351   Using includes
352       When  the  set of exported symbols differ between architectures, it may
353       become inefficient to use a single symbol  file.  In  those  cases,  an
354       include directive may prove to be useful in a couple of ways:
355
356       ·   You can factorize the common part in some external file and include
357           that file in your package.symbols.arch file  by  using  an  include
358           directive like this:
359
360           #include "packages.symbols.common"
361
362       ·   The include directive may also be tagged like any symbol:
363
364           (tag|...|tagN)#include "file-to-include"
365
366           As  a  result,  all  symbols  included from file-to-include will be
367           considered to be tagged with tag ... tagN by default. You  can  use
368           this feature to create a common package.symbols file which includes
369           architecture specific symbol files:
370
371             common_symbol1@Base 1.0
372            (arch=amd64 ia64 alpha)#include "package.symbols.64bit"
373            (arch=!amd64 !ia64 !alpha)#include "package.symbols.32bit"
374             common_symbol2@Base 1.0
375
376       The symbols files are read line by line,  and  include  directives  are
377       processed  as soon as they are encountered. This means that the content
378       of the included file can override any content that appeared before  the
379       include directive and that any content after the directive can override
380       anything contained in the included file. Any symbol  (or  even  another
381       #include directive) in the included file can specify additional tags or
382       override values  of  the  inherited  tags  in  its  tag  specification.
383       However,  there is no way for the symbol to remove any of the inherited
384       tags.
385
386       An included file can repeat the header line containing  the  SONAME  of
387       the  library.  In  that  case,  it overrides any header line previously
388       read.  However, in general it's best to avoid duplicating header lines.
389       One way to do it is the following:
390
391       #include "libsomething1.symbols.common"
392        arch_specific_symbol@Base 1.0
393
394   Good library management
395       A well-maintained library has the following features:
396
397       ·   its  API  is  stable  (public  symbols  are never dropped, only new
398           public symbols are added) and changes  in  incompatible  ways  only
399           when the SONAME changes;
400
401       ·   ideally, it uses symbol versioning to achieve ABI stability despite
402           internal changes and API extension;
403
404       ·   it doesn't export private  symbols  (such  symbols  can  be  tagged
405           optional as workaround).
406
407       While  maintaining the symbols file, it's easy to notice appearance and
408       disappearance of symbols. But it's more difficult to catch incompatible
409       API  and  ABI  change.  Thus  the maintainer should read thoroughly the
410       upstream changelog looking for cases where the rules  of  good  library
411       management  have been broken. If potential problems are discovered, the
412       upstream author should be notified as an upstream fix is always  better
413       than a Debian specific work-around.
414

OPTIONS

416       -Ppackage-build-dir
417              Scan package-build-dir instead of debian/tmp.
418
419       -ppackage
420              Define  the  package  name.  Required  if  more  than one binary
421              package  is  listed  in  debian/control  (or   if   there's   no
422              debian/control file).
423
424       -vversion
425              Define  the  package  version. Defaults to the version extracted
426              from debian/changelog. Required if called outside  of  a  source
427              package tree.
428
429       -elibrary-file
430              Only  analyze libraries explicitly listed instead of finding all
431              public libraries. You can use shell patterns used  for  pathname
432              expansions  (see  the File::Glob(3perl) manual page for details)
433              in library-file  to  match  multiple  libraries  with  a  single
434              argument (otherwise you need multiple -e).
435
436       -Ifilename
437              Use filename as reference file to generate the symbols file that
438              is integrated in the package itself.
439
440       -O[filename]
441              Print the generated  symbols  file  to  standard  output  or  to
442              filename  if specified, rather than to debian/tmp/DEBIAN/symbols
443              (or  package-build-dir/DEBIAN/symbols  if  -P  was   used).   If
444              filename is pre-existing, its contents are used as basis for the
445              generated symbols file.  You can use this feature  to  update  a
446              symbols file so that it matches a newer upstream version of your
447              library.
448
449       -t     Write the symbol file in template mode rather  than  the  format
450              compatible  with  deb-symbols(5). The main difference is that in
451              the template mode symbol names and tags  are  written  in  their
452              original  form  contrary to the post-processed symbol names with
453              tags stripped in the compatibility mode.  Moreover, some symbols
454              might  be  omitted  when  writing a standard deb-symbols(5) file
455              (according to the tag processing rules) while  all  symbols  are
456              always written to the symbol file template.
457
458       -c[0-4]
459              Define  the  checks  to  do when comparing the generated symbols
460              file with the template file used as starting point.  By  default
461              the level is 1. Increasing levels do more checks and include all
462              checks of lower levels. Level 0 never fails. Level  1  fails  if
463              some symbols have disappeared. Level 2 fails if some new symbols
464              have been introduced. Level  3  fails  if  some  libraries  have
465              disappeared.   Level   4  fails  if  some  libraries  have  been
466              introduced.
467
468              This  value  can  be  overridden  by  the  environment  variable
469              DPKG_GENSYMBOLS_CHECK_LEVEL.
470
471       -q     Keep  quiet  and never generate a diff between generated symbols
472              file and the template file used as starting point  or  show  any
473              warnings  about  new/lost  libraries  or  new/lost symbols. This
474              option only disables informational output  but  not  the  checks
475              themselves (see -c option).
476
477       -aarch Assume  arch  as host architecture when processing symbol files.
478              Use this option to generate  a  symbol  file  or  diff  for  any
479              architecture provided its binaries are already available.
480
481       -d     Enable  debug  mode.  Numerous messages are displayed to explain
482              what dpkg-gensymbols does.
483
484       -V     Enable  verbose  mode.  The  generated  symbols  file   contains
485              deprecated  symbols  as  comments. Furthermore in template mode,
486              pattern symbols are followed by comments  listing  real  symbols
487              that have matched the pattern.
488
489       -?, --help
490              Show the usage message and exit.
491
492       --version
493              Show the version and exit.
494

ENVIRONMENT

496       DPKG_GENSYMBOLS_CHECK_LEVEL
497              Overrides  the  command check level, even if the -c command-line
498              argument was given (note  that  this  goes  against  the  common
499              convention  of  command-line  arguments  having  precedence over
500              environment variables).
501

SEE ALSO

503       https://people.redhat.com/drepper/symbol-versioning
504       https://people.redhat.com/drepper/goodpractice.pdf
505       https://people.redhat.com/drepper/dsohowto.pdf
506       deb-symbols(5), dpkg-shlibdeps(1).
507
508
509
5101.18.25                           2018-06-26                dpkg-gensymbols(1)
Impressum