docs/handbook/handbook-kernelconfig-building.mdwn

   1 ## Building and Installing a Custom Kernel
   2
   3 First, let us take a quick tour of the kernel build directory. All directories mentioned will be relative to the main `/usr/src/sys` directory, which is also accessible through `/sys`. There are a number of subdirectories here representing different parts of the kernel, but the most important, for our purposes, is `config`, where you will edit your custom kernel configuration, and `compile`, which is the staging area where your kernel will be built.  Notice the logical organization of the directory structure, with each supported device, file system, and option in its own subdirectory.
   4
   5
   6
   7  **Installing the Source**  ****
   8
   9
  10
  11 If there is ***not*** a `/usr/src/sys` directory on your system, then the kernel source has not been installed. One method to do this is via cvsup.  An alternative is to install the kernel source tree from the archive distributed on the DragonFly CD named `src-sys.tar.bz2`.  This is especially useful when you do not have ready access to the internet.  See [Building Kernel From Live CD](BuildingKernelFromLiveCD) for notes on how to access and extract this archive.  When installing kernel source only, use the alternate build procedure below.
  12
  13
  14
  15  **Your Custom Config File**
  16
  17
  18
  19 Next, move to the `config` directory and copy the `GENERIC` configuration file to the name you want to give your kernel. For example:
  20
  21
  22
  23
  24
  25     # cd /usr/src/sys/config
  26
  27     # cp GENERIC MYKERNEL
  28
  29
  30
  31 Traditionally, this name is in all capital letters and, if you are maintaining multiple DragonFly machines with different hardware, it is a good idea to name it after your machine's hostname. We will call it `MYKERNEL` for the purpose of this example.
  32
  33
  34
  35  **Tip:** Storing your kernel config file directly under `/usr/src` can be a bad idea. If you are experiencing problems it can be tempting to just delete `/usr/src` and start again. Five seconds after you do that you realize that you have deleted your custom kernel config file. Do not edit `GENERIC` directly, as it may get overwritten the next time you [update your source tree](updating.html#UPDATING-SETUP), and your kernel modifications will be lost.
  36
  37
  38
  39 You might want to keep your kernel config file elsewhere, and then create a symbolic link to the file in the `config` directory.
  40
  41
  42
  43 For example:
  44
  45
  46
  47
  48
  49     # cd /usr/src/sys/config
  50
  51     # mkdir /root/kernels
  52
  53     # cp GENERIC /root/kernels/MYKERNEL
  54
  55     # ln -s /root/kernels/MYKERNEL
  56
  57
  58
  59  **Note:** You must execute these and all of the following commands under the `root` account or you will get permission denied errors.
  60
  61
  62
  63 Now, edit `MYKERNEL` with your favorite text editor. If you are just starting out, the only editor available will probably be ***vi***, which is too complex to explain here, but is covered well in many books in the [bibliography](bibliography.html). However, DragonFly does offer an easier editor called ***ee*** which, if you are a beginner, should be your editor of choice. Feel free to change the comment lines at the top to reflect your configuration or the changes you have made to differentiate it from `GENERIC`.
  64
  65
  66
  67 If you have built a kernel under SunOS™ or some other BSD operating system, much of this file will be very familiar to you. If you are coming from some other operating system such as DOS, on the other hand, the `GENERIC` configuration file might seem overwhelming to you, so follow the descriptions in the [[Configuration File|handbook-kernelconfig-config]] section slowly and carefully.
  68
  69
  70
  71  **Building a Kernel - Full Source Tree**
  72
  73
  74
  75  ****  **Note:** Be sure to always check the file `/usr/src/UPDATING`, before you perform any update steps, in the case you [sync your source tree](updating.html#UPDATING-SETUP) with the latest sources of the DragonFly project. In this file all important issues with updating DragonFly are typed out. `/usr/src/UPDATING` always fits your version of the DragonFly source, and is therefore more accurate for new information than the handbook.
  76
  77
  78
  79  1. Change to the `/usr/src` directory.
  80
  81
  82
  83       # cd /usr/src
  84
  85
  86
  87
  88
  89  1. Compile the kernel.
  90
  91
  92
  93       # make buildkernel KERNCONF=MYKERNEL
  94
  95
  96
  97
  98
  99  1. Install the new kernel.
 100
 101
 102
 103       # make installkernel KERNCONF=MYKERNEL
 104
 105
 106
 107
 108
 109
 110
 111 If you have ***not*** upgraded your source tree in any way since the last time you successfully completed a `buildworld`-`installworld` cycle (you have not run  **CVSup** ), then it is safe to use the `quickworld` and `quickkernel`, `buildworld`, `buildkernel` sequence.
 112
 113
 114
 115  **Building a Kernel - Kernel Source Only**
 116
 117
 118
 119 When only the kernel source is installed, you need to change step 2, above, to this:
 120
 121
 122
 123
 124
 125      # make nativekernel KERNCONF=MYKERNEL
 126
 127
 128
 129
 130
 131 The other steps are the same.
 132
 133
 134
 135  **Running Your New Kernel**
 136
 137
 138
 139 The new kernel will have been copied to the boot directory as `kernel` and the old kernel will be moved to `/boot/kernel.old`, the same applies to the modules (`/boot/modules` -> `/boot/modules.old`). Now, shutdown the system and reboot to use your new kernel. In case something goes wrong, there are some [troubleshooting](kernelconfig-trouble.html) instructions at the end of this chapter. Be sure to read the section which explains how to recover in case your new kernel [does not boot](kernelconfig-trouble.html#KERNELCONFIG-NOBOOT).
 140
 141
 142
 143  **Note:** If you have added any new devices (such as sound cards), you may have to add some device nodes to your `/dev` directory before you can use them. For more information, take a look at [Making Device Nodes](kernelconfig-nodes.html) section later on in this chapter.
 144
 145
 146
 147
 148