This file is indexed.

/usr/share/kernel-package/docs/README is in kernel-package 12.036+nmu3.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

   1
   2
   3
   4
   5
   6
   7
   8
   9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
   $Id: README,v 1.66 2003/08/26 01:47:23 srivasta Exp $

This is the Debian GNU/Linux prepackaged version of the Linux kernel.
Linux was written by Linus Torvalds <Linus.Torvalds@cs.Helsinki.FI> and
others.

This package was put together by Herbert Xu <herbert@greathan.apana.org.au>

Linux is copyrighted by Linus Torvalds and others.

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; version 2 dated June, 1991.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program;  if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
   02111-1307  USA 

On Debian GNU/Linux systems, the complete text of the GNU General
Public License can be found in `/usr/share/common-licenses/GPL'.

INSTALLATION NOTES:

Before you go any further, please allow me to point out that you need to
have a few other packages installed before you can compile your own kernels
(it is difficult to compile anything without a compiler ;-). 

Firstly, you will need gcc, the libc development package (libc5-dev or
libc6-dev at the time of writing), and, on Intel platforms, bin86. [If
you use the menuconfig target of make, you will need ncursesX.X-dev,
and make xconfig also requires either tkX.X-dev for 2.4.X kernels, or
libqt3-mt-dev and g++ >= 3.0 for the new 2.6 kernel versions, and 2.6.X
kernels also have an additional option, make gconfig, which requires
libglade2-dev, and other packages these depend on]

The packages suggested are:
devel:        gcc, libc5-dev/libc6-dev, binutils, make, and, for intel
              x86 platforms, bin86 (non-Intel platforms don't need
              this), modutils (or module-init-tools for 2.5.x+ kernels).
interpreters: awk, which is contained in either the mawk or gawk packages
base:         gzip, shellutils, and grep.

Some of these packages are marked essential, and hence are going to be
present on your machine already. Others you have to check and install.

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-3.2" make-kpkg ...
(please see the top level kernel Makefile).

Of course, pretty GUI front ends to kernel configuration require more
packages, but they are not strictly essential (though quite nice really). 

Oh, and of course, make-kpkg is part of kernel-package, usually found
in section misc.


 For the Brave and the impatient: (Look for Kent's 10-Step Procedure
 to Compiling a Debian Kernel near the tail end of this file for
 more detailed HOWTO)

Phase ONE: Getting and configuring the kernel
 1% cd <kernel source tree> (make sure you have write permission there)
 2% make config # or make menuconfig or make xconfig (or, for 2.6.x
    kernels, make gconfig) and configure

Phase TWO: Create a portable kernel image .deb file
 3% make-kpkg clean
    Or just rm -rf ./debian, if you do not want to get rid of the
    previous state and only rebuild whatever required for any
    changes. 
 4% $Get_Root make-kpkg --revision=custom.1.0 kernel_image 
      (Get_Root is whatever you need to become root -- fakeroot or
      sudo are examples that come to mind).  NOTE: if you have
      instructed your boot loader to expect initrd kernels (which is
      the norm for recent kernel image packages) you need to
      add --initrd to the line above.
   % $Get_Root make-kpkg --initrd --revision=custom.1.0 kernel_image 
      Personally, I prefer non initrd images for my personal machines,
      since then adding third party modules to the machine has fewer
      gotchas. Note that you will have to arrange for the actual
      initrd creation to take place by installing a script like
      /usr/share/kernel-package/examples/etc/kernel/post{inst,rm}.d/yaird,
      or, alternately,
      /usr/share/kerne-package/examples/etc/kernel/post{inst,rm}.d/initramfs 
      into the corresponding directories /etc/kernel/post{inst,rm}.d,
      since the kernel-postinst does not arrange for the initramfs
      creator to be called. You can thus select your own;
      initramfs-tools or yaird.

Phase THREE: Install the kernel image on one or more machines
 5# dpkg -i ../kernel-image-X.XXX_1.0_<arch>.deb
 6# shutdown -r now # If and only if LILO/SILO/QUIK/PALO/VMELILO/ZIPL/yaboot/..
                    # worked or you have a means of
                    # booting the new kernel. YOU HAVE BEEN WARNED!!

 With the addition of fakeroot ( a really nice program, I recommend
 it). Steps 1 to 4 can be carried out as a non root user. Step 5 does
 require root privileges.

Getting the kernel source
------- --- ------ ------

 You can get kernel sources in several different ways: by installing a
 prepackaged Debian kernel source package created by make-kpkg. This
 shall create a file /usr/src/kernel-source-2.4.20.tar.bz2, which can
 be unpacked wherever you wish. Alternately, you can get
 linux-2.4.20.tar.bz2 from you favorite ftp.kernel.org mirror,
 (/pub/linux/kernel/v2.4/ in the FTP site).

Unpacking kernel sources:
-------------------------

Some of the suggestions about where to unpack the kernel packages are
a) /tmp/linux
b) /var/tmp/linux
c) /usr/local/src/<whatever>
d) /usr/src/linux-X.X.XX; where X.X.XX is the version number of the
   kernel. 

In any case, choose a partition that has a large amount of free space,
since recent kernels, unpacked, run to about 23MB, and you need more
than double that in order to create kernel-image, kernel-source, and
the tar file (that is, if you choose to build everything together with
the dist target in debian.rules -- say if you want, for whatever
reason, to run dchanges on the files created). I needed nearly 60MB to
create the full spectrum of packages for version 1.99.7 (and doubtless
this size will go up in the future) [It has. Now even an gzipped kernel
source is over 23MB].

Make sure that the user who is building the kernel has adequate write
permissions in the kernel source tree, and also has write permissions
in MODULES_LOC and its parent directory, or is using sudo or some
other means of getting these write permission while building.

[ EXAMPLE
So, suppose you have chosen /usr/local/src/kernel as the place to
build kernels.
% cd  /usr/local/src/kernel # or cd /path/to/where-ever/you/have/space
% tar jvvfx /usr/src/kernel-source-2.4.20.tar.bz2
  (or, tar jvvfx /path/to/download/linux-2.4.20.tar.bz2)

	The next two steps are optional, you only need them if you are
 going to create third party modules (stuff in
 /usr/src/module-name.tar.gz)

 % export MODULE_LOC=/usr/local/src/kernel/modules
 % tar jvvfx /usr/src/some-module.tar.gz
]

Now, cd linux (wherever you have created the kernel sources). Make
sure you have the permission to write in that dir, or that you are
using sudo or some other means of getting this write permission while
building.

Configuration File
------------- ----

The kernel now needs to be configured, that is you have to set the
kernel options and select the drivers which are going to be included,
either as built-in, or as external modules. These setting are saved in
a file ./config.  The kernel build infrastructure offers a number of
targets, which invoke different configuration front-ends. 

Kernel package by itself does not create any configuration file
(.config); it uses whatever you have. You can use the previous version
made for you machine by copying it over from /boot/config-Y.Y.YY, like
so:
 % cp /boot/config-Y.Y.YY .config
where Y.Y.YY stands for the old version of the kernel that you had
hand tuned.

If you do not wish to copy the old copy over, you can create a new one
from scratch using console-based menu configuration command "make
menuconfig" (please look at the kernel documentation for help on
configuring your kernel). Instead of menuconfig one can use config
(text-based line-by-line configuration front-end) or xconfig (graphical
configuration front-end).

After the configuration process is finished, the new or updated kernel
configuration will be stored in .config file in the top-level
directory.


Versions and revisions
----------------------

The version number is deduced from the kernel Makefile directly to
ensure that the version numbers are in sync[1], so you don't have to
worry about that.

Then, remember to change the revision number (using the --revision
option of make-kpkg).  It has been suggested that you renumber the
revision number in such a way that a generic kernel image package will
not override the custom package while using dselect (or dpkg
-BOGiE). You may also do this on the fly by setting the
DEBIAN_REVISION environmental variable.

"--revision" affects the name of the Debian package itself but not the
kernel name, so "uname -r" won't show the revision, and it will use
the same modules as other revisions of the same version.

If I may digress to talk about "--append-to-version",
"--append-to-version=bla" affects the name of the Debian package
itself, and also appends the append-to-version text to the kernel name
AND to the modules directory name when dpkg installs the kernel, so
this kernel will have its own set of modules, separate from the
modules used by the default kernel with the same version.

The revision number (the argument supplied after the --revision flag)
has certain constraints: 
a) It only has an effect during the configure phase.
   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.
   (just rm -rf ./debian should work)
b) It may contain only alphanumerics and the characters + . (full
   stop, and plus) and should contain a digit.  NOTE: No hyphens
   allowed (Look at the Debian Policy manual for details). Optionally,
   you may prepend the revision with a digit followed by a colon (:);
   this shall put your revision into a new epoch; more on this later.

You should _not_ use a "_" in the revision number! As tempting as it may
seem, it actually interferes with the policy.

The revision number is required because dpkg imposes an ordering on
version numbers, so that it can tell whether packages are being up- or
downgraded and so that dselect can tell whether a package it finds
available is newer than the one installed on the system. Dselect uses
an option that prevents a package from being downgraded, for example.

Packaged kernel-images in the distribution also have a version number -
not at all coincidentally coinciding with the kernel version, because it
is used to reflect the upstream version number. Note that the kernel
version is also part of the package's name, thus it appears twice in the
package's file name. It also gets a debian revision number relating to
differences in builds. It then looks like: 
  kernel-image-2.0.29_2.0.29-8.deb

I've found that using a two-level scheme where the major level starts
with a letter nicely does the job -- unless epochs are used,
(--revision custom.Y, so the image package become
kernel-image-X.X.XX-custom.Y.deb), and dselect and dpkg -BOGiE will
refuse to downgrade to a generic kernel (don't give the BOG arguments
to dpkg if you actually do want to downgrade later).

The reason for telling kernel-package that the package has a version
"custom-x.y.whatever.you-want.to+add.more-just.do.not+use.an=underscore" 
is that to dpkg that is always a higher version number than any version
number starting with a numeral ( e.g. "a" > "2" like "b" > "a". ) This way,
dselect will not try to upgrade your "roll-it-yourself" kernel-image when
a new build of the distribution default kernel appears in the archive. 


Unfortunately, this fails if the upstream maintainer uses epochs to
correct a version misnumbering ;-(. The good news is that you can add
your own epoch to your customized image, ugly though that may
be. (--revision 1:custom.Y; the kernel image file shall remain
kernel-image-X.X.XX-custom.Y.deb, but dpkg shall know that it should
not replace that with a standard kernel with an epoch. Hopefully, we
shall never see an epoch greater than 1 on a standard kernel, but who
knows. Choose your epoch, if you must use it, wisely. I fear, though,
that with the introduction of epochs in kernel image versions shame
has entered the garden of eden, and we must forever use epochs to
guard against forced upgrades.

So, try using an epoch for your custom packages: 
  make-kpkg clean
      (or just rm -rf ./debian, if you do not want to rebuild from the
      beginning)
  $Get_Root make-kpkg --revision=3:custom.1.0 kernel_image
      (Get_Root is whatever you need to become root -- fakeroot or
      sudo are examples that come to mind).

And the next time when you build a kernel, because you just bought a new
sound card or you discovered that you suddenly want masquerading in your
kernel enabled, you'll type: 
  make-kpkg clean
      (or just rm -rf ./debian)
  $Get_Root make-kpkg --revision=3:custom.2.0 kernel_image
      (Get_Root is whatever you need to become root -- fakeroot or
      sudo are examples that come to mind).
(remember to do rm -rf ./debian or a make-kpkg clean before you
compile again with a different revision, or else the revision flag
shall not have any effect)

Note that you will have to arrange for the actual initrd creation to
take place by installing a script like
/usr/share/kernel-package/examples/etc/kernel/post{inst,rm}.d/yaird,
or, alternately,
/usr/share/kernel-package/examples/etc/kernel/post{inst,rm}.d/initramfs
into the corresponding directories /etc/kernel/post{inst,rm}.d, since
the kernel-postinst does not arrange for the initramfs creator to be
called. You can thus select your own; initramfs-tools or yaird


 NOTE about using initial ram disk images (initrd).  Recent kitchen
 sink kernel image packages tend to use this, in order to accommodate
 as wide a variety of root file system types as humanly possible
 without building them all into the kernel. In order to use these
 images, you need to instruct you boot loader that this is a kernel
 image using initrd, and tell the boot loader where to find the initrd
 image.  Unfortunately, you can't just substitute a non initrd image
 afterwards without changing the boot loader instructions.  So, if
 your boot loader configuration expects to see an initrd image, add
 --initrd to the above invocation, like so:
   make-kpkg clean
        (or just rm -rf ./debian, if you do not want to rebuild from the
         beginning)
   $Get_Root make-kpkg --initrd --revision=3:custom.2.0 kernel_image

With the new kernel-package conventions, you also need the example
scripts in /etc/kernel/postinst.d/ and /etc/kernel/postrm.d, to create
and remove the initramfs. Make sure that these scripts pay attention
to the INITRD env variable to determine whether or not to take any
action.

 Let me repeat: 
 Since nothing is created automatically. you need to provide a hook
 script for things to happen when you install the kernel image
 package.  The user provides such scripts. For example, to invoke
 mkinitramfs, I did:
--8<---------------cut here---------------start------------->8---
 cp /usr/share/kernel-package/examples/etc/kernel/postinst.d/yaird \
    /etc/kernel/postinst.d/
 cp /usr/share/kernel-package/examples/etc/kernel/postrm.d/yaird \
    /etc/kernel/postrm.d/
--8<---------------cut here---------------end--------------->8---

        Or, alternately, you could do:
--8<---------------cut here---------------start------------->8---
 cp /usr/share/kernel-package/examples/etc/kernel/postinst.d/initramfs \
    /etc/kernel/postinst.d/
 cp /usr/share/kernel-package/examples/etc/kernel/postrm.d/initramfs \
    /etc/kernel/postrm.d/
--8<---------------cut here---------------end--------------->8---


        These scripts above do nothing unless the corresponding
 packages are installed (initramfs-tools or yaird), so you could
 potentially cp both over -- as long as you never install both yaird
 and initramfs-tools at the same time.

        To run grub, I have in /etc/kernel-img.conf:
--8<---------------cut here---------------start------------->8---
postinst_hook = update-grub
postrm_hook   = update-grub
--8<---------------cut here---------------end--------------->8---

You can look at other example in the examples directory:
/usr/share/kernel-package/examples/ to see if there are other example
script you want to cp into /etc/kernel -- and you can create your own
scripts.

For example, if you use linux-headers-* packages to compile third
party modules so that you do not have to keep the sources directory
around, you might be interested in:
--8<---------------cut here---------------start------------->8---
/etc/kernel/header_postinst.d/link
/etc/kernel/header_postrm.d/link
/etc/kernel/header_prerm.d/link
/etc/kernel/postinst.d/force-build-link
/etc/kernel/postrm.d/force-build-link
--8<---------------cut here---------------end--------------->8---

        These scripts will try to make sure that the symlink
 /lib/modules/$VERSION/build 
 is sane -- that is points to the header packages whether you install
 the image packages first, or the header packages first -- and takes
 care of cleanup when either of the packages are installed.

When make-kpkg is finished, you'll have 
kernel-image-2.0.29_custom.1.0_i386.deb and all it takes now is to
install the package (as root):
# dpkg -i kernel-image-2.0.29_custom.1.0_i386.deb

This will install the kernel, the modules, the map file and do some other
administrativia and finally it will ask you if you want to make a
boot floppy and if you want to run lilo now. 

Now, there is a caveat: If you already have kernel 2.0.29 installed,
and you have a freshly created custom 2.0.29 kernel, just installing
the new 2.0.29 kernel shall install modules (as it should) in
/lib/modules/2.0.29, which is where the old modules were! If you have
added or removed modules relative to the old 2.0.29 kernel (very
likely if your old kernel was the default gigantic generic kernel),
then you shall have a mish-mash of modules in /lib/modules/2.0.29 ;-(

Unfortunately, there is no reasonable solution; I suggest moving the
old modules directory before installation, like so (need to be root):

        # mv /lib/modules/2.0.29 /lib/modules/2.0.29.save
        # dpkg -i kernel-image-2.0.29_custom.1.0_i386.deb
and later get rid of the .save directory.

People who want to have multiple flavors of the same kernel version
around should look at the append_to_version flag of make-kpkg. This
appends to the EXTRAVERSION variable of the kernel Makefile, and does
not require one to edit that makefile manually.  This can also be done
by setting the environment variable APPEND_TO_VERSION. The command
line invocation overrides the env variable. 

You may also place long term directives (like your name and email
address) in the file /etc/kernel-pkg.conf (or ~/.kernel-pkg.conf).
Putting your name and address in that file is a good idea, to remind
you that this is not an official package, unless, of course, you
happen to be the maintainer (Hi Herbert). The file
/etc/kernel-pkg.conf (or ~/.kernel-pkg.conf) is actually a Makefile
snippet included during the kernel packages build process, and hence
you may put any legal Makefile directive in that file (just make very
sure you know what you are doing ;-).

        At the moment, the user modifiable variables supported are:

maintainer	Local kernel-* package maintainer.  Please note that
                any apostrophes "'" shall have to be quoted like so: 
                maintainer = John O'\\''Brien. 
                Yes, this is ugly, but this works.

email           The email address of that person.

pgp             Name to search for in the pgp database _iff_ separate
                modules (like pcmcia etc) are being built in
                $(MODULE_LOC:-/usr/src/modules)/*. Can be set from
                environment variable PGP_SIGNATURE. Defaults to
                maintainer.

debian 		The Debian revision of the kernel packages. Can be set
		from the environment variable DEBIAN_REVISION. Defaults
		to 1.0.

kimage		The kernel image type (i.e. zImage or bzImage). Can be
		set from the environment variable IMAGE_TYPE. Defaults
		to bzImage.

image_dest    If  you  want  the  symbolic  link  (or  image,  if
              move_image is set) to be stored elsewhere than /
              set this variable to the dir  where  you  want  the
              symbolic  link.   Please  note  that  this is not a
              boolean variable.  This may be of help  to  loadlin
              users,  who  may  set  both  this  and  move_image.
              Defaults to /. 

root_cmd         This should be set to a means of gaining superuser
                 access (for example, `sudo' or `fakeroot') as needed
                 by dpkg-buildpackages' -r option. This is  used
                 to call dpkg-buildpackage with the proper
                 options. The environment variable ROOT_CMD overrides
                 this.

