Provided by: kernel-package_13.018+nmu1_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. However, this might still result in an inappropriate
configuration, you are encouraged to configure the kernel by the usual means before invoking make-kpkg.
Typically, make-kpkg should be run under fakeroot,
make-kpkg --rootcmd fakeroot kernel_image
but instead you run this command as root (this is not recommended), or under fakeroot, or tell make-kpkg
how to become root (not recommended either, fakeroot is perhaps the safest option), like so:
make-kpkg --rootcmd sudo 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 source. 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 setting the environment variable MAKEFLAGS. To
observe, try:
% KBUILD_VERBOSE=1 MAKEFLAGS="CC=gcc-4.4" make-kpkg configure
Please note that the kernel Makefile might pay attention to other variables (for instance KCFLAGS ). This
can be addressed like so:
% KBUILD_VERBOSE=1 MAKEFLAGS='CC=gcc-4.4 KCFLAGS="-march=athlon64"' make-kpkg configure
The KBUILD_VERBOSE shows the details of the commands being run. (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. There is also a -j flag that can be used.
OPTIONS
--help Print out a usage message.
--revision number
Changes the version number for the packages produced to the argument number. This has certain
constraints: the version must start with a digit. 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). 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. Hint: You may set it to $(version)-<foo> in the configuration file to get the
upstream version number prepended to your custom string <foo>.
--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 overrides the environment variable
APPEND_TO_VERSION.
--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.
--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 another 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, nconfig, xconfig, randconfig, defconfig, allmodconfig, allyesconfig,
allnoconfig, old, menu, g, or x.
Note however that make-kpkg scans the config file at start up 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, arrange to convey to the hook scripts run from
the post installation maintainer scripts that this image requires an initrd, and that the initrd
generation hook scripts should not short circuit early. Without this option, the example initramfs
hook scripts bundled in with kernel-package will take no action on installation. The same effect
can be achieved by setting the environment variable INITRD to any non empty value. Please note
that unless there are hook scripts in /etc/kernel or added into the hook script parameter of
/etc/kernel-img.conf, no initrd will be created (the bundled in example scripts are just examples
-- user action is required before anything happens). On most systems, however initramfs-tools
installs scripts (since version 0.94 (and they have respected the INITRD variable since 0.98)).
dracut also does this.
--jobs number
-j number
Set the environment variable CONCURRENCY_LEVEL to number.
--overlay-dir /path/to/directory
The specified directory should contain files that will be placed in the ./debian directory of the
kernel sources, in preparation to building the debian packages. The files will replace anything in
/usr/share/kernel-package that would normally be placed there, and it is up to the user to make
sure that the files in the overlay directory are compatible with make-kpkg. If you break make-
kpkg with an overlay file, you get to keep the pieces. The same effect can be achieved by setting
the environment variable KPKG_OVERLAY_DIR.
Please note that overlay-dir/Control and overlay-dir/changelog are special, and variable
substitution is performed on these files. Use /usr/share/kernel-package/Control and
/usr/share/kernel-package/changelog files as templates.
If a overlay-dir/post-install executable (or executable script) exists, it shall be run
immediately after ./debian is populated. The script shall be executed in the ./debian directory.
This can be used, for instance, to delete files the user does not want, or to take actions other
than simple replacement.
--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. This option does not work for three of the targets,
namely, binary, binary-indep, and binary-arch. For those targets the entire make-kpkg command
must be run as (fake)root.
--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. The stem, since it is the initial part of a package name must consist only
of lower case letters (`a-z'), digits (`0-9'), plus (`+') and minus (`-') signs, and periods
(`.'). It must be at least two characters long and must start with an alphanumeric character.
--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 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. It is
possible to set -j as a make-kpkg argument.
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. Please note that by default the clean
target is not run as root, whic works fine of the command fakeroot was used. However, if
previously the build was done using sudo, you need to run make-kpkgclean also under sudo.
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. However, this requires make-kpkg to be run as root (or fakeroot), since --rootcmd
will not work.
binary-indep
This target produces the arch independent packages by running the targets kernel_source,
kernel_manual and kernel_doc. However, this also requires make-kpkg to be run as root (or
fakeroot), since --rootcmd will not work.
binary-arch
This target produces the arch dependent packages by running the targets kernel_headers and
kernel_image. However, this also requires make-kpkg to be run as root (or fakeroot), since
--rootcmd will not work.
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_debug
This target produces a Debian package containing the debugging symbols for the modules contained
in the corresponding image package. The basic idea here is to keep the space in
/lib/modules/<kver> under control, since this could be on a root partition with space
restrictions. Please note that if module signatures are enable in the kernel configuration the
corresponding image package will not have modules with the debugging link pointing to these
debugging symbol files. In order to turn on debugging links for modules in the image package you
need to turn off module signatures.
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 kernel configuration file has enabled support for modules, modules will be
created and installed. If module signatures are not enabled, the resulting modules will have a
link to the location of the debugging symbols file for the module, usually installed by the debug
package.
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 version is passed in through the environment
variable version for all these scripts.
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/,
/etc/kernel/preinst.d/<VERSION>/, /etc/kernel/postinst.d/<VERSION>/,
/etc/kernel/prerm.d/<VERSION>/, and /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), and the variable
KERNEL_PACKAGE_VERSION shall be set to the version of the kernel-package that created the package.
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 messages 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,
KPKG_ARCH, CROSS_COMPILE, KPKG_SUBARCH, KPKG_OVERLAY_DIR, ARCH_IN_NAME, INITRD, SOURCE_CLEAN_HOOK,
MODULE_LOC, CONCURRENCY_LEVEL and 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
dpkg-deb(1), dpkg-source(1), make(1), Getopt::Long(3perl), kernel-img.conf(5), kernel-pkg.conf(5), The Programmers manual, The GNU Make manual, and the extensive documentation in the /usr/share/doc/kernel-package directory
AUTHOR
This manual page was written by Manoj Srivastava <srivasta@debian.org>, for the Debian GNU/Linux system.