Package: dh-kpatches
Version: 0.99.36+nmu4
Severity: important
Dear Maintainer,
As reported in https://bugs.debian.org/870820 and getting very positive
feedback at DEBCONF17 after migrating Debian Policy to DocBookXML,
debiandoc-sgml will be removed from the archive at buster+{0,1}. I am sending
reminder to packages which still uses this package.
The offending SGML source is converted to XML using "debiandoc2dbk -1" command.
So please replace it and use the actively maintained XML tool chain.
Osamu
-- System Information:
Debian Release: 9.1
APT prefers stable
APT policy: (500, 'stable')
Architecture: amd64 (x86_64)
<?xml version='1.0' encoding='utf-8'?>
<!-- -*- DocBook -*- -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [
<!-- Include entity definition file by uncommenting the following -->
<!-- <!ENTITY % versiondata SYSTEM "version.ent"> %versiondata; -->
]>
<book lang="en">
<title>Kernel-patch sub-policy draft document</title>
<bookinfo>
<authorgroup>
<author><personname>Yann
Dirson</personname><email>dir...@debian.org</email></author>
</authorgroup>
<releaseinfo>$Revision: 1.2 $</releaseinfo>
<pubdate><!-- put date --></pubdate>
<abstract>
<para>
This document is an attempt to gather current Best Practice(tm) in providing
kernel-patches for easy use with <systemitem
role="package">kernel-package</systemitem> (see
<citerefentry><refentrytitle>make-kpkg</refentrytitle><manvolnum>1</manvolnum></citerefentry>).
It comes from the various issues that stopped me while I started to package
kernel patches, and is targetted at maintainers of kernel-patch packages, to
gain in consistency, functionality, and smooth system integration. The
intention is that at least part of it gets some day blessed into Policy, and
most of the remaining into Packaging Manual.
</para>
</abstract>
</bookinfo>
<chapter id="ch1"><title>Big picture summary</title>
<para>
This section is meant to give a brief overview of how
<command>make-kpkg</command> works with respect to patch handling. For more
details please refer to the
<citerefentry><refentrytitle>make-kpkg</refentrytitle><manvolnum>1</manvolnum></citerefentry>
manpage.
</para>
<section id="s1.1"><title>Using <command>make-kpkg</command> to build patched
kernels</title>
<para>
The default configuration of <command>make-kpkg</command> is to ignore any
available patches and build a package with whatever kernel source is in the
current directory. You can tell it to use patches from under
<filename>/usr/src/kernel-patches/</filename>, either by setting the
<literal>PATCH_THE_KERNEL</literal> environment variable to
<literal>YES</literal> <footnote><para> You may also set the
<literal>patch_the_kernel</literal> variable in
<filename>/etc/kernel-pkg.conf</filename>, but I discourage this, you may well
forget you have this set one day. </para> </footnote>.
</para>
<para>
When asked to apply patches, <command>make-kpkg</command> will apply all
patches it finds for the current architecture and version for the kernel being
built. You may want to only select some of them using the
<literal>--added_patches</literal> option.
</para>
</section>
<section id="s1.2"><title>How <command>make-kpkg</command> applies
patches</title>
<para>
It looks for <filename>apply</filename> scripts in the following subdirectories
of <filename>/usr/src/kernel-patches/</filename>:
</para>
<orderedlist numeration="arabic">
<listitem>
<para>
<filename>$ARCH/$VERSION/apply/</filename>
</para>
</listitem>
<listitem>
<para>
<filename>$ARCH/apply/</filename>
</para>
</listitem>
<listitem>
<para>
<filename>all/$VERSION/apply/</filename>
</para>
</listitem>
<listitem>
<para>
<filename>all/apply/</filename>
</para>
</listitem>
</orderedlist>
<para>
At the time it will want to remove those patches, it will then look into
similar directories with name <filename>unpatch</filename>.
</para>
<para>
Typically the main job of these scripts is to apply a diff, but well, they are
scripts after all, and more complex tasks in need of something more smart than
<command>patch</command> may make use of this power.
</para>
</section>
</chapter>
<chapter id="ch2"><title>Patch scope</title>
<para>
This section should describe possible scopes for a patch in terms of kernel
architecture and versions, and what actions to take depending on effective
scope.
</para>
<para>
As you may infer from the previous chapter, some patches are fully generic,
whereas others only apply to specific kernel versions and/or specific
architectures.
</para>
<section id="s2.1"><title>Architecture</title>
<para>
Some patches do not include support for some achitectures, in which case all
they can bring to other architectures is to break them in one way or another.
Then they need to be restricted into architecture-dependant directories. In
the case where a patch applies to several architectures, shared files should be
hard-linked to avoid wasting disk space.
</para>
<para>
Only patches with (at least theoretical) support for all architectures, and
non-architecture-dependant patches, belong to the <literal>all</literal>
category.
</para>
</section>
<section id="s2.2"><title>Version</title>
<para>
Usually patches are made of a diff file. These diff files are usually built by
comparing a specific kernel-source tree and a modified tree. Although those
diffs are guaranted to apply on a tree identical to the one which served as
reference when the diff was built, they may also apply (in the mechanical
meaning defined by <command>patch</command> returning success) to a number of
kernel revisions (or kernels with other patches already applied), if the areas
touched by the patch are similar enough to those in the reference tree. This
means that a patch against revision <literal>x.y.z</literal> may also apply to
<literal>x.y.(z-2)</literal> or <literal>x.y.(z+5)</literal> without
<command>patch</command> complaining.
</para>
<para>
However, this mechanical meaning of a patch applying is not enough in some
cases, where changes in one area may interfere with changes in another. Such
interferences will range from kernel not being able to compile (eg. because of
struct members renamed or previously exported functions marked static) to
kernels behaving in really strange unforeseen ways, possibly causing data
corruption or all other types of behaviour you usually want to run away from.
</para>
<para>
For these reasons, depending on how tricky a patch is, one may want to limit
the range of kernel versions on which it is to be applied. For this the
version-specific subdirectories of
<filename>/usr/src/kernel-patches/</filename> have been created. But beware
not to be too limitative, a patch against the latest stable kernel may well be
useful with the next yet-unreleased one, and you may not want to be
totalitarian with your package's users. Up to you to make a "good
choice", whatever that means.
</para>
</section>
</chapter>
<chapter id="ch3"><title>Scripts naming and behaviour</title>
<para>
This section is meant to give guidelines for writing the
<filename>apply</filename> and <filename>unpatch</filename> in a way that will
work securely (ie. doesn't break the current kernel-source tree), and will
integrate smoothly with the remaining of the system.
</para>
<para>
This is where currently packaged patches tend to behave in unwanted ways.
</para>
<section id="s3.1"><title>Naming</title>
<para>
Unless specific patches are requested, scripts in the
<filename>apply</filename> and <filename>unpatch</filename> dirs are executed
via <command>run-parts</command>, which runs them in lexical sort order.
</para>
<para>
It may be nice at some time to allow the names of applied patches to make their
way to the EXTRAVERSION field in the kernel revision, so that we get kernel
versions like "2.2.17+ide+ltt+int", that would automagically provide at the
same time instant information for what patches were applied, and the ability of
also installing at the same time plain "2.2.17" as well as
"2.2.17+kdb+reiserfs" (no offense to reiserfs meant ;). It may be nice at this
time to have patches provide such a short name to <command>make-kpkg</command>.
</para>
</section>
<section id="s3.2"><title>Behaviour</title>
<para>
Most of the scripts share a number of behaviours that help them to acomplish
the task that justifies their existence. However, probably for lack of such a
document, they are currently built on an ad-hoc basis, starting with a copy of
existing scripts. I'll try here to list those behaviours and give guidelines
so that they indeed do not interfere with each other.
</para>
<para>
As of now, I don't think a single patch package (including mines) behaves
correctly in all these areas. I have started a <systemitem
role="package">debhelper</systemitem>-like script to help in this area and to
provide a couple additional functionalities. Those interested will find it at
<ulink
url="http://people.debian.org/~dirson/kpatches/";>http://people.debian.org/~dirson/kpatches/</ulink>
</para>
<section id="s3.2.1"><title><filename>apply</filename> telling
<filename>unpatch</filename> the patch was applied</title>
<para>
This is usually done by creating a file named
<filename>debian-patches/APPLIED_<replaceable>patchname</replaceable></filename>,
which <filename>unpatch</filename> checks to know whether it has something to
do, and which <filename>apply</filename> also checks to not try to re-apply
itself.
</para>
<para>
Some patches create this file in the <filename>debian/</filename> subdirectory,
and some other patches create it at the top-level of the kernel sources. The
former causes interferences between <command>make-kpkg clean</command>
operation and patches applied by running <filename>apply</filename> scripts by
hand; the latter causes problems because some <filename>apply</filename>
scripts remove empty files after patching. Further more, these files are
debian-specific, so they may be better in debian-specific subdir anyway.
</para>
</section>
<section id="s3.2.2"><title>Removing empty files after patching</title>
<para>
This is mostly done to cleanup the source tree in cases where files were
suppressed or moved. Most package just run <command>find</command> on the
whole source tree to find them, then remove them, and create an empty
<filename>APPLIED_<replaceable>whatever</replaceable></filename> as described
above... which gets happily removed by the next <filename>apply</filename>
script that gets run.
</para>
<para>
For good interaction between those 2 behaviours, no empty files should be
removed from the <filename>debian/</filename> subdirectory - anyway no file
there should be removed by any patch I can think of, as this dir is not part of
an official kernel tree. This will allow
<filename>APPLIED_<replaceable>whatever</replaceable></filename> scripts
conforming to the previous point to survive to play their role in the whole
picture.
</para>
</section>
<section id="s3.2.3"><title>Checking whether to apply the patch</title>
<para>
<filename>apply</filename> scripts, when they determine with whatever means
that they should not attempt to apply, should not return an error code. This
allows unversionned patches to be applied as long as <command>patch</command>
can do the job, without preventing other patches to apply on versions of the
kernel on which they don't themselves apply.
</para>
</section>
<section id="s3.2.4"><title>Not breaking the source tree</title>
<para>
The scripts should make sure they won't break the user's tree, by using
<command>patch --dry-run</command> before they really apply the patch. Not
only does this allow unversionned patches to exist at all without enforcing
version tests in the scripts, but it also allows the user to experiment with
stacking patches without having to restart from unpacking the source at each
failure.
</para>
</section>
</section>
</chapter>
<chapter id="ch4"><title>Packaging issues</title>
<section id="s4.1"><title>whether to include several patches per package</title>
</section>
<section id="s4.2"><title>how to name patch packages</title>
</section>
</chapter>
</book>
