rev 18631 - www/v2/pages

Mon Aug 9 13:40:40 UTC 2010

Author: gkiagia-guest
Date: 2010-08-09 13:40:27 +0000 (Mon, 09 Aug 2010)
New Revision: 18631

Added:
   www/v2/pages/symbolfiles
Modified:
   www/v2/pages/bottom
Log:
Add documentation about symbol files.


Modified: www/v2/pages/bottom
===================================================================

--- www/v2/pages/bottom	2010-08-09 08:31:49 UTC (rev 18630)
+++ www/v2/pages/bottom	2010-08-09 13:40:27 UTC (rev 18631)
@@ -55,6 +55,7 @@
 				<li><a href="pkgkdesvn.html">pkg-kde SVN quick guide</a></li>
 				<li><a href="pkgkdegit.html">pkg-kde git quick guide</a></li>
 				<li><a href="experimental_linking.html">Fixing link errors</a></li>
+                                <li><a href="symbolfiles.html">Working with symbol files</a></li>
 			        <li><a href="web-maintenance.html">Web maintenance</a></li>
 				<li><a href="todo.html">ToDo-List</a></li>
          </ul>

Added: www/v2/pages/symbolfiles
===================================================================
--- www/v2/pages/symbolfiles	                        (rev 0)
+++ www/v2/pages/symbolfiles	2010-08-09 13:40:27 UTC (rev 18631)
@@ -0,0 +1,138 @@
+<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 at 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>
+