do_clean	 Set to anything but YES, this shall forego the make
                 clean done in the kernel source tree after building
                 the kernel image package. The environment variable
                 CLEAN_SOURCE overrides this.

install_vmlinux  Set to YES to install the uncompressed kernel
                 ELF image along with the bootable compressed kernel
		 image (vmlinuz).
		 This image is necessary for profiling kernel and
		 userspace with oprofile (oprofile.sourceforge.net,
		 i386 only).

kpkg_follow_symlinks_in_src
              This option is especially useful for people who use
              symbolic link farms to compile kernels. With this option,
              kernel-source and kernel-header packages shall not be
              just full of dangling symlinks, instead, the symbolic
              links shall be followed. Please note that any symbolic
              links in the kernel sources would be flattened as well.
              The environment variable KPKG_FOLLOW_SYMLINKS_IN_SRC
              overrides this. Symlink farming is described below.

The value of a variable can be set so: 
  a) Defaults exist in the rules file. These are the values used if no
     customization is done.
  b) Variables can be set in the config file /etc/kernel-pkg.conf (or
     ~/.kernel-pkg.conf).  These values override the defaults.
  c) Variables can also be set by setting a corresponding environment
     variable.  These values override the config file and the defaults.
  d) Using make-kpkg options, or, if using the rules file directly, on 
     command line ( # xxx/rules DEBIAN_REVISION=2.0a kernel_image). This 
     overrides all the above methods.

Please see kernel-pkg.conf (5).

image_dest    If  you  want  the  symbolic  link  (or  image,  if
              move_image is set)   to be stored elsewhere than  /
              set this variable to the dir  where  you  want  the
              symbolic  link.   Please  note  that  this is not a
              Boolean variable.  This may be of help  to  loadlin
              users,  who  may  set  both  this  and  move_image.
              Defaults to /. 

move_image    Instead  of  creating  symbolic  links  to  (or, if
              reverse_symlinks  is  set,  from)  image_dest,  the
              image  is  moved  from  its  location in /boot into
              image_dest.   If  reverse_symlinks  is  set,  /boot
              shall  contain a symbolic link to the actual image.
              This option can be useful to people using  loadlin,
              who  may need the image to be moved to a  different
              dos partition.  This variable is unset by  default.

clobber_modules
              If  set,  the  preinst  shall  silently try to move
              /lib/modules/version out of the way if  it  is  the
              same  version  as the image being installed. Use at
              your own risk.  This variable is unset by  default.

postinst_hook
              Set this variable to a script to be executed during
              installation. This script shall be called with two
              arguments, the first being the version of the kernel
              image, and the second argument being the location of the
              kernel image itself. Errors in the script shall produce
              a warning message, but shall be otherwise ignored.  An
              example script for grub users is present in
              /usr/share/doc/kernel-package/ directory.
postrm_hook
              Set this variable to a script to be executed in the
              postrm (that is, after the image has been  removed)
              after  all  the remove actions have been performed.
              This script shall be called with two arguments, the
              first  being  the  version of the kernel image, and
              the second argument being the location of the  ker-
              nel  image  itself. Errors in the script shall pro-
              duce a warning  message,  but  shall  be  otherwise
              ignored.

Please see kernel-img.conf (5).


To generate a new kernel image, just run
% make-kpkg clean
  (or just rm -rf ./debian)
% $Get_Root make-kpkg --revision=custom.1.0 kernel_image
      (Get_Root is whatever you need to become root -- fakeroot or
      sudo are examples that come to mind) or (if you use initrd)
   $Get_Root make-kpkg --initrd --revision=3:custom.2.0 kernel_image

This will create a default kernel image (as in the image package or
available on the boot disks. 

If you want a custom kernel, you may generate a config file by any of
these methods (just follow the directions).
% make config          # boring old tty based method
or
% make menuconfig      # curses based menu driven method (uses color if 
                         you have any)
% make xconfig         # An X window system based method -- make sure
                         you are running X windows when you call this.
% make gconfig         # The gnome version, if you have version 2.6.X.
All these methods ultimately generate a .config file.  If you already 
have a .config file, just copy it to this directory, and you are go.

With a custom .config file in place (created as above) run again:
% make-kpkg clean
     (or just rm -rf ./debian)
% $Get_Root make-kpkg --revision=custom.1.0 kernel_image
      (Get_Root is whatever you need to become root -- fakeroot or
      sudo are examples that come to mind).
   $Get_Root make-kpkg --initrd --revision=3:custom.2.0 kernel_image

|-----------------------------------------------------------------------|
|                           Special needs                               |
| Or, for people who want to minimize time spent in fakeroot (for       |
| whatever reasons that maybe -- I think that the separate step as      |
| non-fake-root is not required, but that is a personal opinion)        |
| % test ! -d debian || rm -rf debian                                   |
| % make-kpkg  --revision=custom.1.0 build                              |
| % $Get_Root make-kpkg --revision=custom.1.0 kernel_image              |
|     (Get_Root is whatever you need to become root -- fakeroot or      |
|     sudo are examples that come to mind)                              |
|                                                                       |
| For people who wish to see the username (not root) when they do a     |
| uname -a on the machine when they install the kernel, there is a      |
| trick:                                                                |
|  % make config                                                        |
|  % make-kpkg build                                                    |
|  % $Get_Root make -f debian/rules stamp-kernel-image                  |
| shall generate a kernel image with the username of the user embedded  |
| in it.                                                                |
|                                                                       |
| If you use initrd images (and have told your boot loader so) you need |
| to include the --initrd option on the command line, like so           |
|                                                                       |
| % $Get_Root make-kpkg --initrd --revision=3:custom.2.0 kernel_image   |
|                                                                       |
-------------------------------------------------------------------------

To create a source or header package, run
% make-kpkg clean
  (or rm -rf ./debian)
% $Get_Root make-kpkg --revision=custom.1.0 kernel_source
% $Get_Root make-kpkg --revision=custom.1.0 kernel_headers
Note: You only need one of these.
      (Get_Root is whatever you need to become root -- fakeroot or
      sudo are examples that come to mind).
Here is a nice, practical example:
% make-kpkg -rfakeroot --append-to-version $(hostname) \
               --revision $(date +'%Y%m%d')

Similarly, the documentation package is built by:
% $Get_Root make-kpkg --revision=custom.1.0 kernel_doc

Or if you want to generate the whole package, 
% $Get_Root make-kpkg --revision=custom.1.0 \
            --pgpsign="Your pgp ID" buildpackage
Note that this needs a pgp key.
      (Get_Root is whatever you need to become root -- fakeroot or
      sudo are examples that come to mind).

For folks using grub, there are now postinst_hook and postrm_hook
variables that can be pointed 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 dir
/usr/share/doc/kernel-package/; and simple scripts like:

  # perl -nle 'print unless /^#Autogenerated by kernel-image $version/ \
                        .. /^#End kernel-image '$version/'

 or for awk fans
  #  awk 'BEGIN{printit=1} 
      /^#Autogenerated by kernel-image $version/{printit=0}
      /^#End kernel-image '$version/{printit=1}
      {if (printit) {print}}'. 
 or
  #  awk '{p=0} 
          /^#Autogenerated by kernel-image $version$/,
          /^#End kernel-image '$version$/ {p=1}
     {if(!p) print}' < foo

 can be put in a script and added to the postrm hook script to remove
 the lines added by kernel_grub_conf.sh


 [1]# dpkg -BRGiE kernel-image-X.X.XX, # need to be root
        and then
 [2]% cp /boot/vmlinuz-X.X.XX <place where loadlin needs image>
 [3]% echo '' > /boot/vmlinuz-X.X.XX

        So you don't have the image taking up space, but still leave a
target for the /vmlinuz symlink.

 MODULES_LOC, SYMLINK FARMING, AND MORE
 ============ ======= ======== === ====

Oh, a quick recipe for people who want to build kernel-module
packages, and don't want to be root to do so (the following assumes
/usr/local/src/kernel is an appropriate location to build kernels):

