/usr/share/doc/ubuntu-packaging-guide-html/libraries.html is in ubuntu-packaging-guide-html 0.3.9.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>10. Shared Libraries — Ubuntu Packaging Guide</title>
<link rel="shortcut icon" href="./_static/images/favicon.ico" type="image/x-icon" />
<link rel="stylesheet" href="./_static/reset.css" type="text/css" />
<link rel="stylesheet" href="./_static/960.css" type="text/css" />
<link rel="stylesheet" href="./_static/base.css" type="text/css" />
<link rel="stylesheet" href="./_static/home.css" type="text/css" />
<link rel="stylesheet" href="./_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="./_static/guide.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '0.3.9',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="./_static/jquery.js"></script>
<script type="text/javascript" src="./_static/underscore.js"></script>
<script type="text/javascript" src="./_static/doctools.js"></script>
<script type="text/javascript" src="./_static/main.js"></script>
<link rel="search" title="Search" href="./search.html" />
<link rel="top" title="Ubuntu Packaging Guide" href="./index.html" />
<link rel="next" title="11. Backporting software updates" href="backports.html" />
<link rel="prev" title="9. Fixing FTBFS packages" href="fixing-ftbfs.html" />
</head>
<body class="home">
<a name="top"></a>
<div class="header-navigation">
<div>
<nav role="navigation">
<ul>
<li class="page_item current_page_item"><a title="Contents" href="index.html">Contents</a>
<li>
<form id="form-search" method="get" action="search.html">
<fieldset>
<input id="input-search" type="text" name="q" value="Search" />
</fieldset>
</form>
</li>
</ul>
</nav>
<a class="logo-ubuntu" href="http://packaging.ubuntu.com/">
<img src="./_static/images/logo-ubuntu.png" width="119" height="27" alt="Ubuntu logo" />
</a>
<a href="http://packaging.ubuntu.com/"><h2>Packaging Guide</h2></a>
</div>
</div>
<div class="header-content">
<div class="clearfix">
<div class="header-navigation-secondary">
<div>
<nav role="navigation">
<ul class="clearfix">
<li class="page_item"><a style="margin-right: 10px"
href="backports.html" title="11. Backporting software updates"
accesskey="N">next</a></li>
<li class="page_item"><a
href="fixing-ftbfs.html" title="9. Fixing FTBFS packages"
accesskey="P">previous</a></li>
<li class="page_item"><a class="sub-nav-item" href="index.html">Ubuntu Packaging Guide »</a></li>
</ul>
</nav>
</div>
</div>
</div>
</div>
<div id="content" class="body container_12">
<div class="grid_12">
<!--<section id="main-section">-->
<div class="grid_9 alpha">
<div class="section" id="shared-libraries">
<h1>10. Shared Libraries<a class="headerlink" href="#shared-libraries" title="Permalink to this headline">¶</a></h1>
<p>Shared libraries are compiled code which is intended to be shared
among several different programs. They are distributed as <code class="docutils literal"><span class="pre">.so</span></code>
files in <code class="docutils literal"><span class="pre">/usr/lib/</span></code>.</p>
<p>A library exports symbols which are the compiled versions of
functions, classes and variables. A library has a name called an
SONAME which includes a version number. This SONAME version does not
necessarily match the public release version number. A program gets
compiled against a given SONAME version of the library. If any of the
symbols is removed or changes then the version number needs to be
changed which forces any packages using that library to be recompiled
against the new version. Version numbers are usually set by upstream
and we follow them in our binary package names called an ABI number,
but sometimes upstreams do not use sensible version numbers and
packagers have to keep separate version numbers.</p>
<p>Libraries are usually distributed by upstream as standalone releases. Sometimes
they are distributed as part of a program. In this case they can be included
in the binary package along with the program (this is called bundling) if you
do not expect any other programs to use the library, more often they should be
split out into separate binary packages.</p>
<p>The libraries themselves are put into a binary package named <code class="docutils literal"><span class="pre">libfoo1</span></code> where
<code class="docutils literal"><span class="pre">foo</span></code> is the name of the library and <code class="docutils literal"><span class="pre">1</span></code> is the version from the SONAME.
Development files from the package, such as header files, needed to compile
programs against the library are put into a package called <code class="docutils literal"><span class="pre">libfoo-dev</span></code>.</p>
<div class="section" id="an-example">
<h2>10.1. An Example<a class="headerlink" href="#an-example" title="Permalink to this headline">¶</a></h2>
<p>We will use libnova as an example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ bzr branch ubuntu:trusty/libnova
$ sudo apt-get install libnova-dev
</pre></div>
</div>
<p>To find the SONAME of the library run:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ readelf -a /usr/lib/libnova-0.12.so.2 | grep SONAME
</pre></div>
</div>
<p>The SONAME is <code class="docutils literal"><span class="pre">libnova-0.12.so.2</span></code>, which matches the file name (usually the
case but not always). Here upstream has put the upstream version number as part
of the SONAME and given it an ABI version of <code class="docutils literal"><span class="pre">2</span></code>. Library package names
should follow the SONAME of the library they contain. The library binary package
is called <code class="docutils literal"><span class="pre">libnova-0.12-2</span></code> where <code class="docutils literal"><span class="pre">libnova-0.12</span></code> is the name of the library
and <code class="docutils literal"><span class="pre">2</span></code> is our ABI number.</p>
<p>If upstream makes incompatible changes to their library they will have to
reversion their SONAME and we will have to rename our library. Any other
packages using our library package will need to recompiled against the new
version, this is called a transition and can take some effort. Hopefully our ABI
number will continue to match upstream’s SONAME but sometimes they introduce
incompatibilities without changing their version number and we will need to
change ours.</p>
<p>Looking in debian/libnova-0.12-2.install we see it includes two files:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">usr</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">libnova</span><span class="o">-</span><span class="mf">0.12</span><span class="o">.</span><span class="n">so</span><span class="o">.</span><span class="mi">2</span>
<span class="n">usr</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">libnova</span><span class="o">-</span><span class="mf">0.12</span><span class="o">.</span><span class="n">so</span><span class="o">.</span><span class="mf">2.0</span><span class="o">.</span><span class="mi">0</span>
</pre></div>
</div>
<p>The last one is the actual library, complete with minor and point version
number. The first one is a symlink which points to the actual library. The
symlink is what programs using the library will look for, the running
programs do not care about the minor version number.</p>
<p><code class="docutils literal"><span class="pre">libnova-dev.install</span></code> includes all the files needed to compile a program
with this library. Header files, a config binary, the <code class="docutils literal"><span class="pre">.la</span></code> libtool file and
<code class="docutils literal"><span class="pre">libnova.so</span></code> which is another symlink pointing at the library, programs
compiling against the library do not care about the major version number
(although the binary they compile into will).</p>
<p><code class="docutils literal"><span class="pre">.la</span></code> libtool files are needed on some non-Linux systems with poor library
support but usually cause more problems than they solve on Debian systems. It
is a current <a class="reference external" href="https://wiki.debian.org/ReleaseGoals/LAFileRemoval">Debian goal to remove .la files</a> and we should help with this.</p>
</div>
<div class="section" id="static-libraries">
<h2>10.2. Static Libraries<a class="headerlink" href="#static-libraries" title="Permalink to this headline">¶</a></h2>
<p>The -dev package also ships <code class="docutils literal"><span class="pre">usr/lib/libnova.a</span></code>. This is a static library,
an alternative to the shared library. Any program compiled against the
static library will include the code directory into itself. This gets round
worrying about binary compatibility of the library. However it also means that
any bugs, including security issues, will not be updated along with the library
until the program is recompiled. For this reason programs using static
libraries are discouraged.</p>
</div>
<div class="section" id="symbol-files">
<h2>10.3. Symbol Files<a class="headerlink" href="#symbol-files" title="Permalink to this headline">¶</a></h2>
<p>When a package builds against a library the <code class="docutils literal"><span class="pre">shlibs</span></code> mechanism will add a
package dependency on that library. This is why most programs will have
<code class="docutils literal"><span class="pre">Depends:</span> <span class="pre">${shlibs:Depends}</span></code> in <code class="docutils literal"><span class="pre">debian/control</span></code>. That gets replaced with
the library dependencies at build time. However shlibs can only make it depend
on the major ABI version number, <code class="docutils literal"><span class="pre">2</span></code> in our libnova example, so if new symbols
get added in libnova 2.1 a program using these symbols could still be
installed against libnova ABI 2.0 which would then crash.</p>
<p>To make the library dependencies more precise we keep <code class="docutils literal"><span class="pre">.symbols</span></code> files that
list all the symbols in a library and the version they appeared in.</p>
<p>libnova has no symbols file so we can create one. Start by compiling the
package:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ bzr builddeb -- -nc
</pre></div>
</div>
<p>The <code class="docutils literal"><span class="pre">-nc</span></code> will cause it to finish at the end of compilation without removing
the built files. Change to the build and run <code class="docutils literal"><span class="pre">dpkg-gensymbols</span></code> for the
library package:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ cd ../build-area/libnova-0.12.2/
$ dpkg-gensymbols -plibnova-0.12-2 > symbols.diff
</pre></div>
</div>
<p>This makes a diff file which you can self apply:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ patch -p0 < symbols.diff
</pre></div>
</div>
<p>Which will create a file named similar to <code class="docutils literal"><span class="pre">dpkg-gensymbolsnY_WWI</span></code> that lists
all the symbols. It also lists the current package version. We can remove the
packaging version from that listed in the symbols file because new symbols are
not generally added by new packaging versions, but by the upstream developers:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ sed -i s,-0ubuntu2,, dpkg-gensymbolsnY_WWI
</pre></div>
</div>
<p>Now move the file into its location, commit and do a test build:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ mv dpkg-gensymbolsnY_WWI ../../libnova/debian/libnova-0.12-2.symbols
$ cd ../../libnova
$ bzr add debian/libnova-0.12-2.symbols
$ bzr commit -m "add symbols file"
$ bzr builddeb
</pre></div>
</div>
<p>If it successfully compiles the symbols file is correct. With the next
upstream version of libnova you would run dpkg-gensymbols again and it will
give a diff to update the symbols file.</p>
</div>
<div class="section" id="c-library-symbols-files">
<h2>10.4. C++ Library Symbols Files<a class="headerlink" href="#c-library-symbols-files" title="Permalink to this headline">¶</a></h2>
<p>C++ has even more exacting standards of binary compatibility than C. The
Debian Qt/KDE Team maintain some scripts to handle this, see their <a class="reference external" href="http://pkg-kde.alioth.debian.org/symbolfiles.html">Working with
symbols files</a> page for how to use them.</p>
</div>
<div class="section" id="further-reading">
<h2>10.5. Further Reading<a class="headerlink" href="#further-reading" title="Permalink to this headline">¶</a></h2>
<p>Junichi Uekawa’s <a class="reference external" href="http://www.netfort.gr.jp/~dancer/column/libpkg-guide/libpkg-guide.html">Debian Library Packaging Guide</a> goes into this topic in more
detail.</p>
</div>
</div>
<div class="divide"></div>
</div>
<div id="sidebar" class="grid_3 omega">
<div class="container-tweet">
<h3>Table Of Contents</h3>
<div class="toc">
<ul>
<li><a class="reference internal" href="#">10. Shared Libraries</a><ul>
<li><a class="reference internal" href="#an-example">10.1. An Example</a></li>
<li><a class="reference internal" href="#static-libraries">10.2. Static Libraries</a></li>
<li><a class="reference internal" href="#symbol-files">10.3. Symbol Files</a></li>
<li><a class="reference internal" href="#c-library-symbols-files">10.4. C++ Library Symbols Files</a></li>
<li><a class="reference internal" href="#further-reading">10.5. Further Reading</a></li>
</ul>
</li>
</ul>
</div>
<div class="browse-guide">
<h3>Browse The Guide:</h3>
<ul>
<li class="prev">
<a href="fixing-ftbfs.html"
title="Previous topic: 9. Fixing FTBFS packages">Go Previous</a>
</li>
<li class="center">
<a title="Back to Index" href="index.html">Index Guide</a>
</li>
<li class="next">
<a href="backports.html"
title="Next topic: 11. Backporting software updates">Go Next</a>
</li>
</ul>
<span>This Page:</span> <a href="./_sources/libraries.rst.txt"
rel="nofollow">Show Source</a>
</div>
</div>
<div id="back_top"><a href="#top">Back to Top</a></div>
</div>
<!--</section>-->
</div>
</div>
<div class="shadow"></div>
<footer>
<div>
Version: 0.3.9.
<a href="https://bugs.launchpad.net/ubuntu-packaging-guide">Report bugs</a> or
<a href="https://code.launchpad.net/~ubuntu-packaging-guide-team/ubuntu-packaging-guide/trunk">grab the source code</a> from Launchpad.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
<br />
© Copyright 2010-2017, Ubuntu Developers, Creative Commons Attribution-ShareAlike 3.0.
<a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">
Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.
<a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">
<img alt="Creative Commons License" style="border-width:0"
src="./_static/images/cc-by-sa.png" /></a>
<br />
<a href="http://people.ubuntu.com/~mitya57/ubuntu-packaging-guide-readme.html#translating">Help translate</a> or
<a href="./_static/translators.html">view the list of translators</a>.
</div>
</footer>
</body>
</html>
|