Provided by: kernel-package_12.036+nmu2_all bug

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.