svn commit: r40999 - head/en_US.ISO8859-1/books/handbook/kernelconfig

Tue Feb 19 05:48:04 UTC 2013

On Sun, 17 Feb 2013, Dru Lavigne wrote:

> Modified: head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml
> ==============================================================================
> --- head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml	Sun Feb 17 17:28:26 2013	(r40998)
> +++ head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml	Sun Feb 17 17:41:05 2013	(r40999)
> @@ -281,78 +261,66 @@ following line in &man.loader.conf.5;:
> 	to build the kernel.</para>
>     </note>
>
> +    <para>The kernel build is located at <filename
> +	class="directory">/usr/src/sys</filename>.  It contains a

The kernel build is at /usr/obj/usr/src/sys/.  This should probably refer 
to the kernel source.

> +      number of subdirectories representing different parts of the
> +      kernel.  These include <filename
> +	class="directory"><replaceable>arch</replaceable>/conf</filename>,
> +      which contains the kernel configuration file, and
> +      <filename class="directory">compile</filename>, which is the
> +      staging area where the kernel will be built.

Oof, this is really out of date, probably from 4.X or worse.  (The above 
is probably a symptom of the same problem.)
There is no /usr/src/sys/compile directory on modern systems, I think this 
is a legacy from manually invoking config(8).  Of course, I can't easily 
check, as Eitan has removed all of the bits from the manual for the "old" 
method of building a kernel.  The man page does seem to support this, 
though.

Probably someone should audit the hierarchy described here against a 
recent kernel build.

> +      <replaceable>arch</replaceable> contains subdirectories for each
> +      supported architecture: <filename
> +	class="directory">i386</filename>, <filename
> +	class="directory">amd64</filename>, <filename
> +	class="directory">ia64</filename>, <filename
> +	class="directory">powerpc</filename>, <filename
> +	class="directory">sparc64</filename>, and <filename
> +	class="directory">pc98</filename>.  Everything inside a
>       particular architecture's directory deals with that architecture
> -      only; the rest of the code is machine independent code common
> -      to all platforms to which &os; could potentially be ported.
> -      Notice the logical organization of the directory structure,
> -      with each supported device, file system, and option in its
> -      own subdirectory.</para>
> -
> -    <para>The examples in this chapter assume that you are using
> -      the i386 architecture.  If your system has a different
> -      architecture you need to change the path names
> -      accordingly.</para>
> +      only and the rest of the code is machine independent code common
> +      to all platforms.  Notice the logical organization of the
> +      directory structure, with each supported device, file system,
> +      and option in its own subdirectory.</para>
> +
> +    <para>The examples in this chapter assume the i386 architecture.
> +      If the system has a different architecture, change the path
> +      names accordingly.</para>

If we had infinite time, amd64 might be more representative than i386 
these days.  That said, we have better things to do with our time.

>     <note>
> -      <para>If the directory <filename>/usr/src/</filename> does not
> -	exist on your system (or if it is empty), then the sources
> -	have not been installed.  The easiest way to install the full
> -	source is to use &man.csup.1; as described in <xref
> -	linkend="synching"/>.  You should also create a symlink to
> +      <para>If <filename class="directory">/usr/src/</filename> does
> +	not exist or it is empty, source has not been installed.  The
> +	easiest way to install source is to use
> +	<application>svn</application> as described in <link
> +	  linkend="svn"></link>.  One should also create a symlink to

I don't agree with using just "source" to describe the system sources; it 
seems too ambiguous.

> 	<filename class="directory">/usr/src/sys/</filename>:</para>
>
> 	<screen>&prompt.root; <userinput>ln -s /usr/src/sys /sys</userinput></screen>
>     </note>
>
> @@ -429,52 +391,49 @@ following line in &man.loader.conf.5;:
>
>       <programlisting>MODULES_OVERRIDE = linux acpi sound/sound sound/driver/ds1 ntfs</programlisting>
>
> -      <para>This variable sets up a list of modules to build instead
> -	of all of them.</para>
> +      <para>This variable specifies the list of modules to build
> +	instead the default of building of all of them.</para>