###############################################################################
# % sudo echo 'MODULE_LOC=/usr/local/src/kernel/modules' \                    #
#                                             >> /etc/kernel-pkg.conf         #
# % sudo echo 'debian := 5:501c' >> /etc/kernel-pkg.conf                      #
# % sudo mkdir -p /usr/local/src/kernel/modules                               #
# % sudo chown -R $(id -n -u) /usr/local/src/kernel/                          #
# % sudo aptitude install cryptoapi-core cryptoloop # for example             #
#                                                                             #
#         Now, we no longer need to be root                                   #
#                                                                             #
# % cd /usr/local/src/kernel/                                                 #
# % wget ftp://ftp.us.kernel.org/pub/linux/kernel/v2.4/linux-2.4.21.tar.bz2   #
# % tar zvvfx /usr/src/cryptoapi-core.tar.gz                                  #
# % tar zvvfx /usr/src/cryptoloop.tar.gz                                      #
# % tar jvvfx linux-2.4.21.tar.bz2                                            #
# % mkdir 2.4.21                                                              #
# % cd 2.4.21                                                                 #
# % lndir ../linux-2.4.21                                                     #
# % cp /boot/config-2.4.20 .config                                            #
# % make-kpkg --rootcmd fakeroot --append-to-version -cryptoloop kernel_image #
# % fakeroot make-kpkg --append-to-version -cryptoloop modules_image          #
###############################################################################

	The above also demonstrates a technique called symlink farming. I like
 to upgrade between kernel version using patches from
 ftp.us.kernel.org; so I need to keep a source tree in as near a
 pristine state as I can. Once I have
 /usr/local/src/kernel/linux-2.4.20, say, I do this:
