summaryrefslogtreecommitdiffstats
path: root/debian/README.source
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--debian/README.source297
1 files changed, 297 insertions, 0 deletions
diff --git a/debian/README.source b/debian/README.source
new file mode 100644
index 000000000..2248ac9ae
--- /dev/null
+++ b/debian/README.source
@@ -0,0 +1,297 @@
+Checklist for uploaders
+=======================
+
+There is a checklist in the kernel-team.git repository; see
+<https://salsa.debian.org/kernel-team/kernel-team/-/blob/master/docs/kernel-upload-checklist.md>.
+
+Updating the upstream source
+============================
+
+In addition to the build-dependencies, you will need the rsync package
+installed.
+
+1) Run: ./debian/bin/genorig.py <repository>
+
+ where <repository> is a local or remote git repository with the
+ upstream release tag in it.
+
+ If you do not have a local repository, use the appropriate 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
+
+ This will produce ../orig/linux_<version>.orig.tar.xz
+ (e.g. linux_3.5~rc1.orig.tar.xz).
+
+ It involves deleting files for DFSG compliance, as listed in the
+ Files-Excluded field in debian/copyright.
+
+2) Run: make -f debian/rules orig
+
+ This will apply the main quilt series to the upstream source, which
+ will usually fail due to conflicts with upstream changes. You need
+ to resolve those by dropping or refreshing patches.
+
+Recording updates in the changelog
+----------------------------------
+
+Upstream commits that we already cherry-picked and included in a
+previous package upload should not be mentioned, since they don't make
+any difference to the package. Any other commits that fix a Debian
+bug report and/or a security issue with a CVE ID should always be
+listed, along with the (Closes: #nnnnnn) and/or (CVE-yyyy-nnnn)
+reference.
+
+Aside from those general rules:
+
+* For an upstream release candidate, don't attempt to list the changes
+
+* For a stable release by Linus, refer to the summary at
+ kernelnewbies.org, e.g. https://kernelnewbies.org/Linux_4.5
+
+* For a stable update, refer to the changelog on kernel.org, e.g.
+ https://www.kernel.org/pub/linux/kernel/v4.x/ChangeLog-4.5.1, and
+ list all changes that are relevant to our package and that fix bugs
+ that we would consider 'important' or higher severity
+
+ - The script debian/bin/stable-update updates the changelog
+ version and inserts the list of changes. It doesn't attempt to
+ filter out irrelevant or unimportant changes.
+
+ - If you have time, please delete irrelevant changes such as:
+ + Fixes for architectures not supported by the package
+ + Fixes for drivers that aren't enabled in any of our configurations
+ + Build fixes for configurations that we don't use
+ + Fixes for lockdep false positives
+
+If you have time, please add bracketted prefixes to the upstream
+change list as described below under "Changelog conventions".
+
+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.
+
+For each optional featureset there is an additional patch directory
+debian/patches-<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.
+
+Changelog conventions
+=====================
+
+If a change only affects some architectures, flavours or featuresets,
+this should be noted with a bracketted prefix on the changelog line:
+
+* [<fset>] Change to featureset <fset>
+* [<arch>] Change that affects Debian architecture <arch>
+* [<arch1>,<arch2>...] Change that affects Debian architectures
+ <arch1>, <arch2>, ...
+* [<arch>/<flavour>] Change that affects kernel flavour <flavour>
+ on Debian architecture <arch>
+* [<arch>/{<flavour1>,<flavour2>...}] Change that affects kernel
+ flavours <flavour1>, <flavour2>, ... on Debian architecture <arch>
+
+You can use wildcards to cover multiple values, e.g. 'arm*' for armel,
+armhf and arm64 architectures. Also 'x86' is used to cover the Debian
+architectures amd64, i386 and x32.
+
+Kernel config files
+===================
+
+Each kernel configuration file is constructed dynamically from a
+number of files under debian/config and (if it exists)
+debian/config.local. They are read in the following order, such that
+files later on the list can override settings from earlier files.
+Files in debian/config.local can also override settings from the
+corresponding file in debian/config. Most of the files are optional
+and the filenames can generally be overridden by explicit lists
+(possibly empty) specified in the 'defines' files.
+
+1. Common:
+ - Default filename: config
+ - Filename list: [image]configs in defines
+2. Per kernel architecture:
+ - Filename: kernelarch-<karch>/config (optional)
+3. Per architecture:
+ - Default filename: <arch>/config
+ - Filename list: [image]configs in <arch>/defines
+4. Per architecture and flavour:
+ - Default filename: <arch>/config.<flavour> (optional)
+ - Filename list: [<flavour>_image]configs in <arch>/defines
+5. Per featureset:
+ - Default filename: featureset-<fset>/config (optional)
+ - Filename list: [image]configs in featureset-<fset>/defines
+6. Per architecture and featureset:
+ - Default filename: <arch>/<fset>/config (optional)
+ - Filename list: [image]configs in <arch>/<fset>/defines
+7. Per architecture, featureset, and flavour:
+ - Default filename: <arch>/<fset>/config.<flavour> (optional)
+ - Filename list: [<flavour>_image]configs in <arch>/<fset>/defines
+
+You can check the final list of configuration files by reading
+debian/rules.gen. Each binary-arch_<arch>_<fset>_<flavour>_real
+rule passes the list to debian/rules.real as the KCONFIG variable.
+
+These files should be kept in order using the kconfigeditor2
+utility from <https://salsa.debian.org/kernel-team/kernel-team>.
+With this source package as your working directory, run:
+
+ debian/rules source
+ .../kernel-team/utils/kconfigeditor2/process.py .
+
+This will also warn about any symbols that no longer exist, or
+cannot be explicitly configured.
+
+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.
+
+Build-dependencies that relate to specific binary packages can be
+specified in a Build-Depends field in the template for that binary
+package. gencontrol.py will append the value to the source package's
+Build-Depends-Arch or Build-Depends-Indep field, as appropriate. It
+will also use the binary package's Architecture and Build-Profile as
+the architecture-qualification and/or restriction for each build-
+dependency that doesn't already have them.
+
+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
+
+Build profiles
+==============
+
+Several build profiles are understood and supported:
+
+- stage1: Needed when bootstrapping an architecture. A stage1 build
+ produces only the linux-libc-dev package and has no host
+ build-dependencies.
+- nodoc: Exclude most documentation
+- noudeb: Exclude installer udeb packages
+- pkg.linux.notools: Exclude userland tool packages (linux-kbuild-<version>,
+ linux-perf, etc.)
+- pkg.linux.mintools: Build minimal set of userland tool packages
+ (linux-kbuild-<version>, linux-bootwrapper-<abiname> on powerpc/ppc64)
+- pkg.linux.nokernel: Exclude kernel image and header packages
+- pkg.linux.nokerneldbg: Exclude kernel debug packages
+- pkg.linux.nokerneldbginfo: Build kernel without debug symbols (also disables
+ BTF)
+- pkg.linux.nosource: Exclude source binary package (linux-source-<version>)
+- cross: Needed when cross-building.
+- nopython: Disable Python bindings. This currently disables building the
+ linux-perf-<version> package, as the perf program embeds Python.
+- pkg.linux.nometa: Exclude most meta-packages. The linux-compiler-* and
+ linux-headers-*-all* packages can still be built.
+- pkg.linux.quick: Perform a limited build that should provide good
+ coverage yet be quick enough for use in CI.
+
+Build rules
+===========
+
+The Debian build rules are split across multiple makefiles:
+
+- debian/rules: Standard top-level makefile for Debian package build.
+- debian/rules.gen: Intermediate makefile between debian/rules and
+ debian/rules.real. This is generated by gencontrol.py based on
+ the configuration under debian/config.
+- debian/rules.real: Makefile for building a single kernel flavour
+ or other group of binary packages.
+- debian/rules.d: Makefiles for building userland code from specific
+ source directories. The directory structure mirrors the kernel
+ source directories. debian/rules.real uses the "make-tools" to
+ invoke these makefiles.
+
+All builds *must* be done out-of-tree in a subdirectory of
+debian/build, so that the output files do not end up in the
+linux-source-<version> binary package. Currently kernel builds use
+debian/build/build_<arch>_<featureset>_<flavour>, userland code uses
+debian/build/build-tools/<source-dir> and documentation uses
+debian/build/build-doc.
+
+Code signing
+============
+
+The kernel image and modules may be signed after building, to support
+a Secure Boot or Trusted Boot policy. In Debian, this is performed by
+a "code signing service" that is separate from the normal package
+build process.
+
+The initial package build generates binary packages named
+linux-image-<arch>-signed-template, that contain a source package
+template and metadata about the files to be signed. The code signing
+service will download this and the linux-image packages to be signed.
+It will add detached signatures to the source package, then upload it
+(without ever running debian/rules).
+
+The source package template is generated by
+debian/bin/gencontrol_signed.py and debian/rules.real with files from
+debian/signing_templates and debian/templates. To test changes to
+these:
+
+1. Build the linux source package.
+2. Generate the signed source package by running the script
+ "debian-test-sign" from the kernel-team.git repository. It is
+ also possible to set up a development configuration of the
+ official code signing service, but this is more complicated.
+3. Build the signed source package.