From dan@ducky.nz.freebsd.org  Fri Jan  5 01:07:24 2001
Return-Path: <dan@ducky.nz.freebsd.org>
Received: from ducky.nz.freebsd.org (ns1.unixathome.org [203.79.82.27])
	by hub.freebsd.org (Postfix) with ESMTP id 0FB9237B400
	for <FreeBSD-gnats-submit@freebsd.org>; Fri,  5 Jan 2001 01:07:23 -0800 (PST)
Received: (from dan@localhost)
	by ducky.nz.freebsd.org (8.9.3/8.9.3) id WAA03449;
	Fri, 5 Jan 2001 22:07:19 +1300 (NZDT)
Message-Id: <200101050907.WAA03449@ducky.nz.freebsd.org>
Date: Fri, 5 Jan 2001 22:07:19 +1300 (NZDT)
From: dan@freebsddiary.org
Sender: dan@ducky.nz.freebsd.org
Reply-To: dan@freebsddiary.org
To: FreeBSD-gnats-submit@freebsd.org
Subject: change layout and content of kernel building so it's easier to understand
X-Send-Pr-Version: 3.2

>Number:         24083
>Category:       docs
>Synopsis:       change layout and content of kernel building so it's easier to understand
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          sw-bug
>Submitter-Id:   current-users
>Arrival-Date:   Fri Jan 05 01:10:00 PST 2001
>Closed-Date:    Mon Jun 4 10:22:24 MDT 2001
>Last-Modified:  Mon Jun 04 10:23:14 MDT 2001
>Originator:     
>Release:        
>Organization:
>Environment:
>Description:
 Submitter-Id:   current-users
 Originator:     Dan Langille
 Organization:   The FreeBSD Diary
 Confidential:   no
 Synopsis:       We've seen a great deal of confused kernel builders over the past week.  This should fix that.
 Severity:       non-critical
 Priority:       low
 Category:       docs
 Release:        FreeBSD 4.1-STABLE i386
 Class:          change-request
 Environment: 
 
 
 Description: 
 
 People are getting confused over kernel building.  They are using buildkernel when 
 they should be using config -r MYKERNEL.  Hopefully the addition of sub-sections
 and slightly more detail will fix this.
 
 I admit to not building the HTML 
 
 How-To-Repeat: 
 
 
 Fix: 
 
 
 --- chapter.sgml.original	Fri Jan  5 17:57:36 2001
 +++ chapter.sgml	Fri Jan  5 19:05:48 2001
 @@ -57,7 +57,15 @@
  
    <sect1 id="kernelconfig-building">
      <title>Building and Installing a Custom Kernel</title>
 +    <para>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.</para>
  
 +  <sect1 id="kernelconfig-building">
 +    <title>Directory structure</title>
      <para>First, let us take a quick tour of the kernel build directory.
        All directories mentioned will be relative to the main
        <filename>/usr/src/sys</filename> directory, which is also
 @@ -77,17 +85,30 @@
        directory structure, with each supported device, filesystem, and
        option in its own subdirectory.</para>
  
 -    <note>
 -      <para>If there is <emphasis>not</emphasis> a
 -	<filename>/usr/src/sys</filename> directory on your system, then
 -	the kernel source has not been been installed.  The easiest way to
 -	do this is by running <command>/stand/sysinstall</command> as
 -	<username>root</username>, choosing <literal>Configure</literal>,
 -	then <literal>Distributions</literal>, then
 -	<literal>src</literal>, then <literal>sys</literal>.</para>
 -    </note>
 -
 -    <para>Next, move to the
 +  <sect1 id="kernelconfig-building">
 +   <title>Obtaining the kernel source</title>
 +   <para>If there is <emphasis>not</emphasis> a
 +     <filename>/usr/src/sys</filename> directory on your system, then
 +     the kernel source has not been been installed.  The easiest way to
 +     do this is by running <command>/stand/sysinstall</command> as
 +     <username>root</username>, choosing <literal>Configure</literal>,
 +     then <literal>Distributions</literal>, then
 +     <literal>src</literal>, then <literal>sys</literal>.</para>
 +
 +  <sect1 id="kernelconfig-building">
 +   <title>Modifying the kernel configuration file</title>
 +   <para>The installed kernel sources include the configuration file for 
 +     the GENERIC kernel. This file is named, oddly enough,  
 +     <filename>GENERIC</filename>. 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
 +     <filename>GENERIC</filename>, this file should not be modified.</para>
 +
 +   <para>The first step is configuring your kernel is the creation of your
 +     kernel configuration file. We will use <filename>GENERIC</filename>
 +     as the starting point. Move to the
        <filename><replaceable>arch</replaceable>/conf</filename> directory
        and copy the <filename>GENERIC</filename> configuration file to the
        name you want to give your kernel.  For example:</para>
 @@ -95,7 +116,7 @@
      <screen>&prompt.root; <userinput>cd /usr/src/sys/i386/conf</userinput>
  &prompt.root; <userinput>cp GENERIC MYKERNEL</userinput></screen>
  
 -    <para>Traditionally, this name is in all capital letters and, if you
 +    <para>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 <filename>MYKERNEL</filename> for the purpose of this
 @@ -138,12 +159,14 @@
          for those information than the handbook.</para>
      </note>
  
 -    <para>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
 -      <filename>/usr/src/</filename> directory only contains the
 -      <filename>sys/</filename> sub-directory.</para>
 +  <sect1 id="kernelconfig-building">
 +    <title>Compiling your kernel</title>
 +    <para>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.</para>
  
      <note>
        <para>If you are trying to upgrade your kernel from an older version
 @@ -160,6 +183,8 @@
  &prompt.root; <userinput>make</userinput>
  &prompt.root; <userinput>make install</userinput></screen>
  
 +  <sect1 id="kernelconfig-building">
 +    <title>Alternative compilation instructions</title>
      <para>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 <link
 @@ -173,9 +198,10 @@
      <para>If you have <emphasis>not</emphasis> upgraded your source
        tree in any way (you have not run <application>CVSup</application>, 
        <application>CTM</application>, or used 
 -      <application>anoncvs</application>), then you should use the 
 -      <command>config</command>, <command>make depend</command>, 
 -      <command>make</command>, <command>make install</command> sequence.</para>
 +      <application>anoncvs</application>), 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.</para>
  
      <warning>
        <para>If you have upgraded your sources since your last kernel
 @@ -188,6 +214,8 @@
  	sources!</emphasis></para>
      </warning>
      
 +  <sect1 id="kernelconfig-building">    
 +    <title>Kernel installation</title>
      <para>The new kernel will be copied to the root directory as
        <filename>/kernel</filename> and the old kernel will be moved to
        <filename>/kernel.old</filename>.  Now, shutdown the system and
 
>How-To-Repeat:
>Fix:
>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: gnats-admin->freebsd-doc 
Responsible-Changed-By: peter 
Responsible-Changed-When: Wed Jan 10 13:41:39 PST 2001 
Responsible-Changed-Why:  
Misfiled 

http://www.freebsd.org/cgi/query-pr.cgi?pr=24083 
State-Changed-From-To: open->closed 
State-Changed-By: imp 
State-Changed-When: Mon Jun 4 10:22:24 MDT 2001 
State-Changed-Why:  
Dan tells me to kill this. 


http://www.FreeBSD.org/cgi/query-pr.cgi?pr=24083 
>Unformatted:
