linux/debian/README.source

Updating the upstream source
============================

In addition to the build-dependencies, you will need the rsync and
unifdef packages installed.

1) It is recommended to fetch the release tag from the relevant upstream git
   repository, one of:

   * https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
   * https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git
   * git://kernel.ubuntu.com/ubuntu/linux.git

   However, it is also possible to use upstream tarball and patch releases.
   Both tags and files should be signed by the relevant maintainer, which
   you *must* verify using commands such as:

   $ git tag -v v4.5
   $ xzcat linux-4.5.tar.xz | gpg --verify linux-4.5.tar.sign -
   $ xzcat patch-4.5.1.xz | gpg --verify patch-4.5.1.sign -

   The upstream maintainers' key fingerprints are:

   pub   2048R/00411886 2011-09-20
         Key fingerprint = ABAF 11C6 5A29 70B1 30AB  E3C4 79BE 3E43 0041 1886
   uid                  Linus Torvalds <torvalds@linux-foundation.org>
   sub   2048R/012F54CA 2011-09-20

   pub   4096R/6092693E 2011-09-23
         Key fingerprint = 647F 2865 4894 E3BD 4571  99BE 38DB BDC8 6092 693E
   uid                  Greg Kroah-Hartman (Linux kernel stable release signing key) <greg@kroah.com>
   sub   4096R/76D54749 2011-09-23

   pub   4096R/FDCE24FC 2011-12-10
         Key fingerprint = D4E1 E317 4470 9144 B0F8  101A DB74 AEB8 FDCE 24FC
   uid                  Luis Henriques <luis.henriques@canonical.com>
   uid                  Luis Henriques <henrix@camandro.org>
   sub   4096R/EFBC394A 2011-12-10

2) Run: ./debian/bin/genorig.py <repository>
   or:  ./debian/bin/genorig.py <tarball> [patch]

   This will produce ../orig/linux_<version>.orig.tar.xz
   (e.g. linux_3.5~rc1.orig.tar.xz).

3) Run: make -f debian/rules orig

Applying patches to the Debian kernel tree
==========================================

The Debian kernel packaging uses the quilt patch system, but with
multiple series to allow for featuresets.

Patches are stored below debian/patches, loosely sorted in bugfix/,
features/ and debian/. Patches are in the standard kernel patch
format (unified diff to be applied with patch -p1) and generally have
DEP-3 headers.

The series file 'series' is used for all configurations and a series
file 'series-<featureset>' is used for each optional featureset.

If you want to generate a source tree with all patches applied, run
make -f debian/rules source

The resulting source can be found below debian/build.

Kernel config files
===================
Configuration files are constructed dynamically from a number of config
files, as listed in debian/config/<arch>/defines.

Control file
============
The master control file debian/control must be generated before
the package is uploaded. debian/rules contains the debian/control 
target, which generates the control file by invoking the 
debian/bin/gencontrol.py script, which combines the templates from
the templates directory and architecture-specific defines file to
produce the debian/control file. Note that this target is intentionally
made to fail with a non-zero exit code to make sure that it is never
run during an automatic build. The following variables are substituted
into the templates:

@version@      Upstream kernel version, for example 2.6.11.
@arch@         The Debian arch name, such as powerpc or i386.
@flavour@      The build flavour, such as 686 or k7-smp.
@class@        The CPU/architecture class; displayed in synopsis.  It should
               be fairly short, as the synopsis is supposed to be <80 chars.
               It should be in the form "foo class", and will show up in the
	       description as "foo class machines".
@longclass@    The CPU/architecture class; displayed in the extended
               description.  The same rules apply as in @class@.  If
	       this is unset, it will default to @class@.
@desc@         (Potentially) multi-line verbiage that's appended to
               -image descriptions.
@abiname@      Current abiname, a single digit.

Normally, the arch-specific contents should be controlled by
adjusting the corresponding defines file.

TODO:
- Patches applied to the upstream source
- How to define a flavour
- More detail on generation of debian/control and configs

Running tests
=============

linux supports autopkgtest and should be able to run most of the
kernel's self-tests on any architecture where kexec is supported,
but it has higher resource requirements than most packages:

- A VM with plenty of disk space (10GB is enough), RAM (1GB is
  probably enough) and at least 2 CPUs
- The temporary directory for adt-virt-qemu (-o option) will need
  several GB of space, so a tmpfs may not be suitable

Note that if you tell adt-run to use an 'unbuilt tree' (i.e. an
unpacked source package) it does not exclude VCS directories such as
.git.  Either use a packed source package or copy the working tree
elsewhere excluding .git.

Example invocation:

    adt-run -B ../linux-image-4.2.0-rc6-amd64_4.2~rc6-1~exp2_amd64.deb \
        ../linux_4.2~rc6-1~exp2.dsc \
	--timeout-test=1200 \
        --- adt-virt-qemu /var/cache/autopkgtest/adt-sid.img -o /var/tmp -c 2