Contents of /www/v2/pages/symbolfiles

<h2>Working with symbols files</h2>

<p>
Symbols files provide a way of tracking the exported symbols of a library, which helps in
fine-tuning the library dependencies generated by dpkg-shlibdeps and tracking (partially)
binary compatibility. You can find more information about the nature of symbols files
<a href="http://wiki.debian.org/Projects/ImprovedDpkgShlibdeps">here</a>.
</p>

<p>
This page explains how to use symbols files in packages maintained by the KDE team. It requires
that you use pkg-kde-tools, which provides all the mentioned pkgkde-* utilities.
</p>


<h3>Creating a symbols file</h3>

<p>
Let's suppose that you have a library package that is called libfoo1 and its version is 1.7.
First you need to create symbols file using pkgkde-gensymbols and then convert it to the format
used by pkgkde-symbolshelper. The following commands demonstrate how to do this.
</p>

<pre>
pkgkde-gensymbols -plibfoo1 -v1.7 -Osymbols.amd64 -edebian/libfoo1/usr/lib/libfoo.so.1
pkgkde-symbolshelper create -o debian/libfoo1.symbols -v 1.7 symbols.amd64
</pre>

<p>
The above commands should be invoked from the top level directory of your package's source after
having build the package and before cleaning (so that debian/libfoo1/usr/lib/libfoo.so.1 exists).
"symbols.amd64" is the filename of the intermediate symbols file that will be generated by
pkgkde-gensymbols. This filename must be in the format "name.architecture" or "name_architecture"
where "architecture" is the cpu architecture on which you have built this library package.
</p>


<h3>Updating a symbols file for a new library version</h3>

<p>
After building a new version of the library, symbols may have been added or removed, and in both
cases you need to check and update the symbols file. During the build, a diff between the current
symbols file and the one that should be there instead will be printed in the output. So, as a
first step, you need to save the build log in a file. You can do that by piping the output of your
build command through tee, for example:
</p>

<pre>
dpkg-buildpackage -j4 | tee buildlog
</pre>

<p>
In case you forgot to pipe the output and you want to avoid rebuilding, you can also copy-paste
the part of the output that contains the diff in new file.
</p>

<p>
After saving the diff in a file, you can patch the symbols file by executing:
</p>

<pre>
pkgkde-symbolshelper patch -p libfoo1 -v 1.8 &lt; buildlog
</pre>

<p>
Here we suppose that your libfoo1 package was updated to version 1.8, so "-v 1.8" in the command
is the switch to specify the new version.
</p>


<h3>Updating multiple symbols files at once</h3>

<p>
In source packages that provide multiple binary library packages (for example, kde4libs), it is
useful to have a method to patch all the symbol files at once, instead of patching each one
separately. pkgkde-symbolshelper offers a way to do this using the following command:
</p>

<pre>
pkgkde-symbolshelper batchpatch -v 1.8 buildlog
</pre>

<p>
where 1.8 is the new version of the source package and buildlog is the log file that contains
the appropriate diffs, as in the above section.
</p>


<h3>Handling missing symbols</h3>

<p>
In certain cases, some symbols may be marked as MISSING after updating the symbols file of a library
to a new version. This means that a function or class or global variable that was previously
exported for use by applications is not exported anymore. In general, removing a symbol from a
library causes binary incompatibility and in this case the SONAME of the library should be bumped.
However, there are some cases where it is safe to remove a symbol. To ensure that your library stays
binary compatible, you should manually check every missing symbol that you see to see if it is safe
to be removed or not. The most common cases where it is safe to remove a symbol are:
</p>

<ul>
    <li>The symbol is a function/class/variable that is only used internally in the library and does
not exist in any public header.</li>
    <li>The symbol is a private member of a class.</li>
    <li>The symbol is a virtual method that is already provided by the parent class.</li>
</ul>

<p>

<p>
If your library is C++, you will probably need a way to translate symbols to human-readable C++
identifiers. To do this, you can use the c++filt command, passing it as a first argument the symbol,
striping anything after the first @ character (usually symbols end with @Base). For example, if the
symbol is "_ZN10KAboutData10setVersionERK10QByteArray@Base", you can use it like this:
</p>

<pre>
$ c++filt _ZN10KAboutData10setVersionERK10QByteArray
KAboutData::setVersion(QByteArray const&amp;)
</pre>

<p>
After verifying that a symbol is safe to be removed, you can just remove the respective MISSING line
from the symbols file. If at least one symbol is not safe to be removed, then you should cleanup
all the MISSING lines from the symbols file <b>and</b> bump the SONAME of the library.
</p>


<h3>Notes on binary compatibility checking</h3>

<p>
Symbols checking provides a nice way of checking if a library stays binary compatible among releases.
However, you should note that symbols checking alone is not sufficient to ensure that a library
stays binary compatible. There can be other kinds of binary incompatible changes, such as changing
the sizes of classes/structs, adding/removing virtual methods, etc, which cannot be catched by
checking the symbols.
</p>

