MAKE-KPKG
Section: Debian GNU/Linux manual (1)
Updated: Nov 14 2002
Index
Return to Main Contents
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 setting the environment variable
MAKEFLAGS.
To observe, try:
% KBUILD_VERBOSE=1 MAKEFLAGS="CC=gcc-4.4" 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 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 over rides 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 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.
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).
- --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.
- --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.
- --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 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. 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.
- 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_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_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.
- 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.
-
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), 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
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),
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.
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- OPTIONS
-
- TARGETS
-
- ENVIRONMENT VARIABLES
-
- FILES
-
- SEE ALSO
-
- AUTHOR
-
This document was created by
man2html,
using the manual pages.
Time: 19:49:12 GMT, April 27, 2011