Provided by: kernel-package_9.001ubuntu15_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).
       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

         % MAKEFLAGS="CC=gcc-2.95" make-kpkg ...

       (please see the top level kernel Makefile for  variables  that  can  be
       set).

OPTIONS

       --help Print out a usage message.

       --revision number
              Changes  the Debian revision number for the packages produced to
              the  argument  number.   This  has  certain   constraints:   the
              --revision  option only has an effect during the configure phase
              (in other words, if a file called stamp-configure  exists,  this
              option  has  no effect -- run make-kpkg clean or manually remove
              stamp-configure and stamp-debian for it to have an effect  --  I
              strongly  suggest  you  run make-kpkg clean unless you know what
              you  are  doing).    Additionally,   official   source   package
              maintainers  provide  their own version numbers and data for the
              official uploads, and hence a number of  things,  including  the
              Debian revision, is not modified by make-kpkg.  If you happen to
              have  an  official  source,  (that  would  mean  that  the  file
              debian/official  exists, and is not empty), and want to use your
              own revision number, make sure you remove debian/official before
              running  make-kpkg clean for this option to have an effect.  So,
              if you want  to  re-run  make-kpkg  with  a  different  revision
              number,  you  have  to  make  sure you start with a clean slate.
              Secondly, the version may contain  only  alphanumerics  and  the
              characters  +  .  (full stop and plus) and must contain a digit.
              (Look at the Policy manual for details).  Actually,  that  is  a
              lie:  official  kernel  and  modules  maintainers  have  special
              dispensation to use hyphens, but it is strongly  deprecated  for
              most  people,  since  no  sanitization  of the version number is
              done, and dpkg and friends may choke on it at  the  end  of  the
              compile unless one knows what one is doing.  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.

       --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 - + . (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  Please   note   that you must run a make-kpkg
              clean after configuring the kernel using  make  (x|menu)?config,
              since  that creates the file include/linux/version.h without the
              append_to_version data (foo). This file won’t be updated by  the
              make-kpkg  run (make-kpkg creates version.h if it doesn’t exist,
              but doesn’t touch if exists), so the  final  kernel  will  _not_
              have  the  append_to_version data in its version number it shall
              look for the modules and symbols in all the  wrong  places.  The
              simplest  solution  is  either to remove include/linux/version.h
              after configuring and before  compiling,  or  running  make-kpkg
              clean  after configuring, before compiling.  Note also that once
              you use --append_to_version foo for configuring, or building the
              kernel-image,  you need to also use the same option in any later
              invocation of make-kpkg (say, for building stand alone  modules,
              or  something).  make-kpkg does not remember the argument foo in
              between invocations (this is  different  from  the  behavior  of
              --revision, which we do remember in between invocations). If you
              are annoyed by make-kpkg whining about using --append_to_version
              and  there  already  being  a  file from before, you can set the
              environment variable  VERSION_H_OK  which  shall  shut  off  the
              warning.

       --flavour foo
              This  option  is now deprecated in favor of --append_to_version.
              Sets the kernel flavour to the argument foo. The flavour is also
              appended  to  the  package  name. You need a patched Makefile to
              make          this          work          properly          (see
              /usr/share/doc/kernel-package/Flavours.gz).  It may contain only
              lowercase alphanumerics and the characters -  +  .  (full  stop,
              hyphen,  and plus). Uppercase letter are not permitted under the
              Policy for a new package. NOTE: Hyphens are discouraged.   (Look
              at  Chapters  4  of  the Policy manual for details). Please note
              that you shall need to make-kpkg clean  FIRST  if  you  wish  to
              recompile the kernel-image using a flavour.

       --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.

       --added-patches foo

       --added_patches foo
              The argument should be a  comma  separated  list  of  additional
              patches  to  the  kernel  sources.  This  automatically sets the
              patch_the_kernel configuration option to YES.

              Unlike the treatment of the modules, you may only give the patch
              file  basename  (not the full path name of the patch file).  For
              each file <patch_name> in the list,  the  following  process  is
              followed:   If   the  file  can  be  found  in  the  directories
              ALL_PATCH_DIR/{apply,unpatch}/,       then       the        file
              ALL_PATCH_DIR/apply/<patch_name>   shall  be  executed  in  turn
              during the configure phase  (and  presumably  this  applies  the
              patch).            Correspondingly,           the           file
              ALL_PATCH_DIR/unpatch/<patch_name>  shall  be  executed  in  the
              clean  phase.   The  default  is that all patches are applied by
              running all the  executable  files  in  ALL_PATCH_DIR/apply/  if
              requested   (Either   by   setting   the   configuration  option
              patch_the_kernel or the environment variable PATCH_THE_KERNEL to
              YES).   Please  note  that the patches are UN-installed from the
              source when you run the  clean  target.   This  cleanup  can  be
              prevented     by     setting     the     environment    variable
              NO_UNPATCH_BY_DEFAULT

              In the  above,  ALL_PATCH_DIR  defaults  to  a  subdirectory  of
              /usr/src/kernel-patches/.

              Some  times  it  would be convenient to have the patches applied
              when one asks for specific patches using  this  option,  without
              also  having  to  explicitly set the environment variable. Since
              setting the environment variable PATCH_THE_KERNEL to  YES  could
              be  dangerous,  (for  in  that case all patches may be installed
              when you want  none,  and  did  not  specify  the  added_patches
              option), You may also set the variable PATCH_THE_KERNEL to AUTO,
              in which case PATCH_THE_KERNEL shall be set to YES for you  when
              you invoke --added-patches foo, but not otherwise.  Also, please
              note that if any patch installs a  script  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.  This is a
              way for the patch to insert any additional files into the image,
              for example.

              Some   of  the  patch  packages  also  pay  attention  to  other
              environment  variables,  and  these  are   documented   in   the
              appropriate  doc  directory  (for  example,  you  should look at
              /usr/share/doc/kernel-patch-foo/README-kernelpatch.Debian    for
              patch foo for additional information).

       --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

       --cross-compile foo

       --cross_compile foo
              This is useful for setting the target string when you are  cross
              compiling.  The  same  effect  can  be  achieved  by setting the
              environment variable 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; old, menu, g, or x.  This option is particularly useful
              when  using  PATCH_THE_KERNEL if some of the patches change what
              configuration  options  are  available.    Note   however   that
              make-kpkg  scans  the  config  file at startup 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, created  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.

       --initrd
              If make-kpkg is generating a kernel-image package,  perform  any
              actions  necessary  for  a kernel loaded using initrd.  NOTE: in
              older kernels, this required a non-standard cramfs initrd  patch
              to  the  kernel  sources, (unless the mkinitrd configuration was
              modified not to use  cramfs)  or  may  result  in  a  unbootable
              kernel.  The  patch  was  usually  present in the kernel sources
              shipped by Debian.  Some architectures still need patches to fix
              cramfs problems. This option may include extra dependencies, and
              modifications to maintainer scripts.   It  has  no  effect  when
              make-kpkg  is not making a kernel-image package. The same effect
              can be achieved by setting the environment  variable  INITRD  to
              any non empty value.

       --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.

       --mkimage
              This should be a command that produces an initrd image  given  a
              directory. It is passed to the mkinitrd program’s -m option. For
              example, it can be
                "genromfs -d %s -f %s" or
                "mkcramfs %s %s"

       --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.

       --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"

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.

       binary-indep
              This target produces the arch independent  packages  by  running
              the targets kernel_source and kernel_doc.

       binary-arch
              This  target produces the arch dependent packages by running the
              targets kernel_headers and 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 similiar. The
              should point tp executables, then that executable shall  be  run
              from  the  temporary  (top)  directory of the kernel headers and
              coumentation 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_headers
              This target produces a  Debian  package  containing  the  header
              files included in the Linux kernel.

       kernel_doc
              This   target   produces   a   Debian   package  containing  the
              documentation included in the Linux kernel.

       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.

              On initial installation,  the  image  package  updates  symbolic
              links  in  the  symbolic  link  destination  directory (the root
              directory by default) to point to the new kernel  image  in  the
              image directory, which is nominally /boot.  If the symbolic link
              already points to the current kernel image, no action is  taken.
              If  a  prior  symbolic  link  exists,  it  is rotated out with a
              suffix.old,  and  a  new  symbolic  link,  properly  updated  is
              installed   in   its   place   (the   variable  minimal_swap  in
              /etc/kernel-img.conf further modifies this behaviour). No action
              is taken on upgrades.

              Please  see the documentation about hooks in kernel-img.conf(5).
              These hooks are variables that  can  be  pointed  by  hte  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.

              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.

       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).

       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.

       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 is called by the configure target.  You
              may  use  this  target  to  have  the  sources patched, and then
              manually run the configuration step.

       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

       The  following   variables   (documented   above)   affect   make-kpkg:
       DEBIAN_REVISION_MANDATORY         APPEND_TO_VERSION        VERSION_H_OK
       PATCH_THE_KERNEL    NO_UNPATCH_BY_DEFAULT    KPKG_ARCH    CROSS_COMPILE
       KPKG_SUBARCH    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),           mkinitrd(8),
       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.