linux-kernel-2.6.12/debian/README

Migrating to the common kernel-image package
--------------------------------------------
Files for architecture <arch> should be placed into arch/<arch>.
Minimally, this directory should contain a control.in, config.default
and at least one flavour configuration file config.<flavour>. It can
optionally contain config.common, Makefile.inc and multiple flavour
configuration files. For arches with subarches the subdirectory
arch/<arch>/<subarch> with the same file structure must be created
for each subarch.

Config files
------------
Configuration files are constructed dynamically by concatenating a number
of config files as described below. Any of the files, except the .default
and lowest-level .<flavour> files, may be missing.

For architecture without subarches:

  Configuration file for kernel-image:

  arch/config.common
  arch/<arch>/config.common 
  arch/<arch>/config.<flavour>
  
  Configuration file for kernel-headers:

  arch/<arch>/config.default

For architecture with subarches:

  arch/config.common
  arch/<arch>/config.common
  arch/<arch>/<subarch>/config.common
  arch/<arch>/<subarch>/config.<flavour>

  Configuration file for kernel-headers:

  arch/<arch>/<subarch>/config.default

It is possible to avoid the inclusion of the arch-independent
config file (handy for the transitional period) by setting the
include_common_config variable to 'no' in Makefile.inc.

Debian and arch/subarch specific patches
-----------------------------
This is not really settled yet. Ideally we would like to integrate all
this stuff into the kernel-source package. So for now it is probably
reasonable to assume that common-arch debian patches are going to be
in debian/patches directory. As I understand, we will not need the
kernel-tree stuff, as the source with patches is going to accompany each
upload. So we might just place them there along with the list, which will
determine the order of application. For unmerged arch/subarch specific
patches we can do the same in the arch/subarch directory: patches/
subdir will contain patches and a list. Currently the kernel is patched
using the kernel-source package only.

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 concatenating the 
common debian/control.in and all the control.in files found in
and in subdirectories of arch/<arch>, and performing the variable
substitution. Currently the following variables are going to be
substituted:

@karch@     Replaced by the architecture string, identical to
            DEB_HOST_ARCH, as returned by dpkg-architecture.
@version@   Upstream kernel version, for example 2.6.11.
@ktver@     Minor version of kernel-tree to build-depend on. 
@abiname@   Abiname value for this set of packages.
@kbpkg@     Current name and version of the kernel-build
            package to build-depend on. Typical value may 
            be 'kernel-build-2.6-3', for example.

After variable substitution the resulting file is formatted to
ensure that the only blank lines are the ones separating the
entries (i.e. before the next Package: line).

Makefile.inc
------------
Each architecture subdirectory in arch may contain a Makefile.inc
file, which is included by debian/rules after definining all the
variables. It may be used to override the standard variables on
per-architecture basis and other evil things. So far the valid uses of
this file include the setting of the following variables:

include_common_config   

  Setting it to 'no' (without quotes) will prevent the common kernel
  config from being included for this particular architecture.
  Typical usage:

  include_common_config := no

headers_dirs            

  This variable is substituted into the headers-install script,
  controlling which asm-* directories are included into the
  kernel-headers package. By default it is set to karch (see
  above). See header-install.in file for detail. Typical usage:
  
  headers_dirs := sparc | sparc64

headers_extra

  This variable is substituted into the headers-install script,'
  and may be used to specify extra files, which a particular
  architecture would like to include in the kernel-headers package.
  Files should be specified with a full path relative to the
  top-level kernel directory, unquoted and separated by spaces.
  Typical usage:

  headers_extra := arch/i386/kernel/asm-offsets.s

headers_subarch

  The subarch to pass to the --subarch option for the make-kpkg
  call to build the kernel-headers. Typical usage:

  headers_subarch := sparc64

added_patches

  Setting this variable to non-empty value will cause an option
  --added_patches to be added to the make-kpkg 'build' and
  'kernel-image' calls. The value of the variable will be
  given as an argument for the --added-patchs option. The value
  of this variable may contain a special string @uver@ which
  is going to be expanded into the upstream kernel's version
  with dots replaced by underscores (for example, 2_6_11 for the
  kernel version 2.6.11). Typical usage:

  added_patches := debian,hppa-@uver@

