--- name: "make-kpkg" section: "1" platform: "linux" package: "kernel-package" version: "13.014+nmu1" release: "Debian 8 (Jessie)" platforms: ["linux"] url: "https://new.carta.tech/make-kpkg" --- # make-kpkg(1) build Debian kernel packages from Linux kernel sources ## 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 confugre 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 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)-\ in the configuration file to get the upstream version number prepended to your custom string \. - **--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). - **--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)](/Getopt::Long/3perl.md). - **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\_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/\* 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 mdoule, 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)](/kernel-img.conf/5.md). 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/\/*, */etc/kernel/postinst.d/\/*, */etc/kernel/prerm.d/\/*, and */etc/kernel/postrm.d/\/*. 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-deb/1.md), [**dpkg-source**(1)](/dpkg-source/1.md), [**make**(1)](/make/1.md), [**Getopt::Long**(3perl)](/Getopt::Long/3perl.md), [**kernel-img.conf**(5)](/kernel-img.conf/5.md), [**kernel-pkg.conf**(5)](/kernel-pkg.conf/5.md), **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 \, for the Debian GNU/Linux system.