diff --git a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml index 6e6c396cce..cd2038a24e 100644 --- a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml @@ -300,7 +300,15 @@ ath_hal(4) - Atheros Hardware Access Layer (HAL) put a # at the beginning of the line representing that device or subsystem. Do not add or remove a # for any line that you do not understand. - + + + It is easy to remove support for a device or option and + end up with a broken kernel. For example, if the &man.ata.4; + driver is removed from the kernel configuration file, a system + using ATA disk drivers may not boot. When + in doubt, just leave support in the kernel. + + In addition to the brief descriptions provided in this file, additional descriptions are contained in NOTES, which can be found in the same @@ -1163,28 +1171,9 @@ device fwe # Ethernet over FireWire (non-standard!) Building and Installing a Custom Kernel - After saving the edits, compile the source code for the - kernel. - - - After syncing the source tree - with the latest sources, always read - /usr/src/UPDATING - before performing any update steps. This file describes any - important issues or areas requiring special attention within - the updated source code. - /usr/src/UPDATING always matches - the version of the &os; source and contains more up-to-date - information than this Handbook. - - - - It is easy to remove support for a device or option and - end up with a broken kernel. For example, if the &man.ata.4; - driver is removed from the kernel configuration file, a system - using ATA disk drivers may not boot. When - in doubt, just leave support in the kernel. - + Once the edits to the custom configuration file have been + saved, the source code for the + kernel can be compiled using the following steps: Building a Kernel @@ -1193,13 +1182,8 @@ device fwe # Ethernet over FireWire (non-standard!)building / installing - - It is required to have the full &os; source tree - installed to build the kernel. - - - cd to /usr/src: + Change to this directory: &prompt.root; cd /usr/src @@ -1208,100 +1192,88 @@ device fwe # Ethernet over FireWire (non-standard!)Compile the new kernel by specifying the name of the custom kernel configuration file: - &prompt.root; make buildkernel KERNCONF=MYKERNEL + &prompt.root; make buildkernel KERNCONF=MYKERNEL - Install the new kernel: + Install the new kernel associated with the specified + kernel configuration file. This command will copy the new kernel to + /boot/kernel/kernel and save the old kernel + to /boot/kernel.old/kernel: - &prompt.root; make installkernel KERNCONF=MYKERNEL + &prompt.root; make installkernel KERNCONF=MYKERNEL + + + + Shutdown the system and reboot into the new kernel. + If something goes wrong, refer to . - By default, when a custom kernel is compiled, - all kernel modules are rebuilt as well. + all kernel modules are rebuilt. To update a kernel faster or to build only custom modules, edit /etc/make.conf before starting to - build the kernel: + build the kernel. - MODULES_OVERRIDE = linux acpi sound/sound sound/driver/ds1 ntfs + For example, this variable specifies the list of modules to build + instead of using the default of building all modules: - This variable specifies the list of modules to build - instead the default of building of all of them. + MODULES_OVERRIDE = linux acpi ntfs + + Alternately, this variable lists which modules to + exclude from the build process: WITHOUT_MODULES = linux acpi sound ntfs - This variable sets up a list of top level modules to - exclude from the build process. For other available - variables, refer to &man.make.conf.5;. - + Additional variables are available. + Refer to &man.make.conf.5; for details. /boot/kernel.old - - The new kernel will be copied to /boot/kernel as - /boot/kernel/kernel and the old kernel - will be moved to /boot/kernel.old/kernel. - Now, shutdown the system and reboot into the new kernel. - If something goes wrong, refer to the troubleshooting - instructions and the section which explains how to - recover when the new kernel does not boot. - - - Other files relating to the boot process, such as the boot - &man.loader.8; and configuration, are stored in /boot. Third party or - custom modules can be placed in /boot/kernel, although users - should be aware that keeping modules in sync with the compiled - kernel is very important. Modules not intended to run with - the compiled kernel may result in instability. - If Something Goes Wrong There are four categories of trouble that can occur when - building a custom kernel. They are: + building a custom kernel: - config fails: + config fails - If &man.config.8; fails, it is probably a simple - error. Fortunately, &man.config.8; will print the line - number that it had trouble with. For example, for - this message: + If config fails, it will print the line + number that is incorrect. As an example, for + the following message, make sure that line 17 is typed correctly by + comparing it to + GENERIC or NOTES: config: line 17: syntax error - - Make sure the keyword on line 17 is typed correctly by - comparing it to the - GENERIC kernel or another - reference. - make fails: + make fails - If make fails, it usually signals - an error in the kernel description which is not severe - enough for &man.config.8; to catch. Review the - configuration, and if you still cannot resolve the - problem, send an email to the &a.questions; with the - kernel configuration. + If make fails, it is usually due to + an error in the kernel configuration file which is not severe + enough for config to catch. Review the + configuration, and if the problem is not apparent, + send an email to the &a.questions; which contains the + kernel configuration file. - The kernel does not boot: + The kernel does not boot - If the new kernel does not boot, or fails to recognize + If the new kernel does not boot or fails to recognize devices, do not panic! Fortunately, &os; has an excellent mechanism for recovering from incompatible kernels. Simply choose the kernel to boot from at the &os; boot @@ -1310,9 +1282,7 @@ device fwe # Ethernet over FireWire (non-standard!) option. At the prompt, type boot kernel.old, or - the name of any other kernel that will boot properly. - When reconfiguring a kernel, it is always a good idea to - keep a kernel that is known to work on hand. + the name of any other kernel that is known to boot properly. After booting with a good kernel, check over the configuration file and try to build it again. One helpful @@ -1323,16 +1293,14 @@ device fwe # Ethernet over FireWire (non-standard!) When troubleshooting a kernel, make sure to keep - GENERIC, or some other kernel that - is known to work, on hand as a different name that will - not get erased on the next build. Do not rely on - kernel.old because when installing - a new kernel, kernel.old is - overwritten with the last installed kernel which may - be non-functional. As soon as possible, move the - working kernel to the proper /boot/kernel - location or commands such as &man.ps.1; may not work - properly. To do this, simply rename the directory + a copy of GENERIC, or some other kernel that + is known to work, as a different name that will + not get erased on the next build. This is important + because every time + a new kernel is installed, kernel.old is + overwritten with the last installed kernel, which may or + may not be bootable. As soon as possible, move the + working kernel by renaming the directory containing the good kernel: &prompt.root; mv /boot/kernel /boot/kernel.bad @@ -1343,18 +1311,17 @@ device fwe # Ethernet over FireWire (non-standard!) - The kernel works, but &man.ps.1; does not work - any more: + The kernel works, but &man.ps.1; does not If the kernel version differs from the one that the system utilities have been built with, for example, a - -CURRENT kernel on a -RELEASE, many system status commands + kernel built from -CURRENT sources is installed on a -RELEASE system, many system status commands like &man.ps.1; and &man.vmstat.8; will not work. To fix this, recompile and install a world built with the same version of the - source tree as the kernel. This is one reason why it is - not a good idea to use a different version of the kernel + source tree as the kernel. It is + never a good idea to use a different version of the kernel than the rest of the operating system.