build_subarch

  Setting this variable to non-empty value will cause an option
  --subarch to be added to 'build' and 'kernel-image' make-kpkg
  calls, followed by the flavour for which the kernel is built.
  In general, if you wish to add subarch support for your 
  architecture, you should contact kernel-package maintainer
  to ensure that the flavour name correctly maps onto a kernel
  subarch name. Currently only mips and sparc are using this
  facility, and both of them should be fine. Typical usage:

  build_subarch := yes

  Note that the value of this variable is ignored.

build_makeflags

  This variable may contain the make flags settings for the
  make-kpkg invocation in the 'build' target. Currently it is
  only used by amd64, where it should be set to something like

  build_makeflags := 'CC=amd64-linux-gcc V=1'

  The value of the variable must be properly quoted. 
 
initrd_modules

  This variable may contain a space-separated list of modules
  which should be hard-linked into the /lib/modules/<version>/initrd
  directory, so that they will be included by mkinitrd. Full
  pathname relative to the /lib/modules/<version> directory should
  be give, no quoting is necessary. Typical usage:

  initrd_modules := kernel/drivers/video/vesafb.ko kernel/security/capability.ko
1	jurij-guest	3148	Migrating to the common kernel-image package
2			--------------------------------------------
3			Files for architecture <arch> should be placed into arch/<arch>.
4			Minimally, this directory should contain a control.in, config.default
5			and at least one flavour configuration file config.<flavour>. It can
6			optionally contain config.common, Makefile.inc and multiple flavour
7			configuration files. For arches with subarches the subdirectory
8			arch/<arch>/<subarch> with the same file structure must be created
9			for each subarch.
10
11	jurij-guest	3034	Config files
12			------------
13	jurij-guest	3148	Configuration files are constructed dynamically by concatenating a number
14			of config files as described below. Any of the files, except the .default
15			and lowest-level .<flavour> files, may be missing.
16	jurij-guest	3034
17	jurij-guest	3148	For architecture without subarches:
18
19			Configuration file for kernel-image:
20
21			arch/config.common
22			arch/<arch>/config.common
23			arch/<arch>/config.<flavour>
24
25			Configuration file for kernel-headers:
26
27			arch/<arch>/config.default
28
29			For architecture with subarches:
30
31			arch/config.common
32			arch/<arch>/config.common
33			arch/<arch>/<subarch>/config.common
34			arch/<arch>/<subarch>/config.<flavour>
35
36			Configuration file for kernel-headers:
37
38			arch/<arch>/<subarch>/config.default
39
40	jurij-guest	3034	It is possible to avoid the inclusion of the arch-independent
41			config file (handy for the transitional period) by setting the
42	jurij-guest	3148	include_common_config variable to 'no' in Makefile.inc.
43	jurij-guest	3034
44	jurij-guest	3148	Debian and arch/subarch specific patches
45			-----------------------------
46			This is not really settled yet. Ideally we would like to integrate all
47			this stuff into the kernel-source package. So for now it is probably
48			reasonable to assume that common-arch debian patches are going to be
49			in debian/patches directory. As I understand, we will not need the
50			kernel-tree stuff, as the source with patches is going to accompany each
51			upload. So we might just place them there along with the list, which will
52			determine the order of application. For unmerged arch/subarch specific
53			patches we can do the same in the arch/subarch directory: patches/
54			subdir will contain patches and a list. Currently the kernel is patched
55			using the kernel-source package only.
56
57	jurij-guest	3034	Control file
58			------------
59			The master control file debian/control must be generated before
60			the package is uploaded. debian/rules contains the debian/control
61			target, which generates the control file by concatenating the
62	jurij-guest	3148	common debian/control.in and all the control.in files found in
63			and in subdirectories of arch/<arch>, and performing the variable
64			substitution. Currently the following variables are going to be
65			substituted:
66	jurij-guest	3034
67			@karch@ Replaced by the architecture string, identical to
68			DEB_HOST_ARCH, as returned by dpkg-architecture.
69			@version@ Upstream kernel version, for example 2.6.11.
70			@ktver@ Minor version of kernel-tree to build-depend on.
71			@abiname@ Abiname value for this set of packages.
72			@kbpkg@ Current name and version of the kernel-build
73			package to build-depend on. Typical value may
74			be 'kernel-build-2.6-3', for example.
75
76			After variable substitution the resulting file is formatted to
77			ensure that the only blank lines are the ones separating the
78			entries (i.e. before the next Package: line).
79
80			Makefile.inc
81			------------
82			Each architecture subdirectory in arch may contain a Makefile.inc
83			file, which is included by debian/rules after definining all the
84			variables. It may be used to override the standard variables on
85			per-architecture basis and other evil things. So far the valid uses of
86			this file include the setting of the following variables:
87
88			include_common_config
89
90	jurij-guest	3198	Setting it to 'no' (without quotes) will prevent the common kernel
91			config from being included for this particular architecture.
92			Typical usage:
93	jurij-guest	3034
94	jurij-guest	3104	include_common_config := no
95	jurij-guest	3034
96	jurij-guest	3104	headers_dirs
97
98	jurij-guest	3034	This variable is substituted into the headers-install script,
99			controlling which asm-* directories are included into the
100			kernel-headers package. By default it is set to karch (see
101	jurij-guest	3104	above). See header-install.in file for detail. Typical usage:
102
103			headers_dirs := sparc \| sparc64
104	jurij-guest	3044
105	jurij-guest	3136	headers_extra
106
107			This variable is substituted into the headers-install script,'
108			and may be used to specify extra files, which a particular
109			architecture would like to include in the kernel-headers package.
110			Files should be specified with a full path relative to the
111			top-level kernel directory, unquoted and separated by spaces.
112			Typical usage:
113
114			headers_extra := arch/i386/kernel/asm-offsets.s
115
116	jurij-guest	3104	headers_subarch
117	jurij-guest	3044
118	jurij-guest	3104	The subarch to pass to the --subarch option for the make-kpkg
119			call to build the kernel-headers. Typical usage:
120	jurij-guest	3044
121	jurij-guest	3104	headers_subarch := sparc64
122	jurij-guest	3044
123			added_patches
124
125			Setting this variable to non-empty value will cause an option
126	jurij-guest	3104	--added_patches to be added to the make-kpkg 'build' and
127			'kernel-image' calls. The value of the variable will be
128			given as an argument for the --added-patchs option. The value
129			of this variable may contain a special string @uver@ which
130			is going to be expanded into the upstream kernel's version
131			with dots replaced by underscores (for example, 2_6_11 for the
132			kernel version 2.6.11). Typical usage:
133	jurij-guest	3044
134	jurij-guest	3104	added_patches := debian,hppa-@uver@
135	jurij-guest	3044
136	jurij-guest	3104	build_subarch
137
138	jurij-guest	3044	Setting this variable to non-empty value will cause an option
139	jurij-guest	3104	--subarch to be added to 'build' and 'kernel-image' make-kpkg
140			calls, followed by the flavour for which the kernel is built.
141			In general, if you wish to add subarch support for your
142			architecture, you should contact kernel-package maintainer
143	jurij-guest	3044	to ensure that the flavour name correctly maps onto a kernel
144			subarch name. Currently only mips and sparc are using this
145	jurij-guest	3104	facility, and both of them should be fine. Typical usage:
146
147			build_subarch := yes
148
149			Note that the value of this variable is ignored.
150
151			build_makeflags
152
153			This variable may contain the make flags settings for the
154			make-kpkg invocation in the 'build' target. Currently it is
155			only used by amd64, where it should be set to something like
156
157			build_makeflags := 'CC=amd64-linux-gcc V=1'
158
159			The value of the variable must be properly quoted.
160	jurij-guest	3136
161			initrd_modules
162
163			This variable may contain a space-separated list of modules
164			which should be hard-linked into the /lib/modules/<version>/initrd
165			directory, so that they will be included by mkinitrd. Full
166			pathname relative to the /lib/modules/<version> directory should
167			be give, no quoting is necessary. Typical usage:
168
169			initrd_modules := kernel/drivers/video/vesafb.ko kernel/security/capability.ko