#########################################################################
#  last_version=2.4.18                        # I never went for 2.4.19 #
#  for machine in kallissin ember smaug scatha glaurung, tiamat ;do     #
#    mkdir $machine                                                     #
#    scp $machine:/boot/config-$last_version $machine/.config           #
#    cd $machine                                                        #
#    lndir ../linux-2.4.20                                              #
#    cd ..                                                              #
#  done                                                                 #
#                                                                       #
#  for machine in kallissin ember smaug scatha glaurung, tiamat ;do     #
#    if [ -f . configdirs/$machine ]; then                              #
#      . configdirs/$machine                                            #
#      # $patches is now either empty, or it has --added-patches=a,b    #
#    fi                                                                 #
#    cd $machine                                                        #
#    make-kpkg --rootcmd fakeroot --append-to-version $machine \        #
#        $patches $modules kernel_image                                 #
#    if [ "X$modules" != "X" ]; then                                    #
#       fakeroot make-kpkg  --append-to-version $machine \              #
#            $patches $modules modules_image                            #
#    fi                                                                 #
#    test ! -d debian || rm -rf debian                                  #
#  done                                                                 #
#########################################################################

        See? Each lndir directory only has files that were patched, or
 object files; and the ../linux-2.4.20 is pristine, ready to be
 patched up to 2.4.21.


