Provided by:
kernel-package_11.001_all 
NAME
make-kpkg - build Debian kernel packages from Linux kernel sources
SYNOPSIS
make-kpkg [options] [target [target ...]]
DESCRIPTION
This manual page explains the Debian 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, which has been
previously configured (unless you are using the configure target).
Normally, if kernel-package does not find a .config file in the current
directory, it tries very hard to get an appropriate one (usually a
config file already tailored for debian kernels for that architecture),
and then calls make oldconfig to let the user answer any new questions.
Typically, you run this command as root, or under fakeroot, or tell
make-kpkg how to become root, like so:
make-kpkg --rootcmd fakeroot kernel_image
The Debian package file is created in the parent directory of the
kernel source directory where this command is run.
Also, please note that some versions of gcc do not interact well with
the kernel sources (gcc 2.95 has problems compiling the kernel without
the flag ’-fno-strict-aliasing’. This issue has been taken care of for
recent kernels (2.2 and 2.4 series are fine) (I think you may have to
edit the makefile for older kernels, or something). You may control
which version of gcc used in kernel compilation by setting the Makefile
variables CC and HOSTCC in the top level kernel Makefile. You can do
this simply by
% MAKEFLAGS="CC=gcc-2.95" make-kpkg ...
(please see the top level kernel Makefile for variables that can be
set).
WARNING: Do NOT set the -j option in MAKEFLAGS directly, this shall
cause the build to fail. Use CONCURRENCY_LEVEL as specified below.
OPTIONS
--help Print out a usage message.
--revision number
Changes the Debian revision number for the packages produced to
the argument number. This has certain constraints: the
--revision option only has an effect during the configure phase
(in other words, if a file called stamp-configure exists, this
option has no effect -- run make-kpkg clean or manually remove
stamp-configure and stamp-debian for it to have an effect -- I
strongly suggest you run make-kpkg clean unless you know what
you are doing). Additionally, official source package
maintainers provide their own version numbers and data for the
official uploads, and hence a number of things, including the
Debian revision, is not modified by make-kpkg. If you happen to
have an official source, (that would mean that the file
debian/official exists, and is not empty), and want to use your
own revision number, make sure you remove debian/official before
running make-kpkg clean for this option to have an effect. So,
if you want to re-run 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 ~ + . (tilde, full stop and plus) and must contain a
digit. (Look at the Policy manual for details). Actually, that
is a lie: official kernel and modules maintainers have special
dispensation to use hyphens, but it is strongly deprecated for
most people, since no sanitization of the version number is
done, and dpkg and friends may choke on it at the end of the
compile unless one knows what one is doing. Optionally, you may
prepend the revision with a digit followed by a colon (:). The
default is 10.00.Custom unless the environment variable
DEBIAN_REVISION_MANDATORY is set, in which case an error is
generated if the revision is not set on the command line or the
configuration file.
--append-to-version foo
--append_to_version foo
This argument ( foo ) is appended to the value of the
EXTRAVERSION variable present in the kernel Makefile. Since
EXTRAVERSION is a component of the kernel version, it is also
added to the Debian package name, and, as such must obey the
policy governing the package name. That means it may contain
only lowercase alphanumerics and the characters ~ - + . (tilde,
full stop, hyphen, and plus). Uppercase letters are not
permitted under the Policy for a new package. If the
environment variable IGNORE_UPPERCASE_VERSION is set, make-kpkg
shall lower case version numbers set in the Makefile or in the
localversion file. This option over rides the environment
variable APPEND_TO_VERSION Please note that you must run a
make-kpkg clean after configuring the kernel using make
(x|menu)?config, since that creates the file
include/linux/version.h without the append_to_version data
(foo). This file won’t be updated by the make-kpkg run
(make-kpkg creates version.h if it doesn’t exist, but doesn’t
touch if exists), so the final kernel will _not_ have the
append_to_version data in its version number it shall look for
the modules and symbols in all the wrong places. The simplest
solution is either to remove include/linux/version.h after
configuring and before compiling, or running make-kpkg clean
after configuring, before compiling. Note also that once you
use --append_to_version foo for configuring, or building the
kernel-image, you need to also use the same option in any later
invocation of make-kpkg (say, for building stand alone modules,
or something). make-kpkg does not remember the argument foo in
between invocations (this is different from the behavior of
--revision, which we do remember in between invocations). If you
are annoyed by make-kpkg whining about using --append_to_version
and there already being a version.h file from before, you can
set the environment variable VERSION_H_OK which shall shut off
the warning.
--added-modules foo
--added_modules foo
The argument should be a comma separated list of additional
add-on modules (not in the main kernel tree) that you wish to
build when you invoke the modules_blah targets. You may give
full path names of the directory the modules reside in, or just
the module name if it can be found in MODULE_LOC, which defaults
to /usr/src/modules. The default is that all modules in
MODULE_LOC, are compiled when the modules_blah targets are
invoked.
--added-patches foo
--added_patches foo
The argument should be a comma separated list of additional
patches to the kernel sources. This automatically sets the
patch_the_kernel configuration option to YES.
Unlike the treatment of the modules, you may only give the patch
file basename (not the full path name of the patch file).
Additionally, any patch that tries to change the version number,
either by editing the Makefile, or by adding a .localversion
file, is not supported, and will break the compilation, since
the version number has already been fixed in debian/changelog.
For each file <patch_name> in the list, the following process is
followed: If the file can be found in the directories
ALL_PATCH_DIR/{apply,unpatch}/, then the file
ALL_PATCH_DIR/apply/<patch_name> shall be executed in turn
during the configure phase (and presumably this applies the
patch). Correspondingly, the file
ALL_PATCH_DIR/unpatch/<patch_name> shall be executed in the
clean phase. The default is that all patches are applied by
running all the executable files in ALL_PATCH_DIR/apply/ if
requested (Either by setting the configuration option
patch_the_kernel or the environment variable PATCH_THE_KERNEL to
YES). Please note that the patches are UN-installed from the
source when you run the clean target. This cleanup can be
prevented by setting the environment variable
NO_UNPATCH_BY_DEFAULT
In the above, ALL_PATCH_DIR defaults to a subdirectory of
/usr/src/kernel-patches/.
Some times it would be convenient to have the patches applied
when one asks for specific patches using this option, without
also having to explicitly set the environment variable. Since
setting the environment variable PATCH_THE_KERNEL to YES could
be dangerous, (for in that case all patches may be installed
when you want none, and did not specify the added_patches
option), You may also set the variable PATCH_THE_KERNEL to AUTO,
in which case PATCH_THE_KERNEL shall be set to YES for you when
you invoke --added-patches foo, but not otherwise. Also, please
note that if any patch installs a script in ./debian/image.d/
directory, run-parts shall be called on that directory just
before the kernel image package is built. The location of the
root of the image package being built shall be passed in the
environment variable IMAGE_TOP, and the kernel versions is
passed in through the environment variable version. This is a
way for the patch to insert any additional files into the image,
for example.
Some of the patch packages also pay attention to other
environment variables, and these are documented in the
appropriate doc directory (for example, you should look at
/usr/share/doc/kernel-patch-foo/README-kernelpatch.Debian for
patch foo for additional information).
--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. The same effect can be achieved by
setting the environment variable KPKG_ARCH. The value should be
whatever DEB_HOST_ARCH_CPU contains when dpkg-architecture is
run on the target machine, or it can be an other architecture in
a multi-arch set (like i386/amd64).
--cross-compile foo
--cross_compile foo
This is useful for setting the target string when you are cross
compiling. Use the dummy target "-" if you are building for
other arches of a multiarch set, like i386/amd64. The same
effect can be achieved by setting the environment variable.
Please note that this does not in any way set the compiler the
kernel build process shall use; if the default compiler that the
build process comes up with is not the one desired, please
explicitly specify the compiler that should be used.
CROSS_COMPILE
--subarch foo
Some architectures (the Alpha, and the m68k) require a different
kernel for each sub-architecture. This option provides a way of
specifying it as an argument to make-kpkg. Please note that
additional support for sub-architectures may be required in the
kernel sources to actually make this do anything. The same
effect can be achieved by setting the environment variable
KPKG_SUBARCH
--arch-in-name
--arch_in_name
This option uses an extended name for the kernel image package
by embedding the sub-architecture in the image name, so one
could write a script to create multiple sub-architectures one
after the other. You may also do this by setting the environment
variable ARCH_IN_NAME. Please note that only the package name
is affected, not modules locations etc.
--pgpsign name
Set the string used to sign the changes file for any external
modules in /usr/src/modules/ using PGP. This option will
override the builtin default and the site wide customizations
stored in the file /etc/kernel-pkg.conf or ~/.kernel-pkg.conf.
--config target
Change the type of configure done from the default oldconfig.
target must be one of oldconfig, config, menuconfig, gconfig,
xconfig, randconfig,, defconfig, allmodconfig, allyesconfig,
allnoconfig; old, menu, g, or x.
This option is particularly useful when using PATCH_THE_KERNEL
if some of the patches change what configuration options are
available. Note however that make-kpkg scans the config file at
startup for some options, notably the fact that modules are
enabled or not, so toggling the status during the delayed
configuration results in an error. If needed, create the
configuration file as close to the desired one before calling
make-kpkg with this switch.
--targets
Prints out a list of known targets. See the Section Targets
below.
--noexec
Pass a -n option to the make process so that commands are merely
printed to the screen but not actually executed. This is very
useful for debugging.
--verbose
This calls make with the -V=1 option, which calls out the top
level Make commands, also useful in seeing what is happening.
--initrd
If make-kpkg is generating a kernel-image package, perform any
actions necessary for a kernel loaded using initrd. NOTE: in
older kernels, this required a non-standard cramfs initrd patch
to the kernel sources, (unless the mkinitrd configuration was
modified not to use cramfs) or may result in a unbootable
kernel. The patch was usually present in the kernel sources
shipped by Debian. Some architectures still need patches to fix
cramfs problems. This option may include extra dependencies, and
modifications to maintainer scripts. It has no effect when
make-kpkg is not making a kernel-image package. The same effect
can be achieved by setting the environment variable INITRD to
any non empty value.
--zimage
Makes a zImage kernel rather than a bzImage kernel (the
default). Useful for people having problems with bzImage
kernels.
--bzimage
Makes a bzImage kernel. Useful for people who want a bzImage
kernel on sites where the default is zImage kernels.
--mkimage
This should be a command that produces an initrd image given a
directory. It is passed to the mkinitrd program’s -m option. For
example, it can be
"genromfs -d %s -f %s" or
"mkcramfs %s %s"
--rootcmd foo
The command that provides a means of gaining super user access
(for example, ‘sudo’ or ‘fakeroot’) as needed by
dpkg-buildpackage’s -r option.
--stem foo
Call the packages foo-* instead of kernel-*. This is useful in
helping transition from calling the packages kernel-* to linux-*
packages, in preparation for non-linux kernels in the
distribution. The default is linux.
--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.
--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.
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. You may also use the form
option=value; for details these and other variant forms supported,
please read man Getopt::Long (3perl).
CONCURRENCY_LEVEL
If defined, this environment variable sets the concurrency level
of make used to compile the kernel and the modules set using -j
flags to the sub make in the build target of make-kpkg. Should
be a (small) integer, if used. You can get the current number of
CPUs using the command:
"grep -c ’^processor’ /proc/cpuinfo" WARNING: Do NOT set the -j
option in MAKEFLAGS directly, this shall call the build to fail.
TARGETS
clean Cleans the kernel source directory of all files created by
target 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 .config, the file include/linux/autoconf.h is not
preserved. This target should not be combined with other
targets, since make-kpkg reads in all data before running any
target, so the subsequent targets shall be run with the old
data, which may not be what you want.
buildpackage
This target runs the targets clean, and binary, and produces the
complete package using dpkg-buildpackage
binary This target produces all four Debian kernel packages by running
the targets binary-indep and binary-arch.
binary-indep
This target produces the arch independent packages by running
the targets kernel_source, kernel_manual and kernel_doc.
binary-arch
This target produces the arch dependent packages by running the
targets kernel_headers and kernel_image.
kernel_source
This target produces a debianised package of the Linux kernel
sources. If the environment variable SOURCE_CLEAN_HOOK points
to an executable, then that executable shall be run from the
temporary (top) directory of the kernel sources just before
packaging it, ./debian/tmp-source/usr/src/kernel-source-X.X.XX,
so people may take any action they see fit (remove arch trees,
prune version control directories, find . -type d -name CVS
-prune -exec rm -rf {} ; etc). This has no effect on anything
other than the kernel sources that are being packaged -- if the
script operates on the current directory and its children, the
original source tree should remain intact. The environment
variables HEADER_CLEAN_HOOK and DOC_CLEAN_HOOK are similar. They
should point to executables, then that executable shall be run
from the temporary (top) directory of the kernel headers and
documentation just before packaging respectively, so people may
take any action they see fit. This also has no effect on
anything other than the sources that are being packaged.
kernel_headers
This target produces a Debian package containing the header
files included in the Linux kernel.
kernel_manual
This target produces a Debian package containing the section 9
manual pages included in the Linux kernel. Please note that this
is not really an independent target; calling this shall also
invoke the kernel_doc target, and creates a kernel-doc package
at the same time.
kernel_doc
This target produces a Debian package containing the
documentation included in the Linux kernel. This can be called
independently of the kernel_manual target, but not the other way
around.
kernel_image
This target produces a Debian package of the Linux kernel source
image, and any modules configured in the kernel configuration
file .config. If there is no .config file in the kernel source
directory, a default configuration is provided similar to the
one used to create the Debian boot-floppies.
If the file ./debian/post-install exists, and is an executable,
it is run just before the kernel image package is created.
Also, please note that if there are any scripts in
./debian/image.d/ directory, run-parts shall be called on that
directory just before the kernel image package is built. The
location of the root of the image package being built shall be
passed in the environment variable IMAGE_TOP, and the kernel
versions is passed in through the environment variable version
for all these scripts.
On initial installation, the image package updates symbolic
links in the symbolic link destination directory (the root
directory by default) to point to the new kernel image in the
image directory, which is nominally /boot. If the symbolic link
already points to the current kernel image, no action is taken.
If a prior symbolic link exists, it is rotated out with a
suffix.old, and a new symbolic link, properly updated is
installed in its place (the variable minimal_swap in
/etc/kernel-img.conf further modifies this behaviour). No action
is taken on upgrades.
Please see the documentation about hooks in kernel-img.conf(5).
These hooks are variables that can be pointed by the local
sysadmin to scripts that add or remove a line from the grub menu
list at kernel image install and remove times. A sample script
to add lines to a grub menu file is included in the directory
/usr/share/doc/kernel-package/.
Apart from hook variables that the local admin may set, there
are a set of directories where packages, or the local admin, may
drop in script files. The directories are
/etc/kernel/preinst.d/, /etc/kernel/postinst.d/,
/etc/kernel/prerm.d/, /etc/kernel/postrm.d/, and
/etc/kernel/preinst.d/<VERSION>/,
/etc/kernel/postinst.d/<VERSION>/,
/etc/kernel/prerm.d/<VERSION>/, /etc/kernel/postrm.d/<VERSION>/.
If they exists, the kernel-image package shall run a run-parts
program over the directory (including the versioned one), giving
the version being installed or removed as an argument, in the
corresponding phase of installation or removal. Before calling
these scripts, the env variable STEM shall be set to the value
of the --stem argument (or the default value, linux). These
scripts shall be called with two arguments, the first being the
version of the kernel image, and the second argument being the
location of the kernel image itself. Since debconf is in use
before the script is called, this script should issue no
diagnostic messgaes to stdout -- while the postinst does call
db_stop , debconf does not restore stdout, so messages to stdout
disappear.
On installation, it also offers to run the Linux loader, LILO
(or alternates like loadlin, SILO, QUIK, VMELILO, ZIPL, yaboot,
PALO or GRUB ), creating a configuration file for supported boot
loaders 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. grub rates a special
mention here, since grub may not need to be rerun after
installing a kernel image, though an automated change to the
menu list would be nice on install and removal of kernel image
packages.
build This target, used by target kernel_image above, compiles the
Linux kernel image.
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
MODULE_LOC/x (MODULE_LOC defaults to /usr/src/modules. ), and
runs the kdist rule in the local debian.rules file. This target
should create the Debian module package(s), and may also produce
a compressed tar file, and a compressed diff file, with md5sums
recorded in a changes file using 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.
modules_config
This target allows you to configure all packages under
MODULE_LOC, which defaults to /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. This should not be called unless you already have a
./debian directory.
modules_image
This target allows you to build all packages under MODULE_LOC,
which defaults to /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. Generally called in
conjunction with kernel_image, especially if also using the
option append_to_version (prevents spurious warnings). This
should not be called unless you already have a ./debian
directory.
modules_clean
This target allows you to clean all packages under MODULE_LOC,
which defaults to /usr/src/modules, and this should be all that
is needed to undo the effect of any of the other modules_
targets. This should not be called unless you already have a
./debian directory.
configure
This target runs configure (actually, config_target, set by
--config which defaults to oldconfig ) early, so you may edit
files generated by make config in the kernel source directory
and not have them stomped by make-kpkg later.
debian This target creates the ./debian directory, and optionally
patches the source. This target is called by the configure
target. You may use this target to have the sources patched, and
then manually run the configuration step to update the
configuration file, with any new configuration options the
patches may have introduced.
libc-kheaders
This is a special target for the libc-dev maintainer, who can
use it to create the headers package that libc needs. Please
note that it is dangerous to create a libc-kheaders package that
is different from the headers libc was compiled with; it is
known to subtly break systems. Please look at
/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.
ENVIRONMENT VARIABLES
KPKG_DEBUG, if set, causes make-kpkg to spit out debugging messages
about some shell functions executed internally. This is probably of not
interest to anyone not debugging make-kpkg. The following variables
(documented above) also affect make-kpkg: DEBIAN_REVISION_MANDATORY
APPEND_TO_VERSION VERSION_H_OK PATCH_THE_KERNEL NO_UNPATCH_BY_DEFAULT
KPKG_ARCH CROSS_COMPILE KPKG_SUBARCH ARCH_IN_NAME INITRD
SOURCE_CLEAN_HOOK MODULE_LOC CONCURRENCY_LEVEL IGNORE_UPPERCASE_VERSION
FILES
Apart from the runtime options, the debian.rules file run by make-kpkg
also looks for a per user configuration file ~/.kernel-pkg.conf.
Failing that, it looks for site-wide defaults in the file
/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
/etc/kernel-pkg.conf (or ~/.kernel-pkg.conf. ) file is actually a
Makefile snippet, and any legal make directives may be included in
there. Note: Caution is urged with this file, since you can totally
change the way that the make is run by suitably editing this file.
Please look at /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
/usr/share/doc/kernel-package/README.gz and it is recommended that one
read that before using this utility.
SEE ALSO
kernel-pkg.conf(5), kernel-img.conf(5), mkinitrd(8),
Getopt::Long(3perl), dpkg-deb(1), dpkg-source(1), make(1),
The Programmers manual, The GNU Make manual, and the extensive
documentation in the directory /usr/share/doc/kernel-package
AUTHOR
This manual page was written by Manoj Srivastava <srivasta@debian.org>,
for the Debian GNU/Linux system.