.\" Hey, Emacs! This is an -*- nroff -*- source file.
.\" Copyright (c) 1997 Manoj Srivastava <srivasta@debian.org>
.\"
.\" This is free documentation; you can 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 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
.\" USA.
.\"
.\"
.\"    $Id: make-kpkg.8,v 1.24 2000/03/21 07:04:43 srivasta Exp $
.\"
.TH MAKE\-KPKG 8 "May 2 1997" "Debian" "Debian GNU/Linux manual"
.SH NAME
make\-kpkg \- build Debian kernel packages from Linux kernel sources
.SH SYNOPSIS
.B make\-kpkg
.I [options]
\&[target [target ...]]
.SH DESCRIPTION
This manual page explains the Debian
.B "make\-kpkg"
utility, which is used to create the kernel related 
Debian 
packages. This utility needs to be run from a top level 
Linux
kernel source directory.
.SH OPTIONS
.B \-\-help
Print out a usage message.
.TP
.BR \-\-revision " number"
Sets the Debian revision number for the packages produced to the argument
.BR number.
This has certain constraints: the --revision option only has an effect
during the configure phase (in other words, if a file called
.I stamp\-configure
exists, this option has no effect \-\- run 
.B make\-kpkg clean 
or manually remove
.I stamp\-configure 
and 
.I stamp-debian
for it to have an effect -- I strongly suggest you run
.B make\-kpkg clean 
unless you know what you are doing). 
Additionally, official source package maintianers provide their own
version numbers and data for the official uploads, and hence a number
of things, including the
.B Debian
revision, is not modified by
.B make-kpkg.
If you happen to have an official sources, (that would mean that the
file 
.I debian/official
exists), and want to use your own revision number,
make sure you remove
.I debian/official
before running  
.B make\-kpkg clean 
for this option to have an effect.
So, if you want to re\-run 
.B make\-kpkg 
with a different revision number, you have to make sure you start with
a clean slate.
Secondly, the version may contain only alphanumerics and the characters +
. - (full stop, hyphen, and plus) and must contain a digit. (Look at
Chapter 5 of the Programmers manual for details). Optionally,
you may prepend the revision with a digit followed by a colon (:)
.TP
.BR \-\-flavour\ foo
Sets the kernel flavour to the argument \fBfoo\fR. The flavour is
also appended to the package name. You need a patched Makefile to make
this work propperly (see /usr/share/doc/kernel-package/\s-1Flavours\s0.gz).
It may contain only alphanumerics and the characters \- + . (full
stop, hyphen, and plus). Uppercase letter are also not permitted under
the Policy for a new package. \fB\s-1NOTE\s0\fR: Hyphens are
discouraged.  (Look at Chapters 4 and 5 of the Programmers manual for
details). Please note that you shall need to 
.B make-kpkg 
.I clean
.B FIRST
if you wish to recompile the kernel-image using a flavour.
.TP
.BR \-\-arch\ foo
This is useful for setting the architecture when you are cross
compiling. If you are not cross compiling, the architecture is
determined automatically.
.TP
.BR \-\-cross_compile\ foo
This is useful for setting the target string when you are cross
compiling. 
.TP
.BR \-\-subarch\ foo
Some architectures (the Alpha, and the m68k) require a different
kernel for each subarchitecture. This option provides a way of
specifying it as an argument to \fBmake-kpkg\fR. \fBPlease note\fR
that additional support for sub architectures may be required in the
kernel sources to actually make this do anything.
.TP
.BR \-\-subarch\ foo
Some architectures (the Alpha, and the m68k) require a different
kernel for each subarchitecture. This option provides a way of
specifying it as an argument to \fBmake-kpkg\fR. \fBPlease note\fR
that additional support for sub architectures may be required in the
kernel sources to actually make this do anything.
.TP
.BR \-\-arch_in_name
This option uses an extended name for the kernel image package by
embedding the subarchitecture in the image name, so one could write a
script to create multiple subarchitectures one after the other. You
may also do this by setting the environment variable
.B ARCH_IN_NAME. 
\fBPlease note\fR that only the package
.I name
is affected, not modules locations etc.
.TP
.BR \-\-pgpsign " name"
Set the string used to sign the 
.B changes 
file for any external modules in 
.IR /usr/src/modules/
using PGP. This option will override the builtin default and the site
wide customizations stored in the file
.IR /etc/kernel-pkg.conf.
.TP
.B \-\-targets
Prints out a list of known targets. See the Section
.B Targets 
below.
.TP
.B \-\-noexec
Pass a 
.B \-n
option to the 
.I make
process so that commands are merely printed to the screen but not actually
executed. This is very useful for debugging.
.TP
.B \-\-zimage
Makes a zImage kernel rather than a bzImage kernel (the default).
Useful for people having problems with bzImage kernels. 
.TP
.B \-\-bzimage
Makes a bzImage kernel. Useful for people who want a bzImage kernel on
sites where the default is zImage kernels. 
.TP
.B \-\-rootcmd
The command that provides a means of gaining super user access (for
example, `sudo' or `fakeroot') as needed by dpkg-buildpackages's -r
option. This is only relevant for the buildpackage target.
.TP
.B \-\-us
This option is passed to dpkg-buildpackage, and directs that package
not to sign the source. This is only relevant for the buildpackage
target.  
.TP
.B \-\-uc
This option is passed to dpkg-buildpackage, and directs that package
not to sign the changelog. This is only relevant for the buildpackage
target.  
.PP
The options maybe shortened to the smallest unique string, and may
be entered with either a \- or a \-\- prefix, and you may use a space
or an = symbol between an option string and a value.
.SH TARGETS
.TP
.B clean
Cleans the kernel source directory of all files created by target
.B build,
and runs a make distclean. (Please look at a Linux kernel Makefile for
details).  Please note that although we take care of the list of
current kernel configuration contained in the file
.I .config,
the file 
.I include/linux/autoconf.h
is not preserved.
.TP
.B buildpackage
This target runs the targets 
.B clean, 
and
.B binary,
and produces the complete package using 
.B dpkg-buildpackage
.TP
.B binary
This target produces all four Debian kernel packages by running the
targets
.B kernel_source, kernel_headers, kernel_doc
and
.B kernel_image.
.TP
.B kernel_source
This target produces a debianised package of the Linux kernel sources.
.TP
.B kernel_headers
This target produces a Debian package containing the header files
included in the Linux kernel.
.TP
.B kernel_doc
This target produces a Debian package containing the documentation
included in the Linux kernel.
.TP
.B kernel_image
This target produces a Debian package of the Linux kernel source
image, and any modules configured in the kernel configuration file
.I .config.
If there is no 
.I .config
file in the kernel source directory, a default configuration is
provided similar to the one used to create the
.B Debian
boot\-floppies.  At install time, it updates symbolic links in the root
directory to point to the new kernel image in
.I /boot.
On installation, it also offers to run the Linux loader,
.I LILO,
creating a configuration file for 
.I LILO
if needed. At that time it also offers to put the new kernel on a
floppy, formatting the floppy if needed.  On deletion, the package
checks the version of the kernel running, and refuses to delete a
running kernel.
.TP
.B build
This target, used by target
.B kernel_image
above, compiles the 
Linux
kernel image.
.TP
.B modules
This target allows you to build all add-on modules and packages that are
very dependent on the precise kernel version they are compiled for at the
same time you build your kernel image.  This target expects to find the 
modules or packages under /usr/src/modules, and, for all such directories,
changes to /usr/src/modules/x, and runs the 
.B kdist
rule in the local 
.I debian.rules
file. This target should create the 
.B Debian
module package(s), and may also produce a compressed tar file, and a
compressed diff file, with
.I md5sums
recorded in a changes file using
.B dpkg-genchanges.
The file is signed by the same identity that would be used to sign the
kernel packages. This option is used by maintainers uploading the
package to the Debian archives. 
.TP
.B modules_config
This target allows you to configure all packages under
.B /usr/src/modules.
This is useful if you need to manually modify some aspects of the
configuration, or if you want to manually compile the add on modules. 
.TP
.B modules_image
This target allows you to build all packages under
.B /usr/src/modules,
but does not create the source or diff files, and does not create and sign
a changes file. This is the only modules related option you need if
you just want to compile the add on modules image files for
installation on one or more machines.
.TP
.B modules_clean
This target allows you to clean all packages under
.B /usr/src/modules,
and this sould be all that is needed to undo the effect of any of the
other modules_ targets.
.TP
.B configure
This target runs configure (actually,
.B oldconfig)
early, so you may edit files generated by
.B make config
in the kernel source directory and not have them stomped by 
.B make\-kpkg 
later.
.TP
.B libc\-kheaders
This is a special target for the libc-dev maintainer, who can use ot
to create the headers package that libc needs. Please note that it is
dangerous to create a libc-kheaders package that is different fomr the
headers libc was compiled with; it is
.B known
to subtly break systems. Please look at 
.I /usr/share/kernel-package/README.headers
for details.  Creating and installing a self created libc-kheaders
package may break your system unless you know what you are doing. You
have been warned.
.SH FILES
Apart from the runtime options, the 
.I debian.rules
file run by
.B make\-kpkg
also looks for site\-wide defaults in the file 
.I /etc/kernel-pkg.conf.
The default configuration allows there to be a site wide override for
the full name and email address of the person responsible for maintaining 
the kernel packages on the site, but the 
.I /etc/kernel-pkg.conf
file is actually a 
Makefile
snippet, and any legal make directives may be included in there. 
.B Note:
Caution is urged with this file, since you can totally change the way that the 
make is run by suitable editing this file. Please look at
.I /usr/share/doc/kernel-package/Problems.gz
for a list of known problems while compiling kernel images. Extensive
tutorial like documentation is also available in
.I /usr/share/doc/kernel-package/README.gz
and it is recommended that one read that before using this utility.
.SH "SEE ALSO"
.BR kernel-pkg.conf (5),
.BR kernel-img.conf (5),
.BR dpkg-deb (1),
.BR dpkg-source (1),
.BR make (1),
.BR The\ Programmers\ manual, 
.BR The\ GNU\ Make\ manual,
and the extensive documentation in the directory 
.B /usr/share/doc/kernel-package
.SH AUTHOR
This manual page was written by Manoj Srivastava <srivasta@debian.org>,
for the Debian GNU/Linux system.