|
| 1 | +Updating the upstream source |
| 2 | +============================ |
| 3 | + |
| 4 | +In addition to the build-dependencies, you will need the rsync and |
| 5 | +unifdef packages installed. |
| 6 | + |
| 7 | +1) It is recommended to fetch the release tag from the relevant upstream git |
| 8 | + repository, one of: |
| 9 | + |
| 10 | + * https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git |
| 11 | + * https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git |
| 12 | + * git://kernel.ubuntu.com/ubuntu/linux.git |
| 13 | + |
| 14 | + However, it is also possible to use upstream tarball and patch releases. |
| 15 | + Both tags and files should be signed by the relevant maintainer, which |
| 16 | + you *must* verify using commands such as: |
| 17 | + |
| 18 | + $ git tag -v v4.5 |
| 19 | + $ xzcat linux-4.5.tar.xz | gpg --verify linux-4.5.tar.sign - |
| 20 | + $ xzcat patch-4.5.1.xz | gpg --verify patch-4.5.1.sign - |
| 21 | + |
| 22 | + The upstream maintainers' key fingerprints are: |
| 23 | + |
| 24 | + pub 2048R/00411886 2011-09-20 |
| 25 | + Key fingerprint = ABAF 11C6 5A29 70B1 30AB E3C4 79BE 3E43 0041 1886 |
| 26 | + uid Linus Torvalds < [email protected]> |
| 27 | + sub 2048R/012F54CA 2011-09-20 |
| 28 | + |
| 29 | + pub 4096R/6092693E 2011-09-23 |
| 30 | + Key fingerprint = 647F 2865 4894 E3BD 4571 99BE 38DB BDC8 6092 693E |
| 31 | + uid Greg Kroah-Hartman (Linux kernel stable release signing key) < [email protected]> |
| 32 | + sub 4096R/76D54749 2011-09-23 |
| 33 | + |
| 34 | + pub 4096R/FDCE24FC 2011-12-10 |
| 35 | + Key fingerprint = D4E1 E317 4470 9144 B0F8 101A DB74 AEB8 FDCE 24FC |
| 36 | + uid Luis Henriques < [email protected]> |
| 37 | + uid Luis Henriques < [email protected]> |
| 38 | + sub 4096R/EFBC394A 2011-12-10 |
| 39 | + |
| 40 | +2) Run: ./debian/bin/genorig.py <repository> |
| 41 | + or: ./debian/bin/genorig.py <tarball> [patch] |
| 42 | + |
| 43 | + This will produce ../orig/linux_<version>.orig.tar.xz |
| 44 | + (e.g. linux_3.5~rc1.orig.tar.xz). |
| 45 | + |
| 46 | + It involves applying several patches and file deletions for DFSG |
| 47 | + compliance, as listed in debian/patches/series-orig. Occasionally |
| 48 | + you will need to refresh these. |
| 49 | + |
| 50 | +3) Run: make -f debian/rules orig |
| 51 | + |
| 52 | + This will apply the main quilt series to the upstream source, which |
| 53 | + will usually fail due to conflicts with upstream changes. You need |
| 54 | + to resolve those by dropping or refreshing patches. |
| 55 | + |
| 56 | +Recording updates in the changelog |
| 57 | +---------------------------------- |
| 58 | + |
| 59 | +Upstream commits that we already cherry-picked and included in a |
| 60 | +previous package upload should not be mentioned, since they don't make |
| 61 | +any difference to the package. Any other commits that fix a Debian |
| 62 | +bug report and/or a security issue with a CVE ID should always be |
| 63 | +listed, along with the (Closes: #nnnnnn) and/or (CVE-yyyy-nnnn) |
| 64 | +reference. |
| 65 | + |
| 66 | +Aside from those general rules: |
| 67 | + |
| 68 | +* For an upstream release candidate, don't attempt to list the changes |
| 69 | + |
| 70 | +* For a stable release by Linus, refer to the summary at |
| 71 | + kernelnewbies.org, e.g. https://kernelnewbies.org/Linux_4.5 |
| 72 | + |
| 73 | +* For a stable update, refer to the changelog on kernel.org, e.g. |
| 74 | + https://www.kernel.org/pub/linux/kernel/v4.x/ChangeLog-4.5.1, and |
| 75 | + list all changes that are relevant to our package and that fix bugs |
| 76 | + that we would consider 'important' or higher severity |
| 77 | + |
| 78 | + - The script debian/bin/stable-update updates the changelog |
| 79 | + version and inserts the list of changes. It doesn't attempt to |
| 80 | + filter out irrelevant or unimportant changes. |
| 81 | + |
| 82 | + - The script debian/bin/ckt-stable-update.sh does the same for |
| 83 | + stable updates by the Canonical Kernel Team. |
| 84 | + |
| 85 | + - If you have time, please delete irrelevant changes such as: |
| 86 | + + Fixes for architectures not supported by the package |
| 87 | + + Fixes for drivers that aren't enabled in any of our configurations |
| 88 | + + Build fixes for configurations that we don't use |
| 89 | + + Fixes for lockdep false positives |
| 90 | + |
| 91 | +If you have time, please add bracketted prefixes to the upstream |
| 92 | +change list as described below under "Changelog conventions". |
| 93 | + |
| 94 | +Applying patches to the Debian kernel tree |
| 95 | +========================================== |
| 96 | + |
| 97 | +The Debian kernel packaging uses the quilt patch system, but with |
| 98 | +multiple series to allow for featuresets. |
| 99 | + |
| 100 | +Patches are stored below debian/patches, loosely sorted in bugfix/, |
| 101 | +features/ and debian/. Patches are in the standard kernel patch |
| 102 | +format (unified diff to be applied with patch -p1) and generally have |
| 103 | +DEP-3 headers. |
| 104 | + |
| 105 | +The series file 'series' is used for all configurations and a series |
| 106 | +file 'series-<featureset>' is used for each optional featureset. |
| 107 | + |
| 108 | +If you want to generate a source tree with all patches applied, run |
| 109 | +make -f debian/rules source |
| 110 | + |
| 111 | +The resulting source can be found below debian/build. |
| 112 | + |
| 113 | +Changelog conventions |
| 114 | +===================== |
| 115 | + |
| 116 | +If a change only affects some architectures, flavours or featuresets, |
| 117 | +this should be noted with a bracketted prefix on the changelog line: |
| 118 | + |
| 119 | +* [<fset>] Change to featureset <fset> |
| 120 | +* [<arch>] Change that affects Debian architecture <arch> |
| 121 | +* [<arch1>,<arch2>...] Change that affects Debian architectures |
| 122 | + <arch1>, <arch2>, ... |
| 123 | +* [<arch>/<flavour>] Change that affects kernel flavour <flavour> |
| 124 | + on Debian architecture <arch> |
| 125 | +* [<arch>/{<flavour1>,<flavour2>...}] Change that affects kernel |
| 126 | + flavours <flavour1>, <flavour2>, ... on Debian architecture <arch> |
| 127 | + |
| 128 | +You can use wildcards to cover multiple values, e.g. 'arm*' for armel, |
| 129 | +armhf and arm64 architectures. Also 'x86' is used to cover the Debian |
| 130 | +architectures amd64, i386 and x32. |
| 131 | + |
| 132 | +Kernel config files |
| 133 | +=================== |
| 134 | + |
| 135 | +Each kernel configuration file is constructed dynamically from a |
| 136 | +number of files under debian/config. They are read in the following |
| 137 | +order, such that files later on the list can override settings from |
| 138 | +earlier files. Most of the files are optional and the filenames can |
| 139 | +generally be overridden by explicit lists (possibly empty) specified |
| 140 | +in the 'defines' files. |
| 141 | + |
| 142 | +1. Common: |
| 143 | + - Default filename: config |
| 144 | + - Filename list: [image]configs in defines |
| 145 | +2. Per kernel architecture: |
| 146 | + - Filename: kernelarch-<karch>/config (optional) |
| 147 | +3. Per architecture: |
| 148 | + - Default filename: <arch>/config |
| 149 | + - Filename list: [image]configs in <arch>/defines |
| 150 | +4. Per architecture and flavour: |
| 151 | + - Default filename: <arch>/config.<flavour> (optional) |
| 152 | + - Filename list: [<flavour>_image]configs in <arch>/defines |
| 153 | +5. Per featureset: |
| 154 | + - Default filename: featureset-<fset>/config (optional) |
| 155 | + - Filename list: [image]configs in featureset-<fset>/defines |
| 156 | +6. Per architecture and featureset: |
| 157 | + - Default filename: <arch>/<fset>/config (optional) |
| 158 | + - Filename list: [image]configs in <arch>/<fset>/defines |
| 159 | +7. Per architecture, featureset, and flavour: |
| 160 | + - Default filename: <arch>/<fset>/config.<flavour> (optional) |
| 161 | + - Filename list: [<flavour>_image]configs in <arch>/<fset>/defines |
| 162 | + |
| 163 | +You can check the final list of configuration files by reading |
| 164 | +debian/rules.gen. Each binary-arch_<arch>_<fset>_<flavour>_real |
| 165 | +rule passes the list to debian/rules.real as the KCONFIG variable. |
| 166 | + |
| 167 | +Control file |
| 168 | +============ |
| 169 | +The master control file debian/control must be generated before |
| 170 | +the package is uploaded. debian/rules contains the debian/control |
| 171 | +target, which generates the control file by invoking the |
| 172 | +debian/bin/gencontrol.py script, which combines the templates from |
| 173 | +the templates directory and architecture-specific defines file to |
| 174 | +produce the debian/control file. Note that this target is intentionally |
| 175 | +made to fail with a non-zero exit code to make sure that it is never |
| 176 | +run during an automatic build. The following variables are substituted |
| 177 | +into the templates: |
| 178 | + |
| 179 | +@version@ Upstream kernel version, for example 2.6.11. |
| 180 | +@arch@ The Debian arch name, such as powerpc or i386. |
| 181 | +@flavour@ The build flavour, such as 686 or k7-smp. |
| 182 | +@class@ The CPU/architecture class; displayed in synopsis. It should |
| 183 | + be fairly short, as the synopsis is supposed to be <80 chars. |
| 184 | + It should be in the form "foo class", and will show up in the |
| 185 | + description as "foo class machines". |
| 186 | +@longclass@ The CPU/architecture class; displayed in the extended |
| 187 | + description. The same rules apply as in @class@. If |
| 188 | + this is unset, it will default to @class@. |
| 189 | +@desc@ (Potentially) multi-line verbiage that's appended to |
| 190 | + -image descriptions. |
| 191 | +@abiname@ Current abiname, a single digit. |
| 192 | + |
| 193 | +Normally, the arch-specific contents should be controlled by |
| 194 | +adjusting the corresponding defines file. |
| 195 | + |
| 196 | +TODO: |
| 197 | +- Patches applied to the upstream source |
| 198 | +- How to define a flavour |
| 199 | +- More detail on generation of debian/control and configs |
| 200 | + |
| 201 | +Running tests |
| 202 | +============= |
| 203 | + |
| 204 | +linux supports autopkgtest and should be able to run most of the |
| 205 | +kernel's self-tests on any architecture where kexec is supported, |
| 206 | +but it has higher resource requirements than most packages: |
| 207 | + |
| 208 | +- A VM with plenty of disk space (10GB is enough), RAM (1GB is |
| 209 | + probably enough) and at least 2 CPUs |
| 210 | +- The temporary directory for adt-virt-qemu (-o option) will need |
| 211 | + several GB of space, so a tmpfs may not be suitable |
| 212 | + |
| 213 | +Note that if you tell adt-run to use an 'unbuilt tree' (i.e. an |
| 214 | +unpacked source package) it does not exclude VCS directories such as |
| 215 | +.git. Either use a packed source package or copy the working tree |
| 216 | +elsewhere excluding .git. |
| 217 | + |
| 218 | +Example invocation: |
| 219 | + |
| 220 | + adt-run -B ../linux-image-4.2.0-rc6-amd64_4.2~rc6-1~exp2_amd64.deb \ |
| 221 | + ../linux_4.2~rc6-1~exp2.dsc \ |
| 222 | + --timeout-test=1200 \ |
| 223 | + --- adt-virt-qemu /var/cache/autopkgtest/adt-sid.img -o /var/tmp -c 2 |
| 224 | + |
| 225 | +Build profiles |
| 226 | +============== |
| 227 | + |
| 228 | +Several build profiles are understood and supported: |
| 229 | + |
| 230 | +- stage1: Needed when bootstrapping an architecture. A stage1 build |
| 231 | + produces only the linux-libc-dev package and has no host |
| 232 | + build-dependencies. |
| 233 | +- nodoc: Exclude most documentation |
| 234 | +- pkg.linux.notools: Exclude userland tool packages (linux-kbuild-<version>, |
| 235 | + linux-perf-<version>, etc.) |
| 236 | +- cross: Needed when cross-building. Currently this must be used together |
| 237 | + with nopython as the build-dependencies will be unsatisfiable otherwise. |
| 238 | +- nopython: Disable Python bindings. This currently disables building the |
| 239 | + linux-perf-<version> package, as the perf program embeds Python. |
0 commit comments