Recompiling a kernel image
----------- - ------ -----

It happens to all of us. When we configured the kernel, we missed out
on an module. Or we added in more things than we really need, and need
to compile again. If you just recompile a kernel image, it shall, when
installed, contain the same /boot/{System.map,config,vmlinuz}-X.X.XX
files and the /lib/modules/X.X.XX directory that the previous kernel
image contained.

If you try to install the recompiled kernel image over the previous
kernel image (same version), then the install scripts
detect that, and ask you to move at least the /lib/modules/X.X.XX dir
away. If you continue anyway, the files in /boot shall be overwritten. 

Also, if you try to recompile with a changed --revision option or a
different debian revision, you shall have to remove ./debian, and then
recompile. 

Cross Compiling for a subarchitecture
----- --------- --- - ---------------

Suppose you want to compile a 32 bit kernel on a 64 bit (amd64, say)
machine, this is the incantation to use:

DEB_HOST_ARCH=i386 make-kpkg --arch i386 --cross-compile - <other options>

Tecras and other notebooks 
--------------------------
          (Many thanks to Philip Hands <phil@hands.com> and
           Avery Pennarun <apenwarr@worldvisions.ca> for this explanation)

Tecras and other notebooks, and some PCs have a problem where they
fail to flush the cache when switching on the a20 gate (IIRC), which
is provoked by bzImage kernels, but not by zImage kernels. 

