Commit | Line | Data |
---|---|---|
1479465f GJ |
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 | .TH dpkg\-gensymbols 1 "%RELEASE_DATE%" "%VERSION%" "dpkg suite" | |
21 | .nh | |
22 | .SH NAME | |
23 | dpkg\-gensymbols \- generate symbols files (shared library dependency information) | |
24 | . | |
25 | .SH SYNOPSIS | |
26 | .B dpkg\-gensymbols | |
27 | .RI [ option ...] | |
28 | . | |
29 | .SH DESCRIPTION | |
30 | .B dpkg\-gensymbols | |
31 | scans a temporary build tree (debian/tmp by default) looking for libraries | |
32 | and generates a \fIsymbols\fR file describing them. This file, if | |
33 | non-empty, is then installed in the DEBIAN subdirectory of the build tree | |
34 | so that it ends up included in the control information of the package. | |
35 | .P | |
36 | When generating those files, it uses as input some symbols files | |
37 | provided by the maintainer. It looks for the following files (and uses the | |
38 | first that is found): | |
39 | .IP • 4 | |
40 | debian/\fIpackage\fR.symbols.\fIarch\fR | |
41 | .IP • 4 | |
42 | debian/symbols.\fIarch\fR | |
43 | .IP • 4 | |
44 | debian/\fIpackage\fR.symbols | |
45 | .IP • 4 | |
46 | debian/symbols | |
47 | .P | |
48 | The main interest of those files is to provide the minimal version | |
49 | associated to each symbol provided by the libraries. Usually it | |
50 | corresponds to the first version of that package that provided the symbol, | |
51 | but it can be manually incremented by the maintainer if the ABI of the | |
52 | symbol is extended without breaking backwards compatibility. It's the | |
53 | responsibility of the maintainer to keep those files up-to-date and | |
54 | accurate, but \fBdpkg\-gensymbols\fR helps with that. | |
55 | .P | |
56 | When the generated symbols files differ from the maintainer supplied | |
57 | one, \fBdpkg\-gensymbols\fR will print a diff between the two versions. | |
58 | Furthermore if the difference is too significant, it will even fail (you | |
59 | can customize how much difference you can tolerate, see the \fB\-c\fR | |
60 | option). | |
61 | .SH MAINTAINING SYMBOLS FILES | |
62 | The symbols files are really useful only if they reflect the evolution of | |
63 | the package through several releases. Thus the maintainer has to update | |
64 | them every time that a new symbol is added so that its associated minimal | |
65 | version matches reality. | |
66 | The diffs contained in the build logs can be used as a starting point, | |
67 | but the maintainer, additionally, has to make sure that the behaviour | |
68 | of those symbols has not changed in a way that would make anything | |
69 | using those symbols and linking against the new version, stop working | |
70 | with the old version. | |
71 | In most cases, the diff applies directly to the | |
72 | debian/\fIpackage\fR.symbols file. That said, further tweaks are usually | |
73 | needed: it's recommended for example to drop the Debian revision | |
74 | from the minimal version so that backports with a lower version number | |
75 | but the same upstream version still satisfy the generated dependencies. | |
76 | If the Debian revision can't be dropped because the symbol really got | |
77 | added by the Debian specific change, then one should suffix the version | |
78 | with ‘\fB~\fP’. | |
79 | .P | |
80 | Before applying any patch to the symbols file, the maintainer should | |
81 | double-check that it's sane. Public symbols are not supposed to disappear, | |
82 | so the patch should ideally only add new lines. | |
83 | .P | |
84 | Note that you can put comments in symbols files: any line with ‘#’ as | |
85 | the first character is a comment except if it starts with ‘#include’ | |
86 | (see section \fBUsing includes\fP). | |
87 | Lines starting with ‘#MISSING:’ are special comments documenting | |
88 | symbols that have disappeared. | |
89 | .P | |
90 | Do not forget to check if old symbol versions need to be increased. | |
91 | There is no way \fBdpkg\-gensymbols\fP can warn about this. Blindly | |
92 | applying the diff or assuming there is nothing to change if there is | |
93 | no diff, without checking for such changes, can lead to packages with | |
94 | loose dependencies that claim they can work with older packages they | |
95 | cannot work with. This will introduce hard to find bugs with (partial) | |
96 | upgrades. | |
97 | .SS Using #PACKAGE# substitution | |
98 | .P | |
99 | In some rare cases, the name of the library varies between architectures. | |
100 | To avoid hardcoding the name of the package in the symbols file, you can | |
101 | use the marker \fI#PACKAGE#\fR. It will be replaced by the real package | |
102 | name during installation of the symbols files. Contrary to the | |
103 | \fI#MINVER#\fR marker, \fI#PACKAGE#\fR will never appear in a symbols file | |
104 | inside a binary package. | |
105 | .SS Using symbol tags | |
106 | .P | |
107 | Symbol tagging is useful for marking symbols that are special in some way. Any | |
108 | symbol can have an arbitrary number of tags associated with it. While all tags are | |
109 | parsed and stored, only some of them are understood by | |
110 | \fBdpkg\-gensymbols\fR and trigger special handling of the symbols. See | |
111 | subsection \fBStandard symbol tags\fR for reference of these tags. | |
112 | .P | |
113 | Tag specification comes right before the symbol name (no whitespace is allowed | |
114 | in between). It always starts with an opening bracket \fB(\fR, ends with a | |
115 | closing bracket \fB)\fR and must contain at least one tag. Multiple tags are | |
116 | separated by the \fB|\fR character. Each tag can optionally have a value which | |
117 | is separated form the tag name by the \fB=\fR character. Tag names and values | |
118 | can be arbitrary strings except they cannot contain any of the special \fB)\fR | |
119 | \fB|\fR \fB=\fR characters. Symbol names following a tag specification can | |
120 | optionally be quoted with either \fB'\fR or \fB"\fR characters to allow | |
121 | whitespaces in them. However, if there are no tags specified for the symbol, | |
122 | quotes are treated as part of the symbol name which continues up until the | |
123 | first space. | |
124 | .P | |
125 | (tag1=i am marked|tag name with space)"tagged quoted symbol"@Base 1.0 | |
126 | (optional)tagged_unquoted_symbol@Base 1.0 1 | |
127 | untagged_symbol@Base 1.0 | |
128 | .P | |
129 | The first symbol in the example is named \fItagged quoted symbol\fR and has two | |
130 | tags: \fItag1\fR with value \fIi am marked\fR and \fItag name with space\fR | |
131 | that has no value. The second symbol named \fItagged_unquoted_symbol\fR is | |
132 | only tagged with the tag named \fIoptional\fR. The last symbol is an | |
133 | example of the normal untagged symbol. | |
134 | .P | |
135 | Since symbol tags are an extension of the \fBdeb\-symbols\fP(5) format, they | |
136 | can only be part of the symbols files used in source packages (those files | |
137 | should then be seen as templates used to build the symbols files that are | |
138 | embedded in binary packages). When | |
139 | \fBdpkg\-gensymbols\fR is called without the \fB\-t\fP option, it will | |
140 | output symbols files compatible to the \fBdeb\-symbols\fP(5) format: | |
141 | it fully processes symbols according to the requirements of their standard tags | |
142 | and strips all tags from the output. On the contrary, in template mode | |
143 | (\fB\-t\fP) all symbols and their tags (both standard and unknown ones) | |
144 | are kept in the output and are written in their original form as they were | |
145 | loaded. | |
146 | .SS Standard symbol tags | |
147 | .TP | |
148 | .B optional | |
149 | A symbol marked as optional can disappear from the library at any time and that | |
150 | will never cause \fBdpkg\-gensymbols\fR to fail. However, disappeared optional | |
151 | symbols will continuously appear as MISSING in the diff in each new package | |
152 | revision. This behaviour serves as a reminder for the maintainer that such a | |
153 | symbol needs to be removed from the symbol file or readded to the library. When | |
154 | the optional symbol, which was previously declared as MISSING, suddenly | |
155 | reappears in the next revision, it will be upgraded back to the “existing” | |
156 | status with its minimum version unchanged. | |
157 | ||
158 | This tag is useful for symbols which are private where their disappearance do | |
159 | not cause ABI breakage. For example, most of C++ template instantiations fall | |
160 | into this category. Like any other tag, this one may also have an arbitrary | |
161 | value: it could be used to indicate why the symbol is considered optional. | |
162 | .TP | |
163 | .B arch=\fIarchitecture-list\fR | |
164 | .TQ | |
165 | .B arch\-bits=\fIarchitecture-bits\fR | |
166 | .TQ | |
167 | .B arch\-endian=\fIarchitecture-endianness\fR | |
168 | These tags allow one to restrict the set of architectures where the symbol | |
169 | is supposed to exist. The \fBarch\-bits\fP and \fBarch\-endian\fP tags | |
170 | are supported since dpkg 1.18.0. When the symbols list is updated with | |
171 | the symbols | |
172 | discovered in the library, all arch-specific symbols which do not concern | |
173 | the current host architecture are treated as if they did not exist. If an | |
174 | arch-specific symbol matching the current host architecture does not exist | |
175 | in the library, normal procedures for missing symbols apply and it may | |
176 | cause \fBdpkg\-gensymbols\fR to fail. On the other hand, if the | |
177 | arch-specific symbol is found when it was not supposed to exist (because | |
178 | the current host architecture is not listed in the tag or does not match | |
179 | the endianness and bits), it is made arch neutral (i.e. the arch, arch-bits | |
180 | and arch-endian tags are dropped and the symbol will appear in the diff due | |
181 | to this change), but it is not considered as new. | |
182 | ||
183 | When operating in the default non-template mode, among arch-specific symbols | |
184 | only those that match the current host architecture are written to the | |
185 | symbols file. On the contrary, all arch-specific symbols (including those | |
186 | from foreign arches) are always written to the symbol file when operating | |
187 | in template mode. | |
188 | ||
189 | The format of \fIarchitecture-list\fR is the same as the one used in the | |
190 | \fBBuild\-Depends\fP field of \fIdebian/control\fR (except the enclosing | |
191 | square brackets []). For example, the first symbol from the list below | |
192 | will be considered only on alpha, any\-amd64 and ia64 architectures, | |
193 | the second only on linux architectures, while the third one anywhere | |
194 | except on armel. | |
195 | ||
196 | (arch=alpha any\-amd64 ia64)64bit_specific_symbol@Base 1.0 | |
197 | (arch=linux\-any)linux_specific_symbol@Base 1.0 | |
198 | (arch=!armel)symbol_armel_does_not_have@Base 1.0 | |
199 | ||
200 | The \fIarchitecture-bits\fP is either \fB32\fP or \fB64\fP. | |
201 | ||
202 | (arch-bits=32)32bit_specific_symbol@Base 1.0 | |
203 | (arch-bits=64)64bit_specific_symbol@Base 1.0 | |
204 | ||
205 | The \fIarchitecture-endianness\fP is either \fBlittle\fP or \fBbig\fP. | |
206 | ||
207 | (arch-endian=little)little_endian_specific_symbol@Base 1.0 | |
208 | (arch-endian=big)big_endian_specific_symbol@Base 1.0 | |
209 | ||
210 | Multiple restrictions can be chained. | |
211 | ||
212 | (arch-bits=32|arch-endian=little)32bit_le_symbol@Base 1.0 | |
213 | .TP | |
214 | .B ignore\-blacklist | |
215 | dpkg\-gensymbols has an internal blacklist of symbols that should not | |
216 | appear in symbols files as they are usually only side-effects of | |
217 | implementation details of the toolchain. If for some reason, you really | |
218 | want one of those symbols to be included in the symbols file, you should | |
219 | tag the symbol with \fBignore\-blacklist\fP. It can be necessary for | |
220 | some low level toolchain libraries like libgcc. | |
221 | .TP | |
222 | .B c++ | |
223 | Denotes \fIc++\fR symbol pattern. See \fBUsing symbol patterns\fR subsection | |
224 | below. | |
225 | .TP | |
226 | .B symver | |
227 | Denotes \fIsymver\fR (symbol version) symbol pattern. See \fBUsing symbol | |
228 | patterns\fR subsection below. | |
229 | .TP | |
230 | .B regex | |
231 | Denotes \fIregex\fR symbol pattern. See \fBUsing symbol patterns\fR subsection | |
232 | below. | |
233 | .SS Using symbol patterns | |
234 | .P | |
235 | Unlike a standard symbol specification, a pattern may cover multiple real | |
236 | symbols from the library. \fBdpkg\-gensymbols\fR will attempt to match each | |
237 | pattern against each real symbol that does \fInot\fR have a specific symbol | |
238 | counterpart defined in the symbol file. Whenever the first matching pattern is | |
239 | found, all its tags and properties will be used as a basis specification of the | |
240 | symbol. If none of the patterns matches, the symbol will be considered as new. | |
241 | ||
242 | A pattern is considered lost if it does not match any symbol in the library. By | |
243 | default this will trigger a \fBdpkg\-gensymbols\fP failure under \fB\-c1\fP or | |
244 | higher level. However, if the failure is undesired, the pattern may be marked | |
245 | with the \fIoptional\fR tag. Then if the pattern does not match anything, it | |
246 | will only appear in the diff as MISSING. Moreover, like any symbol, the pattern | |
247 | may be limited to the specific architectures with the \fIarch\fR tag. Please | |
248 | refer to \fBStandard symbol tags\fR subsection above for more information. | |
249 | ||
250 | Patterns are an extension of the \fBdeb\-symbols\fP(5) format hence they are | |
251 | only valid in symbol file templates. Pattern specification syntax is not any | |
252 | different from the one of a specific symbol. However, symbol name part of the | |
253 | specification serves as an expression to be matched against \fIname@version\fR | |
254 | of the real symbol. In order to distinguish among different pattern types, a | |
255 | pattern will typically be tagged with a special tag. | |
256 | ||
257 | At the moment, \fBdpkg\-gensymbols\fR supports three basic pattern types: | |
258 | .TP 3 | |
259 | .B c++ | |
260 | This pattern is denoted by the \fIc++\fR tag. It matches only C++ symbols by | |
261 | their demangled symbol name (as emitted by \fBc++filt\fR(1) utility). This | |
262 | pattern is very handy for matching symbols which mangled names might vary | |
263 | across different architectures while their demangled names remain the same. One | |
264 | group of such symbols is \fInon\-virtual thunks\fR which have architecture | |
265 | specific offsets embedded in their mangled names. A common instance of this | |
266 | case is a virtual destructor which under diamond inheritance needs a | |
267 | non-virtual thunk symbol. For example, even if _ZThn8_N3NSB6ClassDD1Ev@Base on | |
268 | 32bit architectures will probably be _ZThn16_N3NSB6ClassDD1Ev@Base on 64bit | |
269 | ones, it can be matched with a single \fIc++\fR pattern: | |
270 | ||
271 | libdummy.so.1 libdummy1 #MINVER# | |
272 | [...] | |
273 | (c++)"non\-virtual thunk to NSB::ClassD::~ClassD()@Base" 1.0 | |
274 | [...] | |
275 | ||
276 | The demangled name above can be obtained by executing the following command: | |
277 | ||
278 | $ echo '_ZThn8_N3NSB6ClassDD1Ev@Base' | c++filt | |
279 | ||
280 | Please note that while mangled name is unique in the library by definition, | |
281 | this is not necessarily true for demangled names. A couple of distinct real | |
282 | symbols may have the same demangled name. For example, that's the case with | |
283 | non-virtual thunk symbols in complex inheritance configurations or with most | |
284 | constructors and destructors (since g++ typically generates two real symbols | |
285 | for them). However, as these collisions happen on the ABI level, they should | |
286 | not degrade quality of the symbol file. | |
287 | .TP | |
288 | .B symver | |
289 | This pattern is denoted by the \fIsymver\fR tag. Well maintained libraries have | |
290 | versioned symbols where each version corresponds to the upstream version where | |
291 | the symbol got added. If that's the case, you can use a \fIsymver\fR pattern to | |
292 | match any symbol associated to the specific version. For example: | |
293 | ||
294 | libc.so.6 libc6 #MINVER# | |
295 | (symver)GLIBC_2.0 2.0 | |
296 | [...] | |
297 | (symver)GLIBC_2.7 2.7 | |
298 | access@GLIBC_2.0 2.2 | |
299 | ||
300 | All symbols associated with versions GLIBC_2.0 and GLIBC_2.7 will lead to | |
301 | minimal version of 2.0 and 2.7 respectively with the exception of the symbol | |
302 | access@GLIBC_2.0. The latter will lead to a minimal dependency on libc6 version | |
303 | 2.2 despite being in the scope of the "(symver)GLIBC_2.0" pattern because | |
304 | specific symbols take precedence over patterns. | |
305 | ||
306 | Please note that while old style wildcard patterns (denoted by "*@version" in | |
307 | the symbol name field) are still supported, they have been deprecated by new | |
308 | style syntax "(symver|optional)version". For example, "*@GLIBC_2.0 2.0" should | |
309 | be written as "(symver|optional)GLIBC_2.0 2.0" if the same behaviour is needed. | |
310 | .TP | |
311 | .B regex | |
312 | Regular expression patterns are denoted by the \fIregex\fR tag. They match by | |
313 | the perl regular expression specified in the symbol name field. A regular | |
314 | expression is matched as it is, therefore do not forget to start it with the | |
315 | \fI^\fR character or it may match any part of the real symbol | |
316 | \fIname@version\fR string. For example: | |
317 | ||
318 | libdummy.so.1 libdummy1 #MINVER# | |
319 | (regex)"^mystack_.*@Base$" 1.0 | |
320 | (regex|optional)"private" 1.0 | |
321 | ||
322 | Symbols like "mystack_new@Base", "mystack_push@Base", "mystack_pop@Base" etc. | |
323 | will be matched by the first pattern while e.g. "ng_mystack_new@Base" won't. | |
324 | The second pattern will match all symbols having the string "private" in their | |
325 | names and matches will inherit \fIoptional\fR tag from the pattern. | |
326 | .P | |
327 | Basic patterns listed above can be combined where it makes sense. In that case, | |
328 | they are processed in the order in which the tags are specified. For example, | |
329 | both | |
330 | ||
331 | (c++|regex)"^NSA::ClassA::Private::privmethod\\d\\(int\\)@Base" 1.0 | |
332 | (regex|c++)N3NSA6ClassA7Private11privmethod\\dEi@Base 1.0 | |
333 | ||
334 | will match symbols "_ZN3NSA6ClassA7Private11privmethod1Ei@Base" and | |
335 | "_ZN3NSA6ClassA7Private11privmethod2Ei@Base". When matching the first pattern, | |
336 | the raw symbol is first demangled as C++ symbol, then the demangled name is | |
337 | matched against the regular expression. On the other hand, when matching the | |
338 | second pattern, regular expression is matched against the raw symbol name, then | |
339 | the symbol is tested if it is C++ one by attempting to demangle it. A failure | |
340 | of any basic pattern will result in the failure of the whole pattern. | |
341 | Therefore, for example, "__N3NSA6ClassA7Private11privmethod\\dEi@Base" will not | |
342 | match either of the patterns because it is not a valid C++ symbol. | |
343 | ||
344 | In general, all patterns are divided into two groups: aliases (basic \fIc++\fR | |
345 | and \fIsymver\fR) and generic patterns (\fIregex\fR, all combinations of | |
346 | multiple basic patterns). Matching of basic alias-based patterns is fast (O(1)) | |
347 | while generic patterns are O(N) (N - generic pattern count) for each symbol. | |
348 | Therefore, it is recommended not to overuse generic patterns. | |
349 | ||
350 | When multiple patterns match the same real symbol, aliases (first \fIc++\fR, | |
351 | then \fIsymver\fR) are preferred over generic patterns. Generic patterns are | |
352 | matched in the order they are found in the symbol file template until the first | |
353 | success. Please note, however, that manual reordering of template file entries | |
354 | is not recommended because \fBdpkg\-gensymbols\fR generates diffs based on the | |
355 | alphanumerical order of their names. | |
356 | .SS Using includes | |
357 | .P | |
358 | When the set of exported symbols differ between architectures, it may become | |
359 | inefficient to use a single symbol file. In those cases, an include directive | |
360 | may prove to be useful in a couple of ways: | |
361 | .IP • 4 | |
362 | You can factorize the common part in some external file | |
363 | and include that file in your \fIpackage\fR.symbols.\fIarch\fR file by | |
364 | using an include directive like this: | |
365 | ||
366 | #include "\fIpackages\fR.symbols.common" | |
367 | .IP • | |
368 | The include directive may also be tagged like any symbol: | |
369 | ||
370 | (tag|...|tagN)#include "file-to-include" | |
371 | ||
372 | As a result, all symbols included from \fIfile-to-include\fR will be considered | |
373 | to be tagged with \fItag\fR ... \fItagN\fR by default. You can use this feature | |
374 | to create a common \fIpackage\fR.symbols file which includes architecture | |
375 | specific symbol files: | |
376 | ||
377 | common_symbol1@Base 1.0 | |
378 | (arch=amd64 ia64 alpha)#include "package.symbols.64bit" | |
379 | (arch=!amd64 !ia64 !alpha)#include "package.symbols.32bit" | |
380 | common_symbol2@Base 1.0 | |
381 | .P | |
382 | The symbols files are read line by line, and include directives are processed | |
383 | as soon as they are encountered. This means that the content of the included | |
384 | file can override any content that appeared before the include directive and | |
385 | that any content after the directive can override anything contained in the | |
386 | included file. Any symbol (or even another #include directive) in the included | |
387 | file can specify additional tags or override values of the inherited tags in | |
388 | its tag specification. However, there is no way for the symbol to remove | |
389 | any of the inherited tags. | |
390 | .P | |
391 | An included file can repeat the header line containing the SONAME of the | |
392 | library. In that case, it overrides any header line previously read. | |
393 | However, in general it's best to avoid duplicating header lines. One way | |
394 | to do it is the following: | |
395 | .PP | |
396 | #include "libsomething1.symbols.common" | |
397 | arch_specific_symbol@Base 1.0 | |
398 | .SS Good library management | |
399 | .P | |
400 | A well-maintained library has the following features: | |
401 | .IP • 4 | |
402 | its API is stable (public symbols are never dropped, only new public | |
403 | symbols are added) and changes in incompatible ways only when the SONAME | |
404 | changes; | |
405 | .IP • 4 | |
406 | ideally, it uses symbol versioning to achieve ABI stability despite | |
407 | internal changes and API extension; | |
408 | .IP • 4 | |
409 | it doesn't export private symbols (such symbols can be tagged optional as | |
410 | workaround). | |
411 | .P | |
412 | While maintaining the symbols file, it's easy to notice appearance and | |
413 | disappearance of symbols. But it's more difficult to catch incompatible | |
414 | API and ABI change. Thus the maintainer should read thoroughly the | |
415 | upstream changelog looking for cases where the rules of good library | |
416 | management have been broken. If potential problems are discovered, | |
417 | the upstream author should be notified as an upstream fix is always better | |
418 | than a Debian specific work-around. | |
419 | .SH OPTIONS | |
420 | .TP | |
421 | .BI \-P package-build-dir | |
422 | Scan \fIpackage-build-dir\fR instead of debian/tmp. | |
423 | .TP | |
424 | .BI \-p package | |
425 | Define the package name. Required if more than one binary package is listed in | |
426 | debian/control (or if there's no debian/control file). | |
427 | .TP | |
428 | .BI \-v version | |
429 | Define the package version. Defaults to the version extracted from | |
430 | debian/changelog. Required if called outside of a source package tree. | |
431 | .TP | |
432 | .BI \-e library-file | |
433 | Only analyze libraries explicitly listed instead of finding all public | |
434 | libraries. You can use shell patterns used for pathname expansions (see | |
435 | the \fBFile::Glob\fP(3perl) manual page for details) in \fIlibrary-file\fR | |
436 | to match multiple libraries with a single argument (otherwise you need | |
437 | multiple \fB\-e\fR). | |
438 | .TP | |
439 | .BI \-I filename | |
440 | Use \fIfilename\fR as reference file to generate the symbols file | |
441 | that is integrated in the package itself. | |
442 | .TP | |
443 | .BR \-O [\fIfilename\fP] | |
444 | Print the generated symbols file to standard output or to \fIfilename\fR | |
445 | if specified, rather than to | |
446 | .B debian/tmp/DEBIAN/symbols | |
447 | (or | |
448 | .IB package-build-dir /DEBIAN/symbols | |
449 | if | |
450 | .B \-P | |
451 | was used). If \fIfilename\fR is pre-existing, its contents are used as | |
452 | basis for the generated symbols file. | |
453 | You can use this feature to update a symbols file so that it matches a | |
454 | newer upstream version of your library. | |
455 | .TP | |
456 | .BI \-t | |
457 | Write the symbol file in template mode rather than the format compatible with | |
458 | \fBdeb\-symbols\fP(5). The main difference is that in the template mode symbol | |
459 | names and tags are written in their original form contrary to the | |
460 | post-processed symbol names with tags stripped in the compatibility mode. | |
461 | Moreover, some symbols might be omitted when writing a standard | |
462 | \fBdeb\-symbols\fP(5) file (according to the tag processing rules) while all | |
463 | symbols are always written to the symbol file template. | |
464 | .TP | |
465 | .BI \-c [0-4] | |
466 | Define the checks to do when comparing the generated symbols file with the | |
467 | template file used as starting point. By default the level is 1. Increasing | |
468 | levels do more checks and include all checks of lower levels. Level 0 never | |
469 | fails. Level 1 fails if some symbols have disappeared. Level 2 fails if some | |
470 | new symbols have been introduced. Level 3 fails if some libraries have | |
471 | disappeared. Level 4 fails if some libraries have been introduced. | |
472 | ||
473 | This value can be overridden by the environment variable | |
474 | .BR DPKG_GENSYMBOLS_CHECK_LEVEL . | |
475 | .TP | |
476 | .BI \-q | |
477 | Keep quiet and never generate a diff between generated symbols file and the | |
478 | template file used as starting point or show any warnings about new/lost | |
479 | libraries or new/lost symbols. This option only disables informational output | |
480 | but not the checks themselves (see \fB\-c\fP option). | |
481 | .TP | |
482 | .BI \-a arch | |
483 | Assume \fIarch\fR as host architecture when processing symbol files. Use this | |
484 | option to generate a symbol file or diff for any architecture provided its | |
485 | binaries are already available. | |
486 | .TP | |
487 | .BI \-d | |
488 | Enable debug mode. Numerous messages are displayed to explain what | |
489 | .B dpkg\-gensymbols | |
490 | does. | |
491 | .TP | |
492 | .BI \-V | |
493 | Enable verbose mode. The generated symbols file contains deprecated | |
494 | symbols as comments. Furthermore in template mode, pattern symbols | |
495 | are followed by comments listing real symbols that have matched the | |
496 | pattern. | |
497 | .TP | |
498 | .BR \-? ", " \-\-help | |
499 | Show the usage message and exit. | |
500 | .TP | |
501 | .BR \-\-version | |
502 | Show the version and exit. | |
503 | . | |
504 | .SH ENVIRONMENT | |
505 | .TP | |
506 | .B DPKG_GENSYMBOLS_CHECK_LEVEL | |
507 | Overrides the command check level, even if the \fB\-c\fP command-line | |
508 | argument was given (note that this goes against the common convention | |
509 | of command-line arguments having precedence over environment variables). | |
510 | .SH SEE ALSO | |
511 | .BR https://people.redhat.com/drepper/symbol\-versioning | |
512 | .br | |
513 | .BR https://people.redhat.com/drepper/goodpractice.pdf | |
514 | .br | |
515 | .BR https://people.redhat.com/drepper/dsohowto.pdf | |
516 | .br | |
517 | .BR deb\-symbols (5), | |
518 | .BR dpkg\-shlibdeps (1). |