1	<h2>Working with symbols files</h2>
2
3	<p>
4	Symbols files provide a way of tracking the exported symbols of a library, which helps in
5	fine-tuning the library dependencies generated by dpkg-shlibdeps and tracking (partially)
6	binary compatibility. You can find more information about the nature of symbols files
7	<a href="http://wiki.debian.org/Projects/ImprovedDpkgShlibdeps">here</a>.
8	</p>
9
10	<p>
11	This page explains how to use symbols files in packages maintained by the KDE team. It requires
12	that you use pkg-kde-tools, which provides all the mentioned pkgkde-* utilities.
13	</p>
14
15
16	<h3>Creating a symbols file</h3>
17
18	<p>
19	Let's suppose that you have a library package that is called libfoo1 and its version is 1.7.
20	First you need to create symbols file using pkgkde-gensymbols and then convert it to the format
21	used by pkgkde-symbolshelper. The following commands demonstrate how to do this.
22	</p>
23
24	<pre>
25	pkgkde-gensymbols -plibfoo1 -v1.7 -Osymbols.amd64 -edebian/libfoo1/usr/lib/libfoo.so.1
26	pkgkde-symbolshelper create -o debian/libfoo1.symbols -v 1.7 symbols.amd64
27	</pre>
28
29	<p>
30	The above commands should be invoked from the top level directory of your package's source after
31	having build the package and before cleaning (so that debian/libfoo1/usr/lib/libfoo.so.1 exists).
32	"symbols.amd64" is the filename of the intermediate symbols file that will be generated by
33	pkgkde-gensymbols. This filename must be in the format "name.architecture" or "name_architecture"
34	where "architecture" is the cpu architecture on which you have built this library package.
35	</p>
36
37
38	<h3>Updating a symbols file for a new library version</h3>
39
40	<p>
41	After building a new version of the library, symbols may have been added or removed, and in both
42	cases you need to check and update the symbols file. During the build, a diff between the current
43	symbols file and the one that should be there instead will be printed in the output. So, as a
44	first step, you need to save the build log in a file. You can do that by piping the output of your
45	build command through tee, for example:
46	</p>
47
48	<pre>
49	dpkg-buildpackage -j4 \| tee buildlog
50	</pre>
51
52	<p>
53	In case you forgot to pipe the output and you want to avoid rebuilding, you can also copy-paste
54	the part of the output that contains the diff in new file.
55	</p>
56
57	<p>
58	After saving the diff in a file, you can patch the symbols file by executing:
59	</p>
60
61	<pre>
62	pkgkde-symbolshelper patch -p libfoo1 -v 1.8 < buildlog
63	</pre>
64
65	<p>
66	Here we suppose that your libfoo1 package was updated to version 1.8, so "-v 1.8" in the command
67	is the switch to specify the new version.
68	</p>
69
70
71	<h3>Updating multiple symbols files at once</h3>
72
73	<p>
74	In source packages that provide multiple binary library packages (for example, kde4libs), it is
75	useful to have a method to patch all the symbol files at once, instead of patching each one
76	separately. pkgkde-symbolshelper offers a way to do this using the following command:
77	</p>
78
79	<pre>
80	pkgkde-symbolshelper batchpatch -v 1.8 buildlog
81	</pre>
82
83	<p>
84	where 1.8 is the new version of the source package and buildlog is the log file that contains
85	the appropriate diffs, as in the above section.
86	</p>
87
88
89	<h3>Handling missing symbols</h3>
90
91	<p>
92	In certain cases, some symbols may be marked as MISSING after updating the symbols file of a library
93	to a new version. This means that a function or class or global variable that was previously
94	exported for use by applications is not exported anymore. In general, removing a symbol from a
95	library causes binary incompatibility and in this case the SONAME of the library should be bumped.
96	However, there are some cases where it is safe to remove a symbol. To ensure that your library stays
97	binary compatible, you should manually check every missing symbol that you see to see if it is safe
98	to be removed or not. The most common cases where it is safe to remove a symbol are:
99	</p>
100
101	<ul>
102	<li>The symbol is a function/class/variable that is only used internally in the library and does
103	not exist in any public header.</li>
104	<li>The symbol is a private member of a class.</li>
105	<li>The symbol is a virtual method that is already provided by the parent class.</li>
106	</ul>
107
108	<p>
109
110	<p>
111	If your library is C++, you will probably need a way to translate symbols to human-readable C++
112	identifiers. To do this, you can use the c++filt command, passing it as a first argument the symbol,
113	striping anything after the first @ character (usually symbols end with @Base). For example, if the
114	symbol is "_ZN10KAboutData10setVersionERK10QByteArray@Base", you can use it like this:
115	</p>
116
117	<pre>
118	$ c++filt _ZN10KAboutData10setVersionERK10QByteArray
119	KAboutData::setVersion(QByteArray const&)
120	</pre>
121
122	<p>
123	After verifying that a symbol is safe to be removed, you can just remove the respective MISSING line
124	from the symbols file. If at least one symbol is not safe to be removed, then you should cleanup
125	all the MISSING lines from the symbols file <b>and</b> bump the SONAME of the library.
126	</p>
127
128
129	<h3>Notes on binary compatibility checking</h3>
130
131	<p>
132	Symbols checking provides a nice way of checking if a library stays binary compatible among releases.
133	However, you should note that symbols checking alone is not sufficient to ensure that a library
134	stays binary compatible. There can be other kinds of binary incompatible changes, such as changing
135	the sizes of classes/structs, adding/removing virtual methods, etc, which cannot be catched by
136	checking the symbols.
137	</p>
138