dirson@debian.org
| Revision History | ||
|---|---|---|
| Revision 1.1 | 2000-06-10 | |
| Initial plain-text revision | ||
| Revision 1.4 | 2001-05-14 | |
| New "Depends" field | ||
| Revision 1.8 | 2002-02-08 | |
| New syntax "Kernel-version: all" | ||
| Revision | 2002-02-10 | |
| Moved to DocBook, made it more of a real manual | ||
| Revision 1.9 | 2002-02-14 | |
| Kernel-version ranges | ||
| Revision 1.10 | 2002-02-18 | |
| First description of "revision 1" format | ||
robustness of patch application
support for variable parameters on patch(1) command line (eg. -p)
allows to apply a version of a patch that was originally targetted at another version
handles (un-)application of patch dependencies
dh_installkpatches is a debhelper script that reads debian/package.kpatches or debian/package.kpatches.something files describing one or several revisions of a single kernel patch, and installs them into the package build directory with customized apply and unpatch scripts.
It also sets the kpatch:Depends substitution variable, that you should use in your control file to ensure that generated material in your package get all their dependencies. The use of kpatch:Depends requires a build-dependency on version 0.99.3 or later of the dh-kpatches package.
This program does not take any particular option in addition to the standard debhelper(1) ones.
This manual page was written by Yann Dirson <dirson@debian.org>.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. A copy of the license can be found under /usr/share/common-licenses/FDL.
The syntax of kpatches files is inspired by the syntax of Debian control-files. A kpatches file contains sections, which are separated by one or more empty lines. Each section is made of Key: value lines.
This is the currently supported format for kpatches files. It is to be superceded shortly with a new revision, more general, described later in this document.
The file starts with a section for generic patch information, and then has one for each patchfile, allowing versions of the patch for many kernel versions to be specified in one file.
a short descriptive name for the patch
Note: Patch-name's cannot contain "pipe" (|) and "double quote" (") characters, for purely implementation reasons. Patch-name's that contain "slash" (/) characters would not be allowed before dh-kpatches 0.99.3.
Example 1. Examples
Patch-name: Kernel debugger Patch-name: Tracing toolkit Patch-name: Kernel crash dump |
a short identifier for the patch
Example 2. Examples
Patch-id: kdb Patch-id: ltt Patch-id: lkcd |
default value for the per-patchfile field of the same name (see below).
default value for the per-patchfile field of the same name (see below).
The name of the patch file. It may optionally be compressed with gzip. This should be the first field of each patchfile-specific section.
The version (or range of versions) of the kernel this patch is designed for. Other optional fields may be introduced in the future to document other versions which are known to work, and versions known not to work.
Version ranges are specified as ver1 - ver2, where both versions must belong to the same "kernel branch" (eg. 2.2, or 2.4), and must be mentionned in increasing order.
Note: Kernel versions used in ranges should show an empty EXTRAVERSION field. This is because no special comparision scheme has been implemented to handle the special meaning associated with EXTRAVERSION values like pre2 or test5.
As a special case, the value "all" is allowed, for patches that don't depend on a specific version (eg. if they just add a set of files).
The optional fields, when not provided, all take hopefully reasonable default values
a comma-separated list of the debian identifiers for archs supported by this patch.
Default is "all".
the value to pass as argument to the patch(1) -p option (aka --strip).
Default is 1.
a comma-separated list of Patch-Id's of patches this one depends on.
Default is no dependency.
This will be the next supported format for kpatches files. It has not been implemented yet. It is described here for public review.
There are 3 levels of information in this file. A kernel-patch (1st level) is a set of patch alternatives (2nd level), each of which is made of a sequence of patch operations (3rd level).
The file starts with a section for generic patch information, and then, for each alternative, has an alternative-specific section followed by one section for each patch operation.
An alternative section is syntactically distinguished from an operation section by their mandatory constituent fields.
All fields described here are mandatory.
the version of the kpatches spec this files complies with. For this version, it should be 1.
a short descriptive name for the patch
Note: Patch-name's cannot contain "pipe" (|) and "double quote" (") characters, for purely implementation reasons. Patch-name's that contain "slash" (/) characters would not be allowed before dh-kpatches 0.99.3.
Example 3. Examples
Patch-name: Kernel debugger Patch-name: Tracing toolkit Patch-name: Kernel crash dump |
a short identifier for the patch
Example 4. Examples
Patch-id: kdb Patch-id: ltt Patch-id: lkcd |
A number of alternative-specific fields are used as conditions for this alternative to be considered. This allows not only to specify in the same file versions of the patch for many kernel versions, but also to specify versions of the patch for different kernel flavours. For example, the LTT patch comes for 2 kernel flavours: plain kernel, and RTAI-patched kernel.
The order of alternative sections is significant: the 1st alternative for which all conditions are fullfilled is selected, and all further alternatives are ignored.
This field is a condition.
The version (or range of versions) of the kernel this patch is designed for. Other optional fields may be introduced in the future to document other versions which are known to work, and versions known not to work.
Version ranges are specified as ver1 - ver2, where both versions must belong to the same "kernel branch" (eg. 2.2, or 2.4), and must be mentionned in increasing order.
As a special case, the value "all" is allowed, for patches that don't depend on a specific version (eg. if they just add a set of files).
The optional fields, when not provided, all take hopefully reasonable default values
This field is a condition.
a comma-separated list of Patch-Id's of patches that need to be pplied for this one to be considered for application.
Default is "" (plain/vanilla kernel).
This field is a condition.
a comma-separated list of the debian identifiers for archs supported by this patch.
Default is "all".
This field is NOT a condition.
a comma-separated list of Patch-Id's of patches this one depends on. Patches in this list, as opposed to those in the Kernel-flavour list, are such that this patch cannot be applied without them.
Default is "" (no dependency).
The identifier for a type of patch operation. Valid operations may include "diff", "cp", "tar", "pax", possibly depending on installed plugins. Other fields in the section will depend on the value of this field.
The name of the diff file.
the value to pass as argument to the patch(1) -p option (aka --strip).
Default is 1.
The name of the tar file.
the value to pass as argument to the patch(1) -p option (aka --strip).
Default is 0.
This option will probably require pax(1) to be applicable.
The path of the directory to copy.
The place to copy the directory to.
These are the 2 kpatches files for the kernel-debugger patch. This patch was monolithic for 2.2 kernels, and has been split for recent 2.4 kernels into an architecture-independant part and one architecture-dependant part per supported architecture.
Example 5. The architecture-independant kdb patch
Patch-name: Kernel debugger architecture-independant core
Patch-id: kdbcore
Path-strip-level: 1
Patch-file: kdb-v2.1-2.4.17-common-1
Architecture: all
Kernel-version: 2.4.17 |
Example 6. The architecture-dependant kdb patches
Patch-name: Kernel debugger
Patch-id: kdb
Path-strip-level: 1
Patch-file: kdb-v1.5-2.2.18
Architecture: i386
Kernel-version: 2.2.18
Patch-file: kdb-v2.1-2.4.17-i386-1
Architecture: i386
Kernel-version: 2.4.17
Depends: kdbcore
Patch-file: kdb-v2.1-2.4.17-ia64-011226-1
Architecture: ia64
Kernel-version: 2.4.17
Depends: kdbcore |