[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

RFC: draft sub-policy for kernel patches

Hi,

Hi wrote a small draft for directives wrt packaging of kernel patches.
I'd like to have comments on this.  I attach the text version.  An
HTML version is available at
http://people.debian.org/~dirson/kpatches/kpatch-policy.html/

Regards,
-- 
Yann Dirson    <ydirson@altern.org> |    Why make M$-Bill richer & richer ?
debian-email:   <dirson@debian.org> |   Support Debian GNU/Linux:
                                    | Cheaper, more Powerful, more Stable !
http://ydirson.free.fr/             | Check <http://www.debian.org/>

                  Kernel-patch sub-policy draft document
                  --------------------------------------

                      Yann Dirson <dirson@debian.org>

                             $Revision: 1.2 $


-------------------------------------------------------------------------------


Abstract
--------

     This document is an attempt to gather current Best Practice(tm) in
     providing kernel-patches for easy use with `kernel-package' (see
     make-kpkg(1)).  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.


Copyright Notice
----------------

     This document is covered by the GNU GPL.


-------------------------------------------------------------------------------


Contents
--------

     1.        Big picture summary
     1.1.      Using `make-kpkg' to build patched kernels
     1.2.      How `make-kpkg' applies patches

     2.        Patch scope
     2.1.      Architecture
     2.2.      Version

     3.        Scripts naming and behaviour
     3.1.      Naming
     3.2.      Behaviour

     4.        Packaging issues
     4.1.      whether to include several patches per package
     4.2.      how to name patch packages


-------------------------------------------------------------------------------


1. Big picture summary
----------------------

     This section is meant to give a brief overview of how `make-kpkg'
     works with respect to patch handling.  For more details please refer
     to the make-kpkg(1) manpage.


1.1. Using `make-kpkg' to build patched kernels
-----------------------------------------------

     The default configuration of `make-kpkg' is to ignore any available
     patches and build a package with whatever kernel source is in the
     current directory.  You can tell him to use patches from under
     `/usr/src/kernel-patches/', either by setting the `PATCH_THE_KERNEL'
     environment variable to `YES' [1].

     When asked to apply patches, `make-kpkg' 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
     `--added_patches' option.

[1]  You may also set the `patch_the_kernel' variable in
     `/etc/kernel-pkg.conf', but I discourage this, you may well forget you
     have this set one day. 


1.2. How `make-kpkg' applies patches
------------------------------------

     It looks for `apply' scripts in the following subdirectories of
     `/usr/src/kernel-patches/':
     1.   `$ARCH/$VERSION/apply/'
     2.   `$ARCH/apply/'
     3.   `all/$VERSION/apply/'
     4.   `all/apply/'

     At the time it will want to remove those patches, it will then look
     into similar directories with name `unpatch'.

     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 `patch' may make use of this power.


-------------------------------------------------------------------------------


2. Patch scope
--------------

     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.

     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.


2.1. Architecture
-----------------

     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.

     Only patches with (at least theoretical) support for all
     architectures, and non-architecture-dependant patches, belong to the
     `all' category.


2.2. Version
------------

     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 `patch' 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
     `x.y.z' may also apply to `x.y.(z-2)' or `x.y.(z+5)' without `patch'
     complaining.

     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.

     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 `/usr/src/kernel-patches/'
     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.


-------------------------------------------------------------------------------


3. Scripts naming and behaviour
-------------------------------

     This section is meant to give guidelines for writing the `apply' and
     `unpatch' in a way that will work securely (ie.  don't break the
     current kernel-source tree), and will integrate smoothly with the
     remaining of the system.

     This is where currently packaged patches tend to do behave in unwanted
     ways.


3.1. Naming
-----------

     Unless specific patches are requested, scripts in the `apply' and
     `unpatch' dirs are executed via `run-parts', which runs them in
     lexical sort order.

     It may be nice at some time to allow applied patch names 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 `make-kpkg'.


3.2. Behaviour
--------------

     Most of the scripts share a number of behaviours that help them in
     acomplishing the task that justifies their existence.  However,
     probably for lack of such a document, they are currently built on as
     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 others.

     As of now, I don't think a single patch package (including mines)
     behaves correctly in all these areas.  I have started a
     `debhelper'-like script to help in this area and to provide a couple
     additional functionalities.  Those interested will find it at ..

3.2.1. `apply' telling `unpatch' the patch was applied
------------------------------------------------------

     This is usually done by creating a file named `APPLIED_<patchname>',
     which `unpatch' checks to know whether it has something to do, and
     which `apply' also checks to not try to re-apply itself.

     Some patches create this file in the `debian/' subdirectory (and then
     must create this dir if needed), and some other patches create it at
     the top-level of the kernel sources.  The latter causes problems
     because some `apply' scripts remove empty files after patching.
     Further more, these files are debian-specific, so they may be better
     in the `debian/' dir anyway.

3.2.2. Removing empty files after patching
------------------------------------------

     This is mostly done to cleanup the source tree in cases where files
     were suppressed or moved.  Most package just run `find' on the whole
     source tree to find them, then remove them, and create an empty
     `APPLIED_<whatever>' as described above...  which gets happily removed
     by the next `apply' script that gets run.

     For good interaction between those 2 behaviours, no empty files should
     be removed from the `debian/' 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 for `APPLIED_<whatever>'
     scripts conforming to the previous point to survive to play their role
     in the whole picture.

3.2.3. Checking whether to apply the patch
------------------------------------------

     `apply' 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 `patch' can do
     the job, without preventing other patches to apply on versions of the
     kernel on which they don't themselves apply.

3.2.4. Not breaking the source tree
-----------------------------------

     The scripts should make sure they won't break the user's tree, by
     using `patch --dry-run' before they really apply the patch.  Not only
     this allows 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.


-------------------------------------------------------------------------------


4. Packaging issues
-------------------


4.1. whether to include several patches per package
---------------------------------------------------


4.2. how to name patch packages
-------------------------------


-------------------------------------------------------------------------------


     Kernel-patch sub-policy draft document

     Yann Dirson <dirson@debian.org>

     $Revision: 1.2 $
Reply to: