1dpkg-gensymbols(1) dpkg utilities dpkg-gensymbols(1)
2
6 dpkg-gensymbols - generate symbols files (shared library dependency
7 information)
8
10 dpkg-gensymbols [options]
11
13 dpkg-gensymbols scans a temporary build tree (debian/tmp by default)
14 looking for libraries and generate a symbols file describing them. This
15 file, if non-empty, is then installed in the DEBIAN subdirectory of the
16 build tree so that it ends up included in the control information of
17 the package.
18 When generating those files, it uses as input some symbols files pro‐
20 vided by the maintainer. It looks for the following files (and use the
21 first that is found):
22 · debian/package.symbols.arch
24 · debian/symbols.arch
26 · debian/package.symbols
28 · debian/symbols
30 The main interest of those files is to provide the minimal version
32 associated to each symbol provided by the libraries. Usually it corre‐
33 sponds to the first version of that package that provided the symbol,
34 but it can be manually incremented by the maintainer if the ABI of the
35 symbol is extended without breaking backwards compatibility. It's the
36 responsibility of the maintainer to keep those files up-to-date and
37 accurate, but dpkg-gensymbols helps him.
38 When the generated symbols files differ from the maintainer supplied
40 one, dpkg-gensymbols will print a diff between the two versions. Fur‐
41 thermore if the difference are too significant, it will even fail (you
42 can customize how much difference you can tolerate, see the -c option).
43
45 The symbols files are really useful only if they reflect the evolution
46 of the package through several releases. Thus the maintainer has to
47 update them every time that a new symbol is added so that its associ‐
48 ated minimal version matches reality. To do this properly he can use
49 the diffs contained in the build logs. In most cases, the diff applies
50 directly to his debian/package.symbols file. That said, further tweaks
51 are usually needed: it's recommended for example to drop the Debian
52 revision from the minimal version so that backports with a lower ver‐
53 sion number but the same upstream version still satisfy the generated
54 dependencies. If the Debian revision can't be dropped because the sym‐
55 bol really got added by the Debian specific change, then one should
56 suffix the version with "~".
57 Before applying any patch to the symbols file, the maintainer should
59 double-check that it's sane. Public symbols are not supposed to disap‐
60 pear, so the patch should ideally only add new lines.
61 Using #PACKAGE# substitution
63 In some rare cases, the name of the library varies between architec‐
64 tures. To avoid hardcoding the name of the package in the symbols
65 file, you can use the marker #PACKAGE#. It will be replaced by the real
66 package name during installation of the symbols files. Contrary to the
67 #MINVER# marker, #PACKAGE# will never appear in a symbols file inside a
68 binary package.
69 Using symbol tags
71 Symbol tagging is useful for marking symbols that are special in some
72 way. Any symbol can have an arbitrary number of tags associated with
73 it. While all tags are parsed and stored, only a some of them are
74 understood by dpkg-gensymbols and trigger special handling of the sym‐
75 bols. See subsection Standard symbol tags for reference of these tags.
76 Tag specification comes right before the symbol name (no whitespace is
78 allowed in between). It always starts with an opening bracket (, ends
79 with a closing bracket ) and must contain at least one tag. Multiple
80 tags are separated by the | character. Each tag can optionally have a
81 value which is separated form the tag name by the = character. Tag
82 names and values can be arbitrary strings except they cannot contain
83 any of the special ) | = characters. Symbol names following a tag spec‐
84 ification can optionally be quoted with either ' or " characters to
85 allow whitespaces in them. However, if there are no tags specified for
86 the symbol, quotes are treated as part of the symbol name which contin‐
87 ues up until the first space.
88 (tag1=i am marked|tag name with space)"tagged quoted symbol"@Base 1.0
90 (optional)tagged_unquoted_symbol@Base 1.0 1
91 untagged_symbol@Base 1.0
92 The first symbol in the example is named tagged quoted symbol and has
94 two tags: tag1 with value i am marked and tag name with space that has
95 no value. The second symbol named tagged_unquoted_symbol is only tagged
96 with the tag named optional. The last symbol is an example of the nor‐
97 mal untagged symbol.
98 Since symbol tags are an extension of the deb-symbols(5) format, they
100 can only be part of the symbols files used in source packages (those
101 files should then be seen as templates used to build the symbols files
102 that are embedded in binary packages). When dpkg-gensymbols is called
103 without the -t option, it will output symbols files compatible to the
104 deb-symbols(5) format: it fully processes symbols according to the
105 requirements of their standard tags and strips all tags from the out‐
106 put. On the contrary, in template mode (-t) all symbols and their tags
107 (both standard and unknown ones) are kept in the output and are written
108 in their orignal form as they were loaded.
109 Standard symbol tags
111 optional
112 A symbol marked as optional can disappear from the library at
113 any time and that will never cause dpkg-gensymbols to fail. How‐
114 ever, disappeared optional symbols will continuously appear as
115 MISSING in the diff in each new package revision. This behav‐
116 iour serves as a reminder for the maintainer that such a symbol
117 needs to be removed from the symbol file or readded to the
118 library. When the optional symbol, which was previously declared
119 as MISSING, suddenly reappears in the next revision, it will be
120 upgraded back to the "existing" status with its minimum version
121 unchanged.
122 This tag is useful for symbols which are private where their
124 disappearance do not cause ABI breakage. For example, most of
125 C++ template instantiations fall into this category. Like any
126 other tag, this one may also have an arbitrary value: it could
127 be used to indicate why the symbol is considered optional.
128 arch=architecture list
130 This tag allows to restrict the set of architectures where the
131 symbol is supposed to exist. When the symbols list is updated
132 with the symbols discovered in the library, all arch-specific
133 symbols which do not concern the current host architecture are
134 treated as if they did not exist. If an arch-specific symbol
135 matching the current host architecture does not exist in the
136 library, normal procedures for missing symbols apply and it may
137 cause dpkg-gensymbols to fail. On the other hand, if the arch-
138 specific symbol is found when it was not supposed to exist
139 (because the current host architecture is not listed in the
140 tag), it is made arch neutral (i.e. the arch tag is dropped and
141 the symbol will appear in the diff due to this change), but it
142 is not considered as new.
143 When operating in the default non-template mode, among arch-spe‐
145 cific symbols only those that match the current host architec‐
146 ture are written to the symbols file. On the contrary, all arch-
147 specific symbols (including those from foreign arches) are
148 always written to the symbol file when operating in template
149 mode.
150 The format of architecture list is the same as the one used in
152 the Build-Depends field of debian/control (except the enclosing
153 square brackets []). For example, the first symbol from the list
154 below will be considered only on alpha, amd64, kfreebsd-amd64
155 and ia64 architectures while the second one anywhere except on
156 armel.
157 (arch=alpha amd64 kfreebsd-amd64 ia64)a_64bit_specific_sym‐
159 bol@Base 1.0
160 (arch=!armel)symbol_armel_does_not_have@Base 1.0
161 ignore-blacklist
163 dpkg-gensymbols has an internal blacklist of symbols that should
164 not appear in symbols files as they are usually only side-
165 effects of implementation details of the toolchain. If for some
166 reason, you really want one of those symbols to be included in
167 the symbols file, you should tag the symbol with ignore-black‐
168 list. It can be necessary for some low level toolchain libraries
169 like libgcc.
170 Using includes
172 When the set of exported symbols differ between architectures, it may
173 become inefficient to use a single symbol file. In those cases, an
174 include directive may prove to be useful in a couple of ways:
175 · You can factorize the common part in some external file and
177 include that file in your package.symbols.arch file by using an
178 include directive like this:
179 #include "packages.symbols.common"
181 · The include directive may also be tagged like any symbol:
183 (tag|..|tagN)#include "file_to_include"
185 As a result, all symbols included from file_to_include will be
187 considered to be tagged with tag .. tagN by default. You can use
188 this feature to create a common package.symbols file which
189 includes architecture specific symbol files:
190 common_symbol1@Base 1.0
192 (arch=amd64 ia64 alpha)#include "package.symbols.64bit"
193 (arch=!amd64 !ia64 !alpha)#include "package.symbols.32bit"
194 common_symbol2@Base 1.0
195 The symbols files are read line by line, and include directives are
197 processed as soon as they are encountered. This means that the content
198 of the included file can override any content that appeared before the
199 include directive and that any content after the directive can override
200 anything contained in the included file. Any symbol (or even another
201 #include directive) in the included file can specify additional tags or
202 override values of the inherited tags in its tag specification. How‐
203 ever, there is no way for the symbol to remove any of the inherited
204 tags.
205 An included file can repeat the header line containing the SONAME of
207 the library. In that case, it overrides any header line previously
208 read. However, in general it's best to avoid duplicating header lines.
209 One way to do it is the following:
210 #include "libsomething1.symbols.common"
212 arch_specific_symbol@Base 1.0
213 Using wildcards with versioned symbols
215 Well maintained libraries have versioned symbols where each version
216 corresponds to the upstream version where the symbol got added. If
217 that's the case, it's possible to write a symbols file with wildcard
218 entries like "*@GLIBC_2.0" that would match any symbol associated to
219 the version GLIBC_2.0. It's still possible to include specific symbols
220 in the file, they'll take precedence over any matching wildcard entry.
221 An example:
222 libc.so.6 libc6 #MINVER#
224 *@GLIBC_2.0 2.0
225 [...]
226 *@GLIBC_2.7 2.7
227 access@GLIBC_2.0 2.2
228 The symbol access@GLIBC_2.0 will lead to a minimal dependency on libc6
230 version 2.2 despite the wildcard entry *@GLIBC_2.0 which associates
231 symbols versioned as GLIBC_2.0 with the minimal version 2.0.
232 Note that using wildcards means that dpkg-gensymbols can't check for
234 symbols that might have disappeared and can't generate a diff between
235 the maintainer-supplied symbols file and the generated one in the
236 binary package.
237 Good library management
239 A well-maintained library has the following features:
240 · its API is stable (public symbols are never dropped, only new pub‐
242 lic symbols are added) and changes in incompatible ways only when
243 the SONAME changes;
244 · ideally, it uses symbol versioning to achieve ABI stability despite
246 internal changes and API extension;
247 · it doesn't export private symbols (such symbols can be tagged
249 optional as workaround).
250 While maintaining the symbols file, it's easy to notice appearance and
252 disappearance of symbols. But it's more difficult to catch incompatible
253 API and ABI change. Thus the maintainer should read thoroughly the
254 upstream changelog looking for cases where the rules of good library
255 management have been broken. If potential problems are discovered, the
256 upstream author should be notified as an upstream fix is always better
257 than a Debian specific work-around.
258
260 -Ppackage-build-dir
261 Scan package-build-dir instead of debian/tmp.
262 -ppackage
264 Define the package name. Required if more than one binary pack‐
265 age is listed in debian/control (or if there's no debian/control
266 file).
267 -vversion
269 Define the package version. Defaults to the version extracted
270 from debian/changelog. Required if called outside of a source
271 package tree.
272 -elibrary-file
274 Only analyze libraries explicitly listed instead of finding all
275 public libraries. You can use a regular expression in library-
276 file to match multiple libraries with a single argument (other‐
277 wise you need multiple -e).
278 -Ifilename
280 Use filename as reference file to generate the symbols file that
281 is integrated in the package itself.
282 -O Print the generated symbols file to standard output, rather than
284 being stored in the package build tree.
285 -Ofilename
287 Store the generated symbols file as filename. If filename is
288 pre-existing, its content is used as basis for the generated
289 symbols file. You can use this feature to update a symbols file
290 so that it matches a newer upstream version of your library.
291 -t Write the symbol file in template mode rather than the format
293 compatible with deb-symbols(5). The main difference is that in
294 the template mode symbol names and tags are written in their
295 original form contrary to the post-processed symbol names with
296 tags stripped in the compatibility mode. Moreover, some symbols
297 might be omitted when writing a standard deb-symbols(5) file
298 (according to the tag processing rules) while all symbols are
299 always written to the symbol file template.
300 -c[0-4]
302 Define the checks to do when comparing the generated symbols
303 file with the file used as starting point. By default the level
304 is 1. Increasing levels do more checks and include all checks
305 of lower levels. Level 0 disables all checks. Level 1 fails if
306 some symbols have disappeared. Level 2 fails if some new symbols
307 have been introduced. Level 3 fails if some libraries have dis‐
308 appeared. Level 4 fails if some libraries have been introduced.
309 This value can be overridden by the environment variable
311 DPKG_GENSYMBOLS_CHECK_LEVEL.
312 -d Enable debug mode. Numerous messages are displayed to explain
314 what dpkg-gensymbols does.
315 -h, --help
317 Show the usage message and exit.
318 --version
320 Show the version and exit.
321
323 http://people.redhat.com/drepper/symbol-versioning
324 http://people.redhat.com/drepper/goodpractice.pdf
325 http://people.redhat.com/drepper/dsohowto.pdf
326 deb-symbols(5), dpkg-shlibdeps(1).
327
329 Copyright © 2007-2009 Raphaël Hertzog
330 This is free software; see the GNU General Public Licence version 2 or
332 later for copying conditions. There is NO WARRANTY.
333Debian Project 2009-08-07 dpkg-gensymbols(1)