r3436 - in trunk/docs: . handbook
Jurij Smakov
jurij-guest@costa.debian.org
Sun, 10 Jul 2005 00:41:47 +0000
Author: jurij-guest
Date: 2005-07-10 00:41:46 +0000 (Sun, 10 Jul 2005)
New Revision: 3436
Added:
trunk/docs/handbook/
trunk/docs/handbook/Makefile
trunk/docs/handbook/kernel-handbook.sgml
trunk/docs/handbook/version.ent
Log:
Initial commit of the handbook stuff, to
generate html version install debiandoc-sgml
and run make.
Added: trunk/docs/handbook/Makefile
===================================================================
--- trunk/docs/handbook/Makefile 2005-07-10 00:33:09 UTC (rev 3435)
+++ trunk/docs/handbook/Makefile 2005-07-10 00:41:46 UTC (rev 3436)
@@ -0,0 +1,10 @@
+version := 0.0.1
+date := $(shell date)
+
+all: version.ent
+ debiandoc2html kernel-handbook.sgml
+
+version.ent:
+ rm -f $@
+ echo "<!entity version \"$(version)\">" >> $@
+ echo "<!entity date \"$(date)\">" >> $@
Added: trunk/docs/handbook/kernel-handbook.sgml
===================================================================
--- trunk/docs/handbook/kernel-handbook.sgml 2005-07-10 00:33:09 UTC (rev 3435)
+++ trunk/docs/handbook/kernel-handbook.sgml 2005-07-10 00:41:46 UTC (rev 3436)
@@ -0,0 +1,444 @@
+<!doctype debiandoc system [
+<!-- include version information so we don't have to hard code it
+ within the document -->
+<!entity % versiondata SYSTEM "version.ent"> %versiondata;
+]>
+<debiandoc>
+
+ <book>
+ <titlepag>
+ <title>Debian Linux Kernel Handbook</title>
+ <author><qref id="authors">The Debian Kernel Mailing List</qref></author>
+ <version>version &version;, &date;</version>
+
+ <abstract>
+ To be added.
+ </abstract>
+
+ <copyright>
+ <copyrightsummary>
+ Copyright © 2005 Debian Kernel Team.
+ </copyrightsummary>
+ <p>
+ This manual is free software; you may redistribute it and/or
+ modify it under the terms of the GNU General Public License
+ as published by the Free Software Foundation; either version
+ 2, or (at your option) any later version.
+ </p>
+
+ <p>
+ This is distributed in the hope that it will be useful, but
+ <em>without any warranty</em>; without even the implied
+ warranty of merchantability or fitness for a particular
+ purpose. See the GNU General Public License for more
+ details.
+ </p>
+
+ <p>
+ A copy of the GNU General Public License is available as
+ <file>/usr/share/common-licenses/GPL</file> in the Debian GNU/Linux
+ distribution or on the World Wide Web at
+ <url id="http://www.gnu.org/copyleft/gpl.html"
+ name="the GNU General Public Licence">. You can also
+ obtain it by writing to the Free Software Foundation, Inc.,
+ 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ </p>
+ </copyright>
+ </titlepag>
+
+ <toc detail="sect1">
+
+ <chapt id="scope">
+ <heading>About this handbook</heading>
+ <sect>
+ <heading>Scope</heading>
+ <p>
+ The main goal of this handbook is to serve as a single
+ access point to all kernel-related documentation. It
+ currently only contains the information about the Debian
+ packaging of Linux kernel 2.6.12 and higher.
+ </p>
+ </sect>
+ <sect id="authors">
+ <heading>Authors and Contributors</heading>
+ <p>
+ This handbook is maintained by the Debian kernel team in the
+ Debian subversion (SVN) repository. It is intended as a
+ community project, thus all the proposals for improvements
+ and contributions are welcome. The preferred way to submit a
+ contribution is to send it to the
+ <tt>debian-kernel@lists.debian.org</tt> mailing list,
+ including a <tt>[Handbook]</tt> tag in the beginning of the
+ subject. When submitting a contribution please clearly
+ identify its copyright holder and include the licensing
+ statement. Note that to be accepted the contribution must be
+ licensed under the same license as the rest of the document,
+ namely GPL version 2 or later. Below is the list of current
+ contributors:
+
+ <list>
+ <item>Jurij Smakov</item>
+ <item>Sven Luther</item>
+ <item>Andres Salomon</item>
+ </list>
+ </p>
+ </sect>
+ </chapt>
+
+
+ <chapt id="source">
+ <heading>Debian kernel source</heading>
+ <sect id="changes">
+ <heading>Changes to the pristine kernel source</heading>
+ <p>
+ The kernels in Debian are distributed in binary form, built
+ from the Debian kernel source. It is important to recognize
+ that Debian kernel source may (and in most cases is) different
+ from the upstream (or "pristine") kernel source, distributed
+ from www.kernel.org and mirrors. Due to licensing
+ restrictions, unclear license information, or failure to
+ comply with the Debian Free Software Guidelines (DFSG) parts
+ of the kernel must be removed in order to distribute the
+ source in the <tt>main</tt> section of the Debian archive. The
+ removal procedure is typically performed by a
+ <tt>prune-non-free</tt> script, available in the Debian kernel
+ SVN repository <footnote>
+ <tt>svn://svn.debian.org/kernel/trunk/scripts/prune-non-free</tt>
+ </footnote> and producing the
+ <tt>linux-kernel-<em>version</em>.orig.tar.gz</tt> tarball, which
+ serves as the original upstream source. The removed parts are
+ packaged as <tt>linux-kernel-nonfree-<em>version</em>.orig.tar.gz</tt>,
+ which serves as the original tarball for the <tt>linux-kernel-nonfree</tt>
+ package.
+
+ The drivers which are currently removed from the pristine
+ kernel source and those under consideration are listed on
+ the <url id="http://wiki.debian.net" name="Debian Wiki">
+ page <url
+ id="http://wiki.debian.net/?KernelFirmwareLicensing"
+ name="KernelFirmwareLicensing">.
+
+ </p>
+ <sect id="patches">
+ <heading>Debian kernel patches</heading>
+ <p>
+ The source from which the Debian binary kernels are built is
+ obtained by taking the source from
+ <tt>linux-kernel-<em>version</em>.orig.tar.gz</tt> (that is,
+ pristine kernel source, processed by the
+ <tt>prune-non-free</tt> script) and applying a set of Debian
+ patches. These patches typically implement essential bug and
+ security hole fixes. The Debian version of the kernel
+ packages has the form <tt><em>version-revision</em></tt>
+ where <tt><em>version</em></tt> is the upstream version of
+ the kernel (like 2.6.12) and <tt><em>revision</em></tt>
+ determines the patchlevel. For example, the packages with
+ version 2.6.12-3 are built from the
+ <tt>linux-kernel-2.6.12.orig.tar.gz</tt> source, patched up
+ to patchlevel 3. Additionally, some architectures (such as
+ HPPA) require additional architecture-specific patches for
+ the kernel to build and operate.
+ </p>
+ <p>
+ All the patches used in the process of building of the
+ Debian official kernel packages are shipped as a part of
+ <tt>linux-patch-debian</tt> package. See its description in
+ <ref id="arch-indep"> for more information about the patch system.
+ </p>
+ </sect>
+ <sect id="acceptance">
+ <heading>Policy for patch acceptance</heading>
+ <p>
+ The goal of the Debian kernel team is to keep the difference
+ between the Debian kernel source and the "pristine" kernel
+ source to a minimum. That typically means that only the
+ patches fixing security holes and serious kernel bugs are
+ going to be considered for the inclusion in the Debian kernel
+ source. The recommended procedure for inclusion of patches
+ introducing optional features is to package them as separate
+ patch packages, or to convince the upstream maintainer to
+ include them in the next kernel release.
+ </p>
+ </sect>
+ </chapt>
+
+ <chapt id="packaging">
+ <heading>Debian kernel packages</heading>
+ <sect id="arch-indep">
+ <heading>Architecture-independent packages</heading>
+ <p>
+ <taglist>
+ <tag><tt>linux-source-<em>version</em></tt></tag>
+ <item>
+ This package contains the Debian kernel source
+ tarball. The patchlevel of the source is determined by the
+ version of the package, for example the version 2.6.12-3
+ of the package <tt>linux-source-2.6.12</tt> contains the
+ version 2.6.12 of the Debian kernel source patched to patchlevel 3.
+ Once the package is installed, the source
+ tarball is available at
+ <tt>/usr/src/linux-source-<em>version</em>.tar.bz2</tt>. For the
+ instructions on obtaining Debian kernel source with arbitrary
+ patchlevel, see <ref id="common-getting">.
+ </item>
+ <tag><tt>linux-doc-<em>version</em></tt></tag>
+ <item>
+ This package contains the kernel documentation in various
+ formats. It is installed in <tt>/usr/share/doc/linux-doc-<em>version</em></tt>.
+ </item>
+ <tag><tt>linux-patch-debian-<em>version</em></tt></tag>
+ <item>
+ This package contains all patches used to produce the
+ Debian kernel source. It also contains the scripts which allow
+ application or un-application of patchsets, bringing the source
+ to the desired patchlevel. After the installation the patches
+ are installed in <tt>/usr/src</tt> as follows:
+ <taglist>
+ <tag><tt>/usr/src/kernel-patches/all/<em>version</em>/debian/</tt></tag>
+ <item>
+ This directory contains the individual patch files for a given
+ version.
+ </item>
+ <tag><tt>/usr/src/kernel-patches/all/<em>version</em>/debian/series/</tt></tag>
+ <item>
+ This directory contains the control files, which
+ determine which patches need to be applied (or
+ unapplied) to move from one patchlevel to another. These
+ are text files named
+ <tt><em>version</em>-<em>N</em></tt>, containing the list
+ of patches which need to be applied (in case when the
+ name of the patch prepended with plus) or unapplied (if
+ it is prepended with a minus) to move from patchlevel
+ <tt><em>N</em>-1</tt> to patchlevel <tt><em>N</em></tt>.
+ For example, the file <tt><em>version</em>-1</tt> lists
+ the patches which need to be applied to go from the
+ original upstream source to the patchlevel 1. Similarly,
+ the file <tt><em>version</em>-4</tt> describes the
+ patchset which makes a tree at patchlevel 4 from the one
+ at patchlevel 3.
+ </item>
+ <tag><tt>/usr/src/kernel-patches/all/<em>version</em>/apply/debian</tt></tag>
+ <item>
+ This script may be used to change the patchlevel of the
+ currently available source tree, when run from its
+ top-level directory. For usage example see <ref id="common-getting">.
+ </item>
+ <tag><tt>/usr/src/kernel-patches/diffs/<em>arch</em>_<em>uversion</em>/</tt></tag>
+ <item>
+ Some architectures (actually, only <tt>hppa</tt> at time of writing) require extra
+ changes to the upstream kernel source in order to produce a working kernel.
+ This directory contains the patches specific to architecture <tt><em>arch</em></tt>
+ (if any), which are applied (in addition to other architecture-independent Debian
+ patches) to build the official Debian kernel for this architecture.
+ <tt><em>uversion</em></tt> in the name stands for the upstream kernel version with
+ dots replaced by underscores, for example 2_6_12 for kernel version 2.6.12. This
+ layout and naming scheme ensure that the extra patches may be applied automatically
+ during kernel build by passing
+ the <tt>--added-patches</tt> argument to <tt>make-kpkg</tt>.
+ </item>
+ <tag><tt>/usr/src/kernel-patches/<em>arch</em>/apply/<em>arch</em>_<em>uversion</em></tt></tag>
+ <item>
+ This script applies the architecture-specific patch for architecture
+ <tt><em>arch</em></tt> and version correspoinding to <tt><em>uversion</em></tt>.
+ It is not intended to be run directly, but rather invoked by <tt>make-kpkg</tt> when
+ the <tt>--added-patches</tt> argument is specified on the command line. For more
+ information see <ref id="common-building"> and <tt>kernel-package</tt> documentation.
+ </item>
+ </taglist>
+ </item>
+ <tag><tt>linux-tree-<em>version</em></tt></tag>
+ <item>
+ This is a dummy package whose sole purpose is to satisfy
+ the build dependencies for a successful kernel build. In
+ the old kernel build system build-depending on the package
+ <tt>linux-tree-<em>version</em>-<em>N</em></tt>, provided
+ by the <tt>linux-tree-<em>version</em></tt>, would result
+ in the automatic installation of all the required source
+ and patch packages, and patching of the kernel source to
+ patchlevel <tt><em>N</em></tt> before building. It has
+ been obsoleted by the new common packaging system
+ introduced since kernel 2.6.12 and is provided only for
+ backward compatibility with architectures, not controlled
+ by the Debian kernel team.
+ </item>
+ </taglist>
+ </p>
+ </sect>
+ <sect id="arch-dep">
+ <heading>Architecture-dependent packages</heading>
+ </sect>
+ <sect id="other-pkg">
+ <heading>Other kernel-related packages</heading>
+ </sect>
+ </chapt>
+ <chapt id="common-tasks">
+ <heading>Common kernel-related tasks</heading>
+ <sect id="common-getting">
+ <heading>Obtaining the Debian kernel source</heading>
+ <p>
+ To get the Debian kernel source at the current maximum patchlevel,
+ it is sufficient to install the latest <tt>linux-source-<em>version</em></tt>
+ package and unpack the source, for example:
+ <list compact="compact">
+ <item><tt>apt-get install linux-source-2.6.12</tt></item>
+ <item><tt>tar jxf /usr/src/linux-source-2.6.12.tar.bz2</tt></item>
+ </list>
+ The unpacked source tree then will be available in <tt>linux-source-2.6.12</tt> directory.
+ </p>
+
+ <p>
+
+ In order to get the Debian kernel source at the patchlevel
+ <em>different</em> from the one provided by the current
+ <tt>linux-source-<em>version</em></tt> package, one should
+ first install and unpack it, then roll back the unneeded
+ patch sets using a script from the <tt>linux-patch-debian-<em>version</em></tt>
+ package. We assume that in the steps mentioned in the
+ previous example the version 2.6.12-3 of the
+ <tt>linux-source-2.6.12</tt> package was installed and
+ unpacks, so that the Debian kernel source at patchlevel 3 is
+ available in the <tt>linux-source-2.6.12</tt> directory. It
+ can then be rolled back to the desired patchlevel (1 in the
+ example below) by running
+ <list compact="compact">
+ <item><tt>apt-get install linux-patch-debian-2.6.12</tt></item>
+ <item><tt>cd linux-source-2.6.12</tt></item>
+ <item><tt>/usr/src/kernel-patches/all/2.6.12/apply/debian 2.6.12-1</tt></item>
+ </list>
+ The last command will <em>unapply</em> the set of patches,
+ which lead from patchlevel 1 to patchlevel 3 and the
+ resulting tree will appear as if it came from the version
+ 2.6.12-1 of the <tt>linux-source-2.6.12</tt> package. This
+ system ensures that the source code for any revision of the
+ Debian kernel source may be recovered from the latest one,
+ without keeping multiple copies of the source in the
+ archive.
+ </p>
+
+ <p>
+
+ The version <tt><em>version</em>-<em>N</em></tt> (like
+ 2.6.12-3) of the <tt>linux-patch-debian-<em>version</em></tt>
+ package contains all the individual patches applied to the
+ source to achieve any patchlevel up to <tt><em>N</em></tt>.
+ They are stored in the directory
+ <tt>/usr/src/kernel-patches/all/<em>version</em>/debian/</tt>.
+
+
+ </p>
+
+ </sect>
+ <sect id="common-official">
+ <heading>Rebuilding an official Debian kernel package</heading>
+ <p>
+ To locally build a kernel image identical to the one
+ distributed in the Debian archive use the following
+ procedure:
+ <taglist>
+ <tag><tt>apt-get source linux-kernel-<em>version</em></tt></tag>
+ <item>
+ This will download an unpack the
+ <tt>linux-kernel-<em>version</em></tt> source package,
+ making the tree available in the
+ <tt>linux-kernel-<em>version</em></tt> directory. As
+ always, the revision of this package (for example, 3 in
+ 2.6.12-3) will determine its patchlevel with respect to
+ the original upstream kernel source.
+ </item>
+ <tag><tt>apt-get install build-essential fakeroot</tt></tag>
+ <tag><tt>apt-get build-dep linux-kernel-<em>version</em></tt></tag>
+ <item>
+ The last two commands will install the build dependencies required by the kernel
+ build process.
+ </item>
+ <tag><tt>cd linux-kernel-<em>version</em></tt></tag>
+ <tag><tt>fakeroot debian/rules binary</tt></tag>
+ <item>
+ The last command will start the kernel build and should
+ result in creation of the kernel packages, identical to
+ the official ones in the original directory (in which
+ the source package was unpacked). It is possible to
+ specify the targets <tt>binary-arch</tt> or
+ <tt>binary-indep</tt> targets instead of the
+ <tt>binary</tt>, if only architecture-dependent (such as
+ the <tt>linux-image</tt>) or architecture-independent
+ packages are required. It is possible to further
+ restrict the build to only the desired flavours of the
+ kernel images by supplying the <tt>flavours</tt>
+ variable on the command line. For example, the command
+ <example>
+ fakeroot debian/rules flavours=686 binary-arch
+ </example>
+ will only build the official kernel image
+ (<tt>linux-image</tt> binary package) for the 686
+ flavour on i386 architecture.
+ </item>
+ </taglist>
+ </p>
+
+ <p>
+ To build the official kernel using the Debian kernel source
+ at the lower patchlevel, than the one provided by the
+ <tt>linux-source-<em>version</em></tt> source package,
+ adjust the <tt>ltver</tt> variable at the top of the
+ <tt>debian/rules</tt> file to the desired patchlevel after
+ unpacking. You may also want to edit the first line of
+ <tt>debian/changelog</tt> to contain the correct version
+ <tt><em>version</em>-<em>patchlevel</em></tt> (in
+ brackets). After that proceed with the build as described
+ above.
+ </p>
+
+ <p>
+ It is possible to apply extra patches to the tree before
+ starting the build. To do that, before invoking the
+ <tt>binary</tt> or <tt>binary-arch</tt> target, use the
+ <tt>unpack</tt> target to unpack the tree and prepare it for
+ a build:
+ <example>
+ fakeroot debian/rules flavours=686 unpack
+ </example>
+ This will unpack the kernel tree in the
+ <tt>debian/build-none-686</tt> directory, where the extra
+ patches may be applied. After that the <tt>binary</tt> or
+ <tt>binary-arch</tt> target may be invoked to complete the
+ build, as described above.
+ </p>
+ </sect>
+ <sect id="common-building">
+ <heading>Building a custom kernel from Debian kernel source</heading>
+ <p>
+ It is recommended to use the <tt>make-kpkg</tt> command from the <tt>kernel-package</tt>
+ package to perform the kernel builds in Debian. A simple example is included here for
+ reference, full documentation for <tt>make-kpkg</tt> is available in its manpage
+ (<tt>man make-kpkg</tt>) and <tt>/usr/share/doc/kernel-package/README.gz</tt> file.
+ </p>
+ </sect>
+ <sect id="common-out-of-tree">
+ <heading>Building out-of-tree kernel modules</heading>
+ </sect>
+ <sect id="common-debian-patches">
+ <heading>Building kernels with packaged patches</heading>
+ </sect>
+ <sect id="common-ext-patches">
+ <heading>Building kernels with third-party patches</heading>
+ </sect>
+ </chapt>
+ <chapt id="initrd">
+ <heading>Managing the initial RAM disk (initrd) image</heading>
+ </chapt>
+ <chapt id="bugs">
+ <heading>Filing a bug against a kernel package</heading>
+ </chapt>
+ <chapt id="developer">
+ <heading>Information for developers of the kernel packages</heading>
+ <sect id="dev-patches">
+ <heading>Packaging the kernel patches</heading>
+ </sect>
+ <sect id="dev-modules">
+ <heading>Packaging third-party kernel modules</heading>
+ </sect>
+ </chapt>
+ </book>
+</debiandoc>
+<!-- vim:set ai et sts=2 sw=2 tw=76: -->
Added: trunk/docs/handbook/version.ent
===================================================================
--- trunk/docs/handbook/version.ent 2005-07-10 00:33:09 UTC (rev 3435)
+++ trunk/docs/handbook/version.ent 2005-07-10 00:41:46 UTC (rev 3436)
@@ -0,0 +1,2 @@
+<!entity version "0.0.1">
+<!entity date "Fri Jul 1 18:56:40 EDT 2005">