move manual to top-level directory, split out of debian-installer package

1 files changed, 182 insertions, 0 deletions

diff --git a/nl/post-install/kernel-baking.xml b/nl/post-install/kernel-baking.xml
new file mode 100644
index 000000000..cc4c7bed7
--- /dev/null
+++ b/nl/post-install/kernel-baking.xml
@@ -0,0 +1,182 @@
+<!-- retain these comments for translator revision tracking -->
+<!-- original version: 28672 untranslated -->
+
+ <sect1 id="kernel-baking"><title>Compiling a New Kernel</title>
+<para>
+
+Why would someone want to compile a new kernel? It is often not
+necessary since the default kernel shipped with Debian handles most
+configurations. However, it is useful to compile a new kernel in order
+to:
+
+<itemizedlist>
+<listitem><para>
+
+handle special hardware needs, or hardware conflicts with the pre-supplied
+kernels
+
+</para></listitem>
+<listitem><para>
+
+handle hardware or options not included in the stock kernel, such as
+APM or SMP
+
+</para></listitem>
+<listitem><para>
+
+optimize the kernel by removing useless drivers to speed up boot
+time
+
+</para></listitem>
+<listitem><para>
+
+use options of the kernel which are not supported by the default
+kernel (such as high memory support)
+
+</para></listitem>
+<listitem><para>
+
+run an updated or development kernel
+
+</para></listitem>
+<listitem><para>
+
+impress your friends, try new things
+
+</para></listitem>
+</itemizedlist>
+
+</para>
+
+  <sect2><title>Kernel Image Management</title>
+<para>
+
+Don't be afraid to try compiling the kernel.  It's fun and profitable.
+
+</para><para>
+
+To compile a kernel the Debian way, you need some packages:
+<classname>kernel-package</classname>,
+<classname>kernel-source-&kernelversion;</classname> (the most recent version
+at the time of this writing), <classname>fakeroot</classname> and a
+few others which are probably already installed (see
+<filename>/usr/share/doc/kernel-package/README.gz</filename> for the
+complete list).
+
+</para><para>
+
+This method will make a .deb of your kernel source, and, if you have
+non-standard modules, make a synchronized dependent .deb of those
+too. It's a better way to manage kernel images;
+<filename>/boot</filename> will hold the kernel, the System.map, and a
+log of the active config file for the build.
+
+</para><para>
+
+Note that you don't <emphasis>have</emphasis> to compile your kernel
+the <quote>Debian way</quote>; but we find that using the packaging system
+to manage your kernel is actually safer and easier.  In fact, you can get
+your kernel sources right from Linus instead of
+<classname>kernel-source-&kernelversion;</classname>, yet still use the
+<classname>kernel-package</classname> compilation method.
+
+</para><para>
+
+Note that you'll find complete documentation on using
+<classname>kernel-package</classname> under
+<filename>/usr/share/doc/kernel-package</filename>.  This section just
+contains a brief tutorial.
+
+</para><para>
+
+Hereafter, we'll assume you have free rein over your machine and will
+extract your kernel source to somewhere in your home directory<footnote>
+
+<para>
+
+There are other locations where you can extract kernel sources and build
+your custom kernel, but this is easiest as it does not require special
+permissions.
+
+</para>
+
+</footnote>. We'll also assume that your kernel version is
+&kernelversion;. Make sure you are in the directory to where you want to
+unpack the kernel sources, extract them using <userinput>tar xjf
+/usr/src/kernel-source-&kernelversion;.tar.bz2</userinput> and change
+to the directory <filename>kernel-source-&kernelversion;</filename>
+that will have been created.
+
+</para><para>
+
+Now, you can configure your kernel.  Run <userinput>make
+xconfig</userinput> if X11 is installed, configured and being run; run
+<userinput>make menuconfig</userinput> otherwise (you'll need
+<classname>libncurses5-dev</classname> installed). Take the time to read
+the online help and choose carefully. When in doubt, it is typically
+better to include the device driver (the software which manages
+hardware peripherals, such as Ethernet cards, SCSI controllers, and so
+on) you are unsure about.  Be careful: other options, not related to a
+specific hardware, should be left at the default value if you do not
+understand them.  Do not forget to select <quote>Kernel module loader</quote>
+in <quote>Loadable module support</quote> (it is not selected by default).
+If not included, your Debian installation will experience problems.
+
+</para><para>
+
+Clean the source tree and reset the <classname>kernel-package</classname>
+parameters.  To do that, do <userinput>make-kpkg clean</userinput>.
+
+</para><para>
+
+Now, compile the kernel:
+<userinput>fakeroot make-kpkg --revision=custom.1.0 kernel_image</userinput>.
+The version number of <quote>1.0</quote> can be changed at will; this is just
+a version number that you will use to track your kernel builds.
+Likewise, you can put any word you like in place of <quote>custom</quote>
+(e.g., a host name).  Kernel compilation may take quite a while, depending on
+the power of your machine.
+
+</para><para condition="supports-pcmcia">
+
+If you require PCMCIA support, you'll also need to install the
+<classname>pcmcia-source</classname> package.  Unpack the gzipped tar file
+as root in the directory <filename>/usr/src</filename> (it's important that
+modules are found where they are expected to be found, namely,
+<filename>/usr/src/modules</filename>).  Then, as root, do <userinput>make-kpkg
+modules_image</userinput>.
+
+</para><para>
+
+Once the compilation is complete, you can install your custom kernel
+like any package.  As root, do <userinput>dpkg -i
+../kernel-image-&kernelversion;-<replaceable>subarchitecture</replaceable>_custom.1.0_&architecture;.deb</userinput>.
+The <replaceable>subarchitecture</replaceable> part is an optional
+sub-architecture,
+<phrase arch="i386"> such as <quote>i586</quote>, </phrase>
+depending on what kernel options you set.
+<userinput>dpkg -i kernel-image...</userinput> will install the
+kernel, along with some other nice supporting files.  For instance,
+the <filename>System.map</filename> will be properly installed
+(helpful for debugging kernel problems), and
+<filename>/boot/config-&kernelversion;</filename> will be installed,
+containing your current configuration set.  Your new
+<classname>kernel-image-&kernelversion;</classname> package is also clever
+enough to automatically use your platform's boot-loader to run an
+update on the booting, allowing you to boot without re-running the
+boot loader.  If you have created a modules package, e.g., if you have
+PCMCIA, you'll need to install that package as well.
+
+</para><para>
+
+It is time to reboot the system: read carefully any warning that the
+above step may have produced, then <userinput>shutdown -r now</userinput>.
+
+</para><para>
+
+For more information on <classname>kernel-package</classname>, read
+the fine documentation in <filename>/usr/share/doc/kernel-package</filename>.
+
+</para>
+  </sect2>
+ </sect1>