From owner-freebsd-doc Mon Jan 8 2:50:45 2001 Delivered-To: freebsd-doc@freebsd.org Received: from freefall.freebsd.org (freefall.FreeBSD.org [216.136.204.21]) by hub.freebsd.org (Postfix) with ESMTP id 8A49C37B6AD for ; Mon, 8 Jan 2001 02:50:03 -0800 (PST) Received: (from gnats@localhost) by freefall.freebsd.org (8.11.1/8.11.1) id f08Ao3k08092; Mon, 8 Jan 2001 02:50:03 -0800 (PST) (envelope-from gnats) Received: from xeon.unixathome.org (ns1.unixathome.org [203.79.82.27]) by hub.freebsd.org (Postfix) with ESMTP id 8C2A637B6A7 for ; Mon, 8 Jan 2001 02:43:57 -0800 (PST) Received: (from dan@localhost) by xeon.unixathome.org (8.11.1/8.11.1) id f08AigF48967; Mon, 8 Jan 2001 23:44:42 +1300 (NZDT) (envelope-from dan) Message-Id: <200101081044.f08AigF48967@xeon.unixathome.org> Date: Mon, 8 Jan 2001 23:44:42 +1300 (NZDT) From: dan@freebsddiary.org Reply-To: dan@freebsddiary.org To: FreeBSD-gnats-submit@freebsd.org X-Send-Pr-Version: 3.2 Subject: docs/24148: improve kernel building description Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org >Number: 24148 >Category: docs >Synopsis: current instructions for kernel building are not clear in some areas >Confidential: no >Severity: non-critical >Priority: low >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: doc-bug >Submitter-Id: current-users >Arrival-Date: Mon Jan 08 02:50:03 PST 2001 >Closed-Date: >Last-Modified: >Originator: Dan Langille >Release: FreeBSD 4.2-STABLE i386 >Organization: The FreeBSD Diary >Environment: >Description: We're seeing lots of people getting confused about config -r and make buildkernel. This should help. >How-To-Repeat: >Fix: Patch supplied: --- chapter.sgml.original Fri Jan 5 17:57:36 2001 +++ chapter.sgml Fri Jan 5 19:05:48 2001 @@ -57,7 +57,15 @@ Building and Installing a Custom Kernel + There are two methods for building a new kernel. Which method + you use depends on whether or not you are doing a build world. If + you don't know what a "build world" you can safely ignore that method. + If you are just modifying your kernel, then you want the standard + method. The steps for each method are quite different and will + be outlined below. + + Directory structure 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 @@ -77,17 +85,30 @@ directory structure, with each supported device, filesystem, and option in its own subdirectory. - - If there is not a - /usr/src/sys directory on your system, then - the kernel source has not been been installed. The easiest way to - do this is by running /stand/sysinstall as - root, choosing Configure, - then Distributions, then - src, then sys. - - - Next, move to the + + Obtaining the kernel source + If there is not a + /usr/src/sys directory on your system, then + the kernel source has not been been installed. The easiest way to + do this is by running /stand/sysinstall as + root, choosing Configure, + then Distributions, then + src, then sys. + + + Modifying the kernel configuration file + The installed kernel sources include the configuration file for + the GENERIC kernel. This file is named, oddly enough, + GENERIC. Do not modify this file. By convention, + the kernel configuration file name is all upper case. Also included + with the kernel source is LINT. This file contains all the + kernel configuration options which are possible. Most options have + a description of what the option is for and any dependencies. Like + GENERIC, this file should not be modified. + + The first step is configuring your kernel is the creation of your + kernel configuration file. We will use GENERIC + as the starting point. Move to the arch/conf directory and copy the GENERIC configuration file to the name you want to give your kernel. For example: @@ -95,7 +116,7 @@ &prompt.root; cd /usr/src/sys/i386/conf &prompt.root; cp GENERIC MYKERNEL - Traditionally, this name is in all capital letters and, if you + As mentioned above, this name is in all capital letters and, if you are maintaining multiple FreeBSD 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 @@ -138,12 +159,14 @@ for those information than the handbook. - When you are finished, type the following to compile and install - your kernel if you are using FreeBSD prior FreeBSD 4.0 and don't - want to upgrade to FreeBSD 4.0 or higher with this step, - or if you are using a release-version of FreeBSD and your - /usr/src/ directory only contains the - sys/ sub-directory. + + Compiling your kernel + This section contains the default kernel compilation instructions. + If you are upgrading from -RELEASE to -STABLE, using FreeBSD 4.0 or + above, then the instructions on this section are for you. If you are + using before FreeBSD 4.0 and are not upgrading to FreeBSD 4.0 or above, + then this section is for you. Otherwise you should read the instructions + from the next section to see if they apply to your situation. If you are trying to upgrade your kernel from an older version @@ -160,6 +183,8 @@ &prompt.root; make &prompt.root; make install + + Alternative compilation instructions If you have just upgraded to a newer version of 4.X or higher (ie from 3.X to 4-STABLE, or even from 4-STABLE to a later version of 4-STABLE), make sure you have If you have not upgraded your source tree in any way (you have not run CVSup, CTM, or used - anoncvs), then you should use the - config, make depend, - make, make install sequence. + anoncvs), then you should use the instructions + from the previous section. However, if all you did was install + the kernel source using cvsup, then the instructions in the previous + section should be used. If you have upgraded your sources since your last kernel @@ -188,6 +214,8 @@ sources! + + Kernel installation The new kernel will be copied to the root directory as /kernel and the old kernel will be moved to /kernel.old. Now, shutdown the system and >Release-Note: >Audit-Trail: >Unformatted: To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message