os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Make this a bit more up to date WRT accepted practice. Could still use some

Browse source 
more re-working though.
This commit is contained in:
Nik Clayton 2001-04-12 07:34:04 +00:00
parent bbe8a1a229
commit b545dba68e
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=9177
2 changed files with 184 additions and 192 deletions
Download patch file Download diff file Expand all files Collapse all files

188
en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml
View file

@ -1,7 +1,7 @@
<!--
The FreeBSD Documentation Project
$FreeBSD: doc/en_US.ISO_8859-1/books/handbook/cutting-edge/chapter.sgml,v 1.60 2001/03/17 01:58:42 dd Exp $
$FreeBSD: doc/en_US.ISO_8859-1/books/handbook/cutting-edge/chapter.sgml,v 1.61 2001/04/09 00:33:49 dd Exp $
-->
<chapter id="cutting-edge">
@ -605,8 +605,8 @@ ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupit.tgz</userinput></scr
</tip>
</sect2>
<sect2>
<title/Drop to single user mode/
<sect2 id="makeworld-singleuser">
<title>Drop to single user mode</title>
<para>You may want to compile the system in single user mode. Apart
from the obvious benefit of making things go slightly faster,
@ -662,7 +662,7 @@ ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupit.tgz</userinput></scr
possibly save yourself some dependency headaches by removing this
directory as well.</para>
<para>Some files below <filename>/usr/obj</filename> will have the
<para>Some files below <filename>/usr/obj</filename> may have the
immutable flag set (see &man.chflags.1; for more information)
which must be removed first.</para>
@ -672,7 +672,7 @@ ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupit.tgz</userinput></scr
</sect2>
<sect2>
<title/Recompile the source and install the new system/
<title>Recompile the source</title>
<sect3>
<title>All versions</title>
@ -776,6 +776,8 @@ Script done, &hellip;</screen>
<para>Use it like this:</para>
<screen>&prompt.root; <userinput>make world</userinput></screen>
<para>This will also install the new system binaries.</para>
</sect3>
<sect3>
@ -798,7 +800,7 @@ Script done, &hellip;</screen>
system will be affected. The build is <quote>self hosted</quote>.
Because of this, you can safely run
<maketarget>buildworld</maketarget> on a machine running in
multi-user mode with no fear of ill-effects. I still recommend you
multi-user mode with no fear of ill-effects. I still recommend you
run the <maketarget>installworld</maketarget> part in single user
mode though.</para>
@ -811,30 +813,12 @@ Script done, &hellip;</screen>
<command>make installworld</command> to install the results of
the build on B and C.</para>
<para>The <maketarget>world</maketarget> target still exists, and
you can use it exactly as shown for version 2.2.2.
<command>make world</command> runs <command>make
buildworld</command> followed by <command>make
installworld</command>.</para>
<para>Although the <maketarget>world</maketarget> target still exists,
you are strongly encouraged not to use it.</para>
<note>
<para>If you do the <command>make buildworld</command> and
<command>make installworld</command> commands separately, you
must pass the same parameters to &man.make.1; each
time.</para>
<para>Run</para>
<para>If you run:</para>
<screen>&prompt.root; <userinput>make -DNOPROFILE=true buildworld</userinput></screen>
<para>you must install the results with:</para>
<screen>&prompt.root; <userinput>make -DNOPROFILE=true installworld</userinput></screen>
<para>otherwise it would try and install profiled libraries that
had not been built during the <command>make buildworld</command>
phase.</para>
</note>
<screen>&prompt.root; <userinput>make buildworld</userinput></screen>
</sect3>
<sect3>
@ -850,10 +834,10 @@ Script done, &hellip;</screen>
<para>On a typical single-CPU machine you would run:</para>
<screen>&prompt.root; <userinput>make -j4 <replaceable>target</replaceable></userinput></screen>
<screen>&prompt.root; <userinput>make -j4 buildworld</userinput></screen>
<para>&man.make.1; will then have up to 4 processes running at any one
time. Empirical evidence posted to the mailing lists shows this
time. Empirical evidence posted to the mailing lists shows this
generally gives the best performance benefit.</para>
<para>If you have a multi-CPU machine and you are using an SMP
@ -862,18 +846,15 @@ Script done, &hellip;</screen>
<para>Be aware that (at the time of writing) this is still
experimental, and commits to the source tree may occasionally break
this feature. If the world fails to compile using this parameter
this feature. If the world fails to compile using this parameter
try again without it before you report any problems.</para>
</sect3>
<sect3>
<title>Timings</title>
<para>Assuming everything goes well you have anywhere between an hour
and a half and a day or so to wait.</para>
<para>As a general rule of thumb, a 200MHz P6 with more than 32MB of
RAM and reasonable SCSI disks will complete <command>make
RAM and reasonable SCSI disks will complete <command>make
world</command> in about an hour and a half. A 32MB P133 will
take 5 or 6 hours. Revise these figures down if your machines are
slower&hellip;</para>
@ -881,8 +862,82 @@ Script done, &hellip;</screen>
</sect2>
<sect2>
<title>Update files not updated by
<command>make world</command></title>
<title>Compile and install a new kernel</title>
<para>To take full advantage of your new system you should recompile the
kernel. This is practically a necessity, as certain memory structures
may have changed, and programs like &man.ps.1; and &man.top.1; will
fail to work until the kernel and source code versions are the
same.</para>
<para>The simplest, safest way to do this is to build and install a
kernel based on <filename>GENERIC</filename>. While
<filename>GENERIC</filename> may not have all the necessary devices
for your system, it should contain everything necessary to boot your
system back to single user mode. This is a good test that the new
system works properly. After booting from
<filename>GENERIC</filename> and verifying that your system works you
can then build a new kernel based on your normal kernel config
file.</para>
<para>If you are upgrading to FreeBSD 4.0 or above then the standard
kernel build procedure (as described in <xref linkend="kernelconfig">)
is deprecated. Instead, you should run these commands.</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make buildkernel</userinput>
&prompt.root; <userinput>make installkernel</userinput></screen>
<para>If you are upgrading to a version of FreeBSD below 4.0 you should
use the standard kernel build procedure. However, it is recommended
that you use the new version of &man.config.8;, using a command line
like this.</para>
<screen>&prompt.root; <userinput>/usr/obj/usr/src/usr.sbin/config/config <replaceable>KERNELNAME</replaceable></userinput></screen>
</sect2>
<sect2>
<title>Reboot in to single user mode</title>
<para>You should reboot in to single user mode to test the new kernel
works. Do this by following the instructions in
<xref linkend="makeworld-singleuser">.</para>
</sect2>
<sect2>
<title>Install the new system binaries</title>
<para>If you were building a version of FreeBSD recent enough to have
used <command>make buildworld</command> then you should now use the
<maketarget>installworld</maketarget> to install the new system
binaries.</para>
<para>Run</para>
<screen>&prompt.root; <userinput>make installworld</userinput></screen>
<note>
<para>If you specified variables on the <command>make
buildworld</command> command line, you must specify the same
variables in the <command>make installworld</command> command
line.</para>
<para>For example, if you ran:</para>
<screen>&prompt.root; <userinput>make -DNOPROFILE=true buildworld</userinput></screen>
<para>you must install the results with:</para>
<screen>&prompt.root; <userinput>make -DNOPROFILE=true installworld</userinput></screen>
<para>otherwise it would try and install profiled libraries that
had not been built during the <command>make buildworld</command>
phase.</para>
</note>
</sect2>
<sect2>
<title>Update files not updated by <command>make world</command></title>
<para>Remaking the world will not update certain directories (in
particular, <filename>/etc</filename>, <filename>/var</filename> and
@ -1143,65 +1198,6 @@ Script done, &hellip;</screen>
</note>
</sect2>
<sect2>
<title>Compile and install a new kernel</title>
<para>To take full advantage of your new system you should recompile the
kernel. This is practically a necessity, as certain memory structures
may have changed, and programs like &man.ps.1; and &man.top.1; will
fail to work until the kernel and source code versions are the
same.</para>
<para>Follow the handbook instructions for compiling a new kernel. If
you have previously built a custom kernel then carefully examine the
<filename>LINT</filename> config file to see if there are any new
options which you should take advantage of.</para>
<para>A previous version of this document suggested rebooting before
rebuilding the kernel. This is wrong because:</para>
<itemizedlist>
<listitem>
<para>Commands like &man.ps.1;, &man.ifconfig.8;, and &man.sysctl.8;
may fail. This could leave your machine unable to connect to the
network.</para>
</listitem>
<listitem>
<para>Basic utilities like &man.mount.8; could fail,
making it impossible to mount <filename>/</filename>,
<filename>/usr</filename> and so on. This is unlikely if you are
tracking a -STABLE candidate, but more likely if you are tracking
-CURRENT during a large merge.</para>
</listitem>
<listitem>
<para>Loadable kernel modules (LKMs on pre-3.X systems, KLDs on 3.X
systems and above) built as part of the <quote>world</quote> may
crash an older kernel.</para>
</listitem>
</itemizedlist>
<para>For these reasons, it is always best to rebuild and install a
new kernel before rebooting.</para>
<para>You should build your new kernel after you have completed
<userinput>make world</userinput> (or <userinput>make
installworld</userinput>). If you do not want to do this (perhaps
you want to confirm that the kernel builds before updating your
system) you may have problems. These may be because your
&man.config.8; command is out of date with respect to your kernel
sources.</para>
<para>In this case you could build your kernel with the new version of &man.config.8;</para>
<screen>&prompt.root; <userinput>/usr/obj/usr/src/usr.sbin/config/config <replaceable>KERNELNAME</replaceable></userinput></screen>
<para>This may not work in all cases. It is recommended that you
complete <userinput>make world</userinput> (or <userinput>make
installworld</userinput>) before compiling a new kernel.</para>
</sect2>
<sect2>
<title/Rebooting/

188
en_US.ISO_8859-1/books/handbook/cutting-edge/chapter.sgml
View file

@ -1,7 +1,7 @@
<!--
The FreeBSD Documentation Project
$FreeBSD: doc/en_US.ISO_8859-1/books/handbook/cutting-edge/chapter.sgml,v 1.60 2001/03/17 01:58:42 dd Exp $
$FreeBSD: doc/en_US.ISO_8859-1/books/handbook/cutting-edge/chapter.sgml,v 1.61 2001/04/09 00:33:49 dd Exp $
-->
<chapter id="cutting-edge">
@ -605,8 +605,8 @@ ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupit.tgz</userinput></scr
</tip>
</sect2>
<sect2>
<title/Drop to single user mode/
<sect2 id="makeworld-singleuser">
<title>Drop to single user mode</title>
<para>You may want to compile the system in single user mode. Apart
from the obvious benefit of making things go slightly faster,
@ -662,7 +662,7 @@ ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupit.tgz</userinput></scr
possibly save yourself some dependency headaches by removing this
directory as well.</para>
<para>Some files below <filename>/usr/obj</filename> will have the
<para>Some files below <filename>/usr/obj</filename> may have the
immutable flag set (see &man.chflags.1; for more information)
which must be removed first.</para>
@ -672,7 +672,7 @@ ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupit.tgz</userinput></scr
</sect2>
<sect2>
<title/Recompile the source and install the new system/
<title>Recompile the source</title>
<sect3>
<title>All versions</title>
@ -776,6 +776,8 @@ Script done, &hellip;</screen>
<para>Use it like this:</para>
<screen>&prompt.root; <userinput>make world</userinput></screen>
<para>This will also install the new system binaries.</para>
</sect3>
<sect3>
@ -798,7 +800,7 @@ Script done, &hellip;</screen>
system will be affected. The build is <quote>self hosted</quote>.
Because of this, you can safely run
<maketarget>buildworld</maketarget> on a machine running in
multi-user mode with no fear of ill-effects. I still recommend you
multi-user mode with no fear of ill-effects. I still recommend you
run the <maketarget>installworld</maketarget> part in single user
mode though.</para>
@ -811,30 +813,12 @@ Script done, &hellip;</screen>
<command>make installworld</command> to install the results of
the build on B and C.</para>
<para>The <maketarget>world</maketarget> target still exists, and
you can use it exactly as shown for version 2.2.2.
<command>make world</command> runs <command>make
buildworld</command> followed by <command>make
installworld</command>.</para>
<para>Although the <maketarget>world</maketarget> target still exists,
you are strongly encouraged not to use it.</para>
<note>
<para>If you do the <command>make buildworld</command> and
<command>make installworld</command> commands separately, you
must pass the same parameters to &man.make.1; each
time.</para>
<para>Run</para>
<para>If you run:</para>
<screen>&prompt.root; <userinput>make -DNOPROFILE=true buildworld</userinput></screen>
<para>you must install the results with:</para>
<screen>&prompt.root; <userinput>make -DNOPROFILE=true installworld</userinput></screen>
<para>otherwise it would try and install profiled libraries that
had not been built during the <command>make buildworld</command>
phase.</para>
</note>
<screen>&prompt.root; <userinput>make buildworld</userinput></screen>
</sect3>
<sect3>
@ -850,10 +834,10 @@ Script done, &hellip;</screen>
<para>On a typical single-CPU machine you would run:</para>
<screen>&prompt.root; <userinput>make -j4 <replaceable>target</replaceable></userinput></screen>
<screen>&prompt.root; <userinput>make -j4 buildworld</userinput></screen>
<para>&man.make.1; will then have up to 4 processes running at any one
time. Empirical evidence posted to the mailing lists shows this
time. Empirical evidence posted to the mailing lists shows this
generally gives the best performance benefit.</para>
<para>If you have a multi-CPU machine and you are using an SMP
@ -862,18 +846,15 @@ Script done, &hellip;</screen>
<para>Be aware that (at the time of writing) this is still
experimental, and commits to the source tree may occasionally break
this feature. If the world fails to compile using this parameter
this feature. If the world fails to compile using this parameter
try again without it before you report any problems.</para>
</sect3>
<sect3>
<title>Timings</title>
<para>Assuming everything goes well you have anywhere between an hour
and a half and a day or so to wait.</para>
<para>As a general rule of thumb, a 200MHz P6 with more than 32MB of
RAM and reasonable SCSI disks will complete <command>make
RAM and reasonable SCSI disks will complete <command>make
world</command> in about an hour and a half. A 32MB P133 will
take 5 or 6 hours. Revise these figures down if your machines are
slower&hellip;</para>
@ -881,8 +862,82 @@ Script done, &hellip;</screen>
</sect2>
<sect2>
<title>Update files not updated by
<command>make world</command></title>
<title>Compile and install a new kernel</title>
<para>To take full advantage of your new system you should recompile the
kernel. This is practically a necessity, as certain memory structures
may have changed, and programs like &man.ps.1; and &man.top.1; will
fail to work until the kernel and source code versions are the
same.</para>
<para>The simplest, safest way to do this is to build and install a
kernel based on <filename>GENERIC</filename>. While
<filename>GENERIC</filename> may not have all the necessary devices
for your system, it should contain everything necessary to boot your
system back to single user mode. This is a good test that the new
system works properly. After booting from
<filename>GENERIC</filename> and verifying that your system works you
can then build a new kernel based on your normal kernel config
file.</para>
<para>If you are upgrading to FreeBSD 4.0 or above then the standard
kernel build procedure (as described in <xref linkend="kernelconfig">)
is deprecated. Instead, you should run these commands.</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make buildkernel</userinput>
&prompt.root; <userinput>make installkernel</userinput></screen>
<para>If you are upgrading to a version of FreeBSD below 4.0 you should
use the standard kernel build procedure. However, it is recommended
that you use the new version of &man.config.8;, using a command line
like this.</para>
<screen>&prompt.root; <userinput>/usr/obj/usr/src/usr.sbin/config/config <replaceable>KERNELNAME</replaceable></userinput></screen>
</sect2>
<sect2>
<title>Reboot in to single user mode</title>
<para>You should reboot in to single user mode to test the new kernel
works. Do this by following the instructions in
<xref linkend="makeworld-singleuser">.</para>
</sect2>
<sect2>
<title>Install the new system binaries</title>
<para>If you were building a version of FreeBSD recent enough to have
used <command>make buildworld</command> then you should now use the
<maketarget>installworld</maketarget> to install the new system
binaries.</para>
<para>Run</para>
<screen>&prompt.root; <userinput>make installworld</userinput></screen>
<note>
<para>If you specified variables on the <command>make
buildworld</command> command line, you must specify the same
variables in the <command>make installworld</command> command
line.</para>
<para>For example, if you ran:</para>
<screen>&prompt.root; <userinput>make -DNOPROFILE=true buildworld</userinput></screen>
<para>you must install the results with:</para>
<screen>&prompt.root; <userinput>make -DNOPROFILE=true installworld</userinput></screen>
<para>otherwise it would try and install profiled libraries that
had not been built during the <command>make buildworld</command>
phase.</para>
</note>
</sect2>
<sect2>
<title>Update files not updated by <command>make world</command></title>
<para>Remaking the world will not update certain directories (in
particular, <filename>/etc</filename>, <filename>/var</filename> and
@ -1143,65 +1198,6 @@ Script done, &hellip;</screen>
</note>
</sect2>
<sect2>
<title>Compile and install a new kernel</title>
<para>To take full advantage of your new system you should recompile the
kernel. This is practically a necessity, as certain memory structures
may have changed, and programs like &man.ps.1; and &man.top.1; will
fail to work until the kernel and source code versions are the
same.</para>
<para>Follow the handbook instructions for compiling a new kernel. If
you have previously built a custom kernel then carefully examine the
<filename>LINT</filename> config file to see if there are any new
options which you should take advantage of.</para>
<para>A previous version of this document suggested rebooting before
rebuilding the kernel. This is wrong because:</para>
<itemizedlist>
<listitem>
<para>Commands like &man.ps.1;, &man.ifconfig.8;, and &man.sysctl.8;
may fail. This could leave your machine unable to connect to the
network.</para>
</listitem>
<listitem>
<para>Basic utilities like &man.mount.8; could fail,
making it impossible to mount <filename>/</filename>,
<filename>/usr</filename> and so on. This is unlikely if you are
tracking a -STABLE candidate, but more likely if you are tracking
-CURRENT during a large merge.</para>
</listitem>
<listitem>
<para>Loadable kernel modules (LKMs on pre-3.X systems, KLDs on 3.X
systems and above) built as part of the <quote>world</quote> may
crash an older kernel.</para>
</listitem>
</itemizedlist>
<para>For these reasons, it is always best to rebuild and install a
new kernel before rebooting.</para>
<para>You should build your new kernel after you have completed
<userinput>make world</userinput> (or <userinput>make
installworld</userinput>). If you do not want to do this (perhaps
you want to confirm that the kernel builds before updating your
system) you may have problems. These may be because your
&man.config.8; command is out of date with respect to your kernel
sources.</para>
<para>In this case you could build your kernel with the new version of &man.config.8;</para>
<screen>&prompt.root; <userinput>/usr/obj/usr/src/usr.sbin/config/config <replaceable>KERNELNAME</replaceable></userinput></screen>
<para>This may not work in all cases. It is recommended that you
complete <userinput>make world</userinput> (or <userinput>make
installworld</userinput>) before compiling a new kernel.</para>
</sect2>
<sect2>
<title/Rebooting/