bzImage files are actually "big zImage" not "bzipped Image".  bzImage
kernels can be as large as you like, but because they need to decompress
into extended memory, they aggravate this problem.  zImage kernels just
compress into conventional memory, so they never need to touch the a20 gate,
but they hit the 640k limit.

There are two solutions that I know of:

  1) Apply a patch, which flushes the cache.  Unfortunately this
     causes other machines to crash so is not universally applicable
     (hence the tecra disks being segregated from the mainstream).

  2) Build a zImage, rather than bzImage kernel.  This seems to get
     round the problem. use the --zimage option to make-kpkg, or even
     set this as the default in /etc/kernel-pkg.conf (or
     ~/.kernel-pkg.conf).

There some add-on modules that hook into make-kpkg and the kernel
sources so that they may be kept in synchrony with the kernel you
run. If you have such a module source package, for example,
pcmcia-source, then please read README.modules as well. If you don't
never mind. (The file is in /usr/share/doc/kernel-source-X.X.XX/. If you
don't have kernel-source packages installed [that's OK], there is a
copy in /usr/share/kernel-package/README.modules).

Have fun,

	Manoj Srivastava


Foot note 1:
  For an explanation on why this synchronization is required, consider
  this. The kernel knows what version it is, as given in the kernel
  Makefile as the variables VERSION, PATCHLEVEL, and SUBLEVEL. It will
  look for the modules in /lib/modules/$VERSION.$PATCHLEVEL.$SUBLEVEL.
  The Debian scripts think they know what the kernel version is, as
  given in the Debian file rules as the variable v (near the top). It
  then proceeds to put the modules in /lib/modules/$v.  So, it is
  essential that the kernel (Makefile) and the Debian script (rules)
  agree about the version number, or the kernel will never figure out
  where the Debian scripts hid the modules. So change the version
  number in the file rules (v = X.X.XX) to be the same version as
  given in the kernel Makefile (this will be
  $VERSION.$PATCHLEVEL.$SUBLEVEL).

