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 pre-
viously configured (unless you are using the configure target). Nor-
mally, if kernel-package does not find a .config file in the current
directory, it tries very hard to get an appropriate one (usually a con-
fig 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 ker-
nel 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.
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.Cus-
tom 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
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 ver-
sion numbers set in the Makefile or in the localversion file.
This option over rides the environment variable APPEND_TO_VER-
SION
--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 MOD-
ULE_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_COM-
PILE
--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
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 main-
tainer 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).
--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 environ-
ment 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/ker-
nel-package/changelog files as templates.
--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-buildpack-
age's -r option. This option does not work for three of the tar-
gets, 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 distribu-
tion. 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.
TARGETS
clean Cleans the kernel source directory of all files created by tar-
get 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 pre-
served. 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.
the targets kernel_source, kernel_manual and kernel_doc. How-
ever, this also requires make-kpkg to be run as root (or fake-
root), 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 vari-
ables 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 any-
thing 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/mod-
ules/<kver> under control, since this could be on a root parti-
tion 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 documenta-
tion included in the Linux kernel. This can be called indepen-
dently of the kernel_manual target, but not the other way
around.
kernel_image
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/pre-
inst.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/<VER-
SION>/, /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 KER-
NEL_PACKAGE_VERSION shall be set to the version of the ker-
nel-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 dele-
tion, the package checks the version of the kernel running, and
refuses to delete a running kernel. grub rates a special men-
tion 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 MOD-
ULE_LOC/x (MODULE_LOC defaults to /usr/src/modules. ), and runs
or if you want to manually compile the add on modules. This
should not be called unless you already have a ./debian direc-
tory.
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 instal-
lation 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_ tar-
gets. 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 tar-
get. You may use this target to have the sources patched, and
then manually run the configuration step to update the configu-
ration 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/ker-
nel-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 CON-
CURRENCY_LEVEL IGNORE_UPPERCASE_VERSION
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.
|
