/usr/share/doc/openvswitch-doc/html/internals/contributing/libopenvswitch-abi.html is in openvswitch-doc 2.9.0-0ubuntu1.
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 | <!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>Open vSwitch Library ABI Updates — Open vSwitch 2.9.0 documentation</title>
<link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../',
VERSION: '2.9.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</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>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="next" title="Mailing Lists" href="../mailing-lists.html" />
<link rel="prev" title="Open vSwitch Documentation Style" href="documentation-style.html" />
<link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head>
<body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="open-vswitch-library-abi-updates">
<h1>Open vSwitch Library ABI Updates<a class="headerlink" href="#open-vswitch-library-abi-updates" title="Permalink to this headline">¶</a></h1>
<p>This file describes the manner in which the Open vSwitch shared library
manages different ABI and API revisions. This document aims to describe
the background, goals, and concrete mechanisms used to export code-space
functionality so that it may be shared between multiple applications.</p>
<div class="section" id="definitions">
<span id="id1"></span><h2>Definitions<a class="headerlink" href="#definitions" title="Permalink to this headline">¶</a></h2>
<table border="1" class="docutils" id="id3">
<caption><span class="caption-text">Definitions for terms appearing in this document</span><a class="headerlink" href="#id3" title="Permalink to this table">¶</a></caption>
<colgroup>
<col width="50%" />
<col width="50%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Term</th>
<th class="head">Definition</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>ABI</td>
<td>Abbreviation of Application Binary Interface</td>
</tr>
<tr class="row-odd"><td>API</td>
<td>Abbreviation of Application Programming Interface</td>
</tr>
<tr class="row-even"><td>Application Binary Interface</td>
<td>The low-level runtime interface exposed
by an object file.</td>
</tr>
<tr class="row-odd"><td>Application Programming Interface</td>
<td>The source-code interface descriptions
intended for use in multiple translation units when compiling.</td>
</tr>
<tr class="row-even"><td>Code library</td>
<td>A collection of function implementations and definitions
intended to be exported and called through a well-defined interface.</td>
</tr>
<tr class="row-odd"><td>Shared Library</td>
<td>A code library which is imported at run time.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="overview">
<span id="id2"></span><h2>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
<p>C and C++ applications often use ‘external’ functionality, such as printing
specialized data types or parsing messages, which has been exported for common
use. There are many possible ways for applications to call such external
functionality, for instance by including an appropriate inline definition which
the compiler can emit as code in each function it appears. One such way of
exporting and importing such functionality is through the use of a library
of code.</p>
<p>When a compiler builds object code from source files to produce object code,
the results are binary data arranged with specific calling conventions,
alignments, and order suitable for a run-time environment or linker. This
result defines a specific ABI.</p>
<p>As library of code develops and its exported interfaces change over time, the
resulting ABI may change as well. Therefore, care must be taken to ensure the
changes made to libraries of code are effectively communicated to applications
which use them. This includes informing the applications when incompatible
changes are made.</p>
<p>The Open vSwitch project exports much of its functionality through multiple
such libraries of code. These libraries are intended for multiple applications
to import and use. As the Open vSwitch project continues to evolve and change,
its exported code will evolve as well. To ensure that applications linking to
these libraries are aware of these changes, Open vSwitch employs libtool
version stamps.</p>
</div>
<div class="section" id="abi-policy">
<span id="policies"></span><h2>ABI Policy<a class="headerlink" href="#abi-policy" title="Permalink to this headline">¶</a></h2>
<p>Open vSwitch will export the ABI version at the time of release, such that the
library name will be the major.minor version, and the rest of the release
version information will be conveyed with a libtool interface version.</p>
<p>The intent is for Open vSwitch to maintain an ABI stability for each minor
revision only (so that Open vSwitch release 2.5 carries a guarantee for all
2.5.ZZ micro-releases). This means that any porting effort to stable branches
must take not to disrupt the existing ABI.</p>
<p>In the event that a bug must be fixed in a backwards-incompatible way,
developers must bump the libtool ‘current’ version to inform the linker of the
ABI breakage. This will signal that libraries exposed by the subsequent release
will not maintain ABI stability with the previous version.</p>
</div>
<div class="section" id="coding">
<h2>Coding<a class="headerlink" href="#coding" title="Permalink to this headline">¶</a></h2>
<p>At build time, if building shared libraries by passing the <cite>–enable-shared</cite>
arguments to <cite>./configure</cite>, version information is extracted from
the <code class="docutils literal"><span class="pre">$PACKAGE_VERSION</span></code> automake variable and formatted into the appropriate
arguments. These get exported for use in Makefiles as <code class="docutils literal"><span class="pre">$OVS_LTINFO</span></code>, and
passed to each exported library along with other <code class="docutils literal"><span class="pre">LDFLAGS</span></code>.</p>
<p>Therefore, when adding a new library to the build system, these version flags
should be included with the <code class="docutils literal"><span class="pre">$LDFLAGS</span></code> variable. Nothing else needs to be
done.</p>
<p>Changing an exported function definition (from a file in, for instance
<cite>lib/*.h</cite>) is only permitted from minor release to minor release. Likewise
changes to library data structures should only occur from minor release to
minor release.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../../contents.html">
<img class="logo" src="../../_static/logo.png" alt="Logo"/>
</a></p>
<h3><a href="../../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Open vSwitch Library ABI Updates</a><ul>
<li><a class="reference internal" href="#definitions">Definitions</a></li>
<li><a class="reference internal" href="#overview">Overview</a></li>
<li><a class="reference internal" href="#abi-policy">ABI Policy</a></li>
<li><a class="reference internal" href="#coding">Coding</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../../contents.html">Documentation overview</a><ul>
<li><a href="../index.html">Open vSwitch Internals</a><ul>
<li><a href="index.html">Contributing to Open vSwitch</a><ul>
<li>Previous: <a href="documentation-style.html" title="previous chapter">Open vSwitch Documentation Style</a></li>
<li>Next: <a href="../mailing-lists.html" title="next chapter">Mailing Lists</a></li>
</ul></li>
</ul></li>
</ul></li>
</ul>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../_sources/internals/contributing/libopenvswitch-abi.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="../../search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©2018, The Open vSwitch Development Community.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
|
<a href="../../_sources/internals/contributing/libopenvswitch-abi.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>
|