This sentence feels a bit awkward ("the default of building of all of 
them"); I'd prefer "the list of modules to build.  The default is to build 
all modules." or something similar.

> @@ -600,37 +550,29 @@ cpu          I686_CPU</programlisting>
>
>     <programlisting>ident          GENERIC</programlisting>
>
> -    <para>This is the identification of the kernel.  You should change
> -      this to whatever you named your kernel,
> -      i.e., <literal><replaceable>MYKERNEL</replaceable></literal>
> -      if you have followed the instructions of the previous examples.
> -      The value you put in the <literal>ident</literal> string will
> -      print when you boot up the kernel, so it is useful to give the
> -      new kernel a different name if you want to keep it separate
> -      from your usual kernel (e.g., you want to build an experimental
> -      kernel).</para>
> +    <para>This is the identification of the kernel.  Change
> +      this to the new kernel name, such as
> +      <literal><replaceable>MYKERNEL</replaceable></literal>.
> +      The value in the <literal>ident</literal> string will
> +      print when the kernel boots.</para>

I prefer "be printed" to "print".

>     <!-- XXX: Add a comment here that explains when compiling hints into
>       the kernel is a good idea and why. -->
>
>     <programlisting>makeoptions     DEBUG=-g          # Build kernel with gdb(1) debug symbols</programlisting>
>
> -    <para>The normal build process of &os; includes
> -      debugging information when building the kernel with the
> -      <option>-g</option> option, which enables debugging
> -      information when passed to &man.gcc.1;.</para>
> +    <para>This option enables debugging information when passed to
> +      &man.gcc.1;.</para>

clang handles -g just fine.  Maybe we should link to cc(1) which I think 
changes between gcc and clang with WITH_CLANG_IS_CC?

>     <programlisting>options          SCHED_ULE         # ULE scheduler</programlisting>
>
> @@ -638,17 +580,14 @@ cpu          I686_CPU</programlisting>
>
>     <programlisting>options          PREEMPTION         # Enable kernel thread preemption</programlisting>
>
> -    <para>Allows threads that are in the kernel to be preempted
> -      by higher priority threads.  It helps with interactivity and
> -      allows interrupt threads to run sooner rather than
> -      waiting.</para>
> +    <para>Allows kernel threads to be preempted by higher priority
> +      threads.  This helps with interactivity and allows interrupt
> +      threads to run sooner rather than waiting.</para>
>
>     <programlisting>options          INET              # InterNETworking</programlisting>
>
> -    <para>Networking support.  Leave this in, even if you do not
> -      plan to be connected to a network.  Most programs require at
> -      least loopback networking (i.e., making network connections
> -      within your PC), so this is essentially mandatory.</para>
> +    <para>Networking support.  This is mandatory as most programs
> +      require at least loopback networking.</para>
>
>     <programlisting>options          INET6             # IPv6 communications protocols</programlisting>

bz et al may be a bit miffed that INET loopback is mandatory, given their 
work on INET6-only systems.  I don't know that there's a better way to 
phrase things than what you have, though.

> @@ -657,40 +596,38 @@ cpu          I686_CPU</programlisting>
>     <programlisting>options          FFS               # Berkeley Fast Filesystem</programlisting>
>
>     <para>This is the basic hard drive file system.  Leave it in if
> -      you boot from the hard disk.</para>
> +      the system boots from the hard disk.</para>

Probably "a hard disk", here.

>
>     <programlisting>options          SOFTUPDATES       # Enable FFS Soft Updates support</programlisting>
>
> -    <para>This option enables Soft Updates in the kernel, this will
> -      help speed up write access on the disks.  Even when this
> +    <para>This option enables Soft Updates in the kernel which helps
> +      to speed up write access on the disks.  Even when this
>       functionality is provided by the kernel, it must be turned on
> -      for specific disks.  Review the output from &man.mount.8; to
> -      see if Soft Updates is enabled for your system disks.  If you
> -      do not see the <literal>soft-updates</literal> option then you
> -      will need to activate it using the &man.tunefs.8; (for existing
> -      file systems) or &man.newfs.8; (for new file systems)
> -      commands.</para>
> +      for specific disks.  Review the output so &man.mount.8; to

SU is per-file-system, not per disk.  I'm not sure where the bug in the 
original came from, but we can fix it here.

> +      determine if Soft Updates is enabled.  If the
> +      <literal>soft-updates</literal> option is not in the output, it
> +      can be activated using &man.tunefs.8; for existing file systems
> +      or &man.newfs.8; for new file systems.</para>
>
> @@ -709,9 +646,10 @@ cpu          I686_CPU</programlisting>
> options          NFSSERVER         # Network Filesystem Server
> options          NFS_ROOT          # NFS usable as /, requires NFSCLIENT</programlisting>
>
> -    <para>The network file system.  Unless you plan to mount
> -      partitions from a &unix; file server over TCP/IP, you can
> -      comment these out.</para>
> +    <para>The network file system (<acronym>NFS</acronym>).  These
> +      lines can be commented unless the system needs to mount
> +      partitions from a <acronym>NFS</acronym> file server over
> +      TCP/IP.</para>

NFS works just fine over UDP/IP as well.  I don't think there's need to 
include "over TCP/IP" at all.

>
>     <indexterm>
>       <primary>kernel options</primary>
> @@ -719,34 +657,32 @@ options          NFS_ROOT          # NFS
>     <programlisting>options          PROCFS            # Process filesystem (requires PSEUDOFS)</programlisting>
>
>     <para>The process file system.  This is a <quote>pretend</quote>

I think "pseudo file system" is more of the term of art.

> -      file system mounted on <filename>/proc</filename> which allows
> -      programs like &man.ps.1; to give you more information on what
> -      processes are running.  Use of <literal>PROCFS</literal>
> -      is not required under most circumstances, as most
> -      debugging and monitoring tools have been adapted to run without
> -      <literal>PROCFS</literal>: installs will not mount this file
> -      system by default.</para>
> +      file system mounted on <filename
> +	class="directory">/proc</filename> which allows some programs
> +      to provide more information on what processes are running.  Use
> +      of <literal>PROCFS</literal> is not required under most
> +      circumstances, as most debugging and monitoring tools have been
> +      adapted to run without <literal>PROCFS</literal>.  The default
> +      installation will not mount this file system by default.</para>

Two uses of "default" in the same sentence; I would probably change the 
first to "standard".

>
>     <programlisting>options          PSEUDOFS          # Pseudo-filesystem framework</programlisting>
>
> @@ -757,51 +693,49 @@ options          NFS_ROOT          # NFS
>
>     <para>Adds support for <ulink
> 	url="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID
> -      Partition Tables</ulink>.  GPT provides the ability to have a
> -      large number of partitions per disk, 128 in the standard
> -      configuration.</para>
> +	  Partition Tables</ulink> (<acronym>GPT</acronym>.  GPT

close paren?

> +	provides the ability to have a large number of partitions per
> +	disk, 128 in the standard configuration.</para>
>
[...]
>
>     <programlisting>options          SCSI_DELAY=5000  # Delay (in ms) before probing SCSI</programlisting>
>
>     <para>This causes the kernel to pause for 5 seconds before probing
> -      each SCSI device in your system.  If you only have IDE hard
> -      drives, you can ignore this, otherwise you can try to lower
> -      this number, to speed up booting.  Of course, if you do this
> -      and &os; has trouble recognizing your SCSI devices, you will
> -      have to raise it again.</para>
> +      each SCSI device in the system.  If the system only has IDE hard
> +      drives, ignore this or lower the number to speed up booting.
> +      However, if &os; has trouble recognizing the SCSI devices, the

Spurious "the"?

> +      number will have to be raised again.</para>

Maybe s/number/timeout/?

-Ben

>
> *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
>