mirror of
https://salsa.debian.org/kernel-team/kernel-handbook.git
synced 2026-01-11 19:58:20 +00:00
3eb60d93a2
For parallel builds, fakeroot limits actual concurrency a lot. In other cases it's still an unnecessary complication that slows things down. - Where appropriate, use dpkg-buildpackage instead. - Otherwise, since src:linux has had "Rules-Requires-Root: no" since before buster, use DEB_RULES_REQUIRES_ROOT=no instead. (Without either this or fakeroot, some debhelper commands would complain.) - Remove fakeroot from lists of packages to be installed.
133 lines
5.2 KiB
XML
133 lines
5.2 KiB
XML
<?xml version='1.0' encoding='utf-8'?>
|
|
<!-- -*- DocBook -*- -->
|
|
<chapter id="ch-versions">
|
|
<?dbhtml filename="ch-versions.html" ?>
|
|
<title>Version numbers and ABIs</title>
|
|
<section id="s-version-types"><title>The different types of version</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>Upstream version</term>
|
|
<listitem>
|
|
<para>
|
|
The version that Linus or a stable series maintainer uses for a release.
|
|
Currently Linus will use the version format:
|
|
4.<replaceable>x</replaceable>[-rc<replaceable>y</replaceable>]. Stable series
|
|
maintainers use the version format:
|
|
4.<replaceable>x</replaceable>.<replaceable>y</replaceable>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Package version</term>
|
|
<listitem>
|
|
<para>
|
|
The version used in a Debian package. Following Debian policy, it should
|
|
follow the format
|
|
<replaceable>upstreamversion</replaceable>-<replaceable>debianrevision</replaceable>.
|
|
However, for an upstream release candidate, the string '-rc' must be replaced
|
|
with '~rc' so that it will be recognised as an earlier version than the
|
|
following release.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Kernel version</term>
|
|
<listitem>
|
|
<para>
|
|
This is the version that appears in kernel messages, filenames, package names
|
|
and the output of 'uname -r'. In official kernel packages it follows the
|
|
format
|
|
<replaceable>upstreamversion</replaceable>[-<replaceable>abiname</replaceable>][-<replaceable>featureset</replaceable>]-<replaceable>flavour</replaceable>.
|
|
It is not changed for every new package version. The
|
|
<replaceable>abiname</replaceable> is changed as explained below.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
Many programs parse the kernel version string reported by the
|
|
<command>uname</command> system call or command and expect to find at least 3
|
|
version components separated by dots. For compatibility, the official kernel
|
|
packages currently add '.0' to the upstream version.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="s-abi"><title>The kernel ABI</title>
|
|
<para>
|
|
An ABI (Application Binary Interface) is an interface between two software
|
|
components, considered at the level of register allocation and memory layout.
|
|
The ABI between the kernel and user-space is generally maintained carefully,
|
|
and is not a concern here. However, the ABI between the kernel and its modules
|
|
is not. In order to support out-of-tree modules, the kernel version should be
|
|
changed when the ABI between the kernel and modules changes.
|
|
</para>
|
|
<section id="s-abi-name"><title>The ABI name</title>
|
|
<para>
|
|
In official kernel packages, we change the <replaceable>abiname</replaceable>
|
|
part of the kernel version to mark ABI changes that aren't due to a new
|
|
upstream version. This part comes from the <literal>abiname</literal> setting
|
|
in <filename>debian/config/defines</filename>. We use either a number or 'trunk'
|
|
(for experimental).
|
|
</para>
|
|
<para>
|
|
If you are rebuilding the package with local modifications, you should
|
|
change the ABI name to some other string, for example
|
|
<userinput>0.local</userinput>. Then run the command
|
|
</para>
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>debian/rules debian/control-real</userinput>
|
|
</screen>
|
|
<para>
|
|
to regenerate the package definitions for this ABI name.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="s-abi-maintenance"><title>Maintaining and updating the ABI</title>
|
|
<para>
|
|
In order to avoid the need for users to rebuild out-of-tree modules frequently,
|
|
we try to avoid changing the kernel ABI during updates to a Debian stable or
|
|
oldstable release. Most importantly, we avoid making such changes without
|
|
changing the ABI name, except where it appears that out-of-tree modules do not
|
|
depend on that part of the ABI.
|
|
</para>
|
|
<para>
|
|
Bug fixes or configuration changes to the kernel may alter the ABI. If an
|
|
exported function is conditional on
|
|
<symbol>CONFIG_<replaceable>FOO</replaceable></symbol>, or it uses a type
|
|
whose definition depends on
|
|
<symbol>CONFIG_<replaceable>FOO</replaceable></symbol>, then turning
|
|
<symbol>CONFIG_<replaceable>FOO</replaceable></symbol> on or off changes the
|
|
ABI of that function, and thus of the kernel as a whole. Enabling or changing
|
|
the configuration of a single driver usually doesn't change the ABI, because
|
|
most drivers don't export anything.
|
|
</para>
|
|
<para>
|
|
The kernel build process generates a 'symbol version' for each exported
|
|
function or variable. This is a hash of the definitions that it depends on,
|
|
and should change whenever the function's ABI changes. The kernel module
|
|
loader detects incompatible modules by comparing symbol versions. The whole
|
|
set of symbol versions represents the kernel ABI.
|
|
</para>
|
|
<para>
|
|
We collect the symbol versions for previously uploaded packages under the
|
|
directory <filename>debian/abi</filename> and then compare the new kernel with
|
|
those. If the ABI name is unchanged but the ABI itself is changed - except for
|
|
additions, or changes that we have marked as acceptable - then the build is
|
|
aborted.
|
|
</para>
|
|
<para>
|
|
If the kernel ABI has changed you must then change the ABI name in
|
|
<filename>debian/config/defines</filename>. Then run the command
|
|
</para>
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>debian/rules debian/control-real</userinput>
|
|
</screen>
|
|
<para>
|
|
to regenerate the package definitions for this ABI name.
|
|
</para>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
</chapter>
|
|
|