#############################################################################
#############################################################################
## This is a working script contributed by Don Armstrong 

#!/bin/sh
# Copyright 2004 Don Armstrong (~don@archimedes.ucr.edu)
# This script is licensed under the GPL v2
KERNEL="linux-2.4.24"
MAKE_KPKG="make-kpkg"
EXTRAVERSION=`date +'%m%d%Y'`
MAKE_KPKG_OPTIONS="--rootcmd fakeroot --revision=$EXTRAVERSION"
DATE=`date +'%m_%d_%Y'`

for CONFIG in `cd config; ls *.gz; cd ..`; do
         MACHINE=$(echo $CONFIG|cut -d _ -f 1);
         gzip -dc config/$CONFIG > $KERNEL/.config
         cd $KERNEL
         test ! -d debian || rm -rf debian
         $MAKE_KPKG $MAKE_KPKG_OPTIONS --append-to-version $MACHINE kernel_image modules_image
    gzip -c .config > ../config/${MACHINE}_config_${KERNEL}_${DATE}.gz
    cd ..;
done;
 
#############################################################################
#############################################################################


-- 
Manoj Srivastava                        <srivasta@debian.org>
PGP Key ID: 1024/C7261095 
Key fingerprint =  CB D9 F4 12 68 07 E4 05  CC 2D 27 12 1D F5 E8 6E 
======================================================================



	Kent's 10-Step Procedure to Compiling a Debian Kernel
		  Kent West <westk@nicanor.acu.edu>

(I may leave a step or two out, but this is the gist. This example
uses the latest kernel version at the time of writing, which was
2.4.18)

1. Run "dselect". Choose "Update". Choose "Select". "space bar" to get
   out of the Help screens. Use "/" (without the quotes) to start
   search.  Search for "kernel-source". Mark for installation the
   2.4.18 or so.

1b. Use "/" to search for "kernel-package". Mark it for installation 
    also. "Enter" to get back to the main dselect menu.

1c. Choose "Install". This will download a file in /usr/src with a .tgz 
    extension, as well as install "kernel-package".

2. "cd /usr/local/src"

3. "bunzip2 /usr/src/kernel-source-2.4.18.tar.bz2" (or whatever the file is 
   named). This will unzip (decompress) the file.

4. "tar -xvf kernel-source-2.4.18.tar". This will untar the file (x
   means extract, v means "be verbose", f means "use the file named
   ...").  A new subdirectory named kernel-source-2.4.18 will be
   created with all the untarred files under it. You can also do steps
   3 and 4 in one tar command, but I never do; habit is the only
   reason. I think you just add the "j" switch to tar, such as "tar
   -xvjf 'filename'". (It used to be the I switch to tar, but they
   moved from I to j).


Pause and Breathe. You now have the kernel sources installed. You 
haven't done anything with them yet, but they're installed.

5. "cd /usr/local/src/kernel-source-2.4.18" 

6. "make menuconfig". This will start a curses-based (text-based) 
     menu-driven application. There are a lot of choices here, and
     many of them won't make sense to you at all. Take the time to
     look at most all of them (some of them you'll know you don't
     need, like SCSI support if you have an all-IDE system, or Amateur
     Radio Support if you're not a ham) and read the HELP on them if
     they look relevant. A lot of the time the HELP will suggest
     whether you should include it or not, and generally when in
     doubt, leave things set the way they are. Some things to check
     out:
       * the correct processor for your system (AMD vs Pentium vs P4, etc)
       * Symmetric Multi-Processing; "No" if you only have a single processor
       * Loadable module support; "Yes" to all three sub-items.
       * Parallel port support; "Yes" if you have a parallel
         printer. "No" to keep things simple for now if you can live
         without the printer for a while. 
       * Plug-N-Play; "Yes"; ISA P-N-P; only if you have any ISA cards
         installed. 
       * Character devices; turn on Direct Rendering if your video card is 
         listed, and turn on agpgart if your video chipset is listed;
         mice if you  have a PS/2 mouse
       * Sound - find the driver for your card
       * Input core support (some USB stuff needs this, but I'm hazy
         on it - use your best guess) 
       * USB support (make your best guesses; I'm hazy on it)
       * You probably won't need to touch the following:
              - General Setup
              - Memory Technology
              - Block devices
              - Multi-device support
              - Networking options
              - Telephony support
              - ATA/IDE/MFM/RLL support
              - Fusion MPT device support
              - I20 device support
              - Amateur Radio support
              - Infrared support
              - ISDN subsystem
              - Old CD-ROM drivers (unless you have a non-ATAPI CD-ROM
                drive for now; wait till you've compiled a kernel or
                two) 
              - Multimedia devices (unless you have a tv tuner, etc;
                too complicated for now; wait) 
              - File Systems (unless you'll be accessing a
                DOS/FAT/NTFS/etc partition, or Windows shares via smb,
                etc) 
              - Console Drivers (play with different text modes at bootup)
              - kernel hacking

     It's by turning off unneeded stuff that the hackers get their kernels 
     down in size and up in efficiency. But you're not really worried about 
     either at this point.

6b. Exit and save your configuration. This will create a hidden file
    named ".config" in the "/usr/local/src/kernel-source-2.4.18"
    directory. You could edit this file directly to make changes to
    your configuration, but I wouldn't. All that this step (6 and 6b))
    has done is to set up this configuration file. This file is read
    by the actual kernel compilation process to compile the options
    you've specified.


Pause and breathe again. You have now configured your options for the 
next kernel compilation, but you have not yet compiled it.


7. Compile the kernel: use the command "make-kpkg clean; make-kpkg
   kernel_image". This will cause a bunch of grinding and text;
   depending on the speed of your computer and the options you chose,
   this could take minutes (fast computer) to hours (slow
   computer). This step is a Debian-way of compiling the kernel. The
   "other" way is to do it manually, which consists of several steps
   such as "make dep" and "make modules" and "make
   modules_install". The Debian-way is much easier. The result will be
   a file named something like
   "kernel-image-2.4.18_2.4.18-10.00.Custom_i386.deb", one level up,
   in "/usr/local/src".

   You can try reading the documentation in the "kernel-package"
   package.  A more complicated command line to build your kernel
   image, with all kinds of bells and whistles, is:

   make-kpkg clean   
   make-kpkg -rootcmd fakeroot --append-to-version -custom.${VER} \
        --revision custom.${VER} kernel_image modules-image
   This one also builds any stand-alone modules packages you may have
   installed on your machine.


Pause and breathe. You have now compiled your kernel and made a .deb 
file out of it for easy installation.


If you're (re)compiling a kernel with the same version number as your
current version, you'll probably want to run the command "mv
/lib/modules/2.[whateverversion] /lib/modules/2.[whateverversion].old"
to move the old modules out of the way in preparation for the creation
of new modules. If you forget, then step 8 shall warn you that you
need to do this before it overwrites the old modules, and you can just
open a new terminal and do it then without canceling whichever step it
concerns. This is only applicable when (re)compiling the same version
number of kernel as your existing version.

8. Install the new .deb file. Use the command "dpkg -i
   /usr/local/src/kernel-image-2.14.18*.deb". This will install the
   new kernel to where it needs to be (and I believe configure
   /etc/lilo.conf if [and only if] /etc/lilo.conf does not exist) and
   run lilo.


Pause and breathe. You are ready for a reboot to start running your new 
kernel. Make sure you have a backup method for getting into your box (a 
Debian install CD, or boot floppy, etc) in case something goes
wrong. I generally have a lilo.conf file that includes at least one
other image than /vmlinuz and /vmlinuz.old


9. Reboot. After the reboot, you should be running the new kernel.
   Typing "uname -a" will tell you what version of kernel you are
   running.  Test the machine and see if things work properly.


Pause, breathe, celebrate. You've successfully compiled and installed 
your first kernel! You may not have a working sound card or USB stuff 
yet, and other things may have broken, but now that you know the basic 
procedure you can go back and try again.

10: Celebrate.


Have fun!

Kent