diff options
| -rw-r--r-- | en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml | 1112 |
1 files changed, 566 insertions, 546 deletions
diff --git a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml index fd89d12445..03d491446d 100644 --- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml @@ -14,20 +14,24 @@ </author> <!-- Mar 2000 --> </authorgroup> + <authorgroup> <author> <firstname>Jordan</firstname> <surname>Hubbard</surname> <contrib>Original work by </contrib> </author> + <author> <firstname>Poul-Henning</firstname> <surname>Kamp</surname> </author> + <author> <firstname>John</firstname> <surname>Polstra</surname> </author> + <author> <firstname>Nik</firstname> <surname>Clayton</surname> @@ -52,28 +56,36 @@ <para>After reading this chapter, you will know:</para> <itemizedlist> - <listitem><para>The difference between the two development - branches: &os.stable; and &os.current;.</para> + <listitem> + <para>The difference between the two development + branches: &os.stable; and &os.current;.</para> </listitem> - <listitem><para>How to keep your system up to date with + + <listitem> + <para>How to keep your system up to date with <application>CVSup</application>, <application>CVS</application>, or <application>CTM</application>.</para> </listitem> - <listitem><para>How to rebuild and reinstall the entire base - system with <command>make buildworld</command> (etc).</para> - </listitem> + <listitem> + <para>How to rebuild and reinstall the entire base + system with <command>make buildworld</command> (etc).</para> + </listitem> </itemizedlist> <para>Before reading this chapter, you should:</para> <itemizedlist> - <listitem><para>Properly set up your network connection (<xref - linkend="advanced-networking">).</para> + <listitem> + <para>Properly set up your network connection (<xref + linkend="advanced-networking">).</para> + </listitem> + + <listitem> + <para>Know how to install additional third-party + software (<xref linkend="ports">).</para> </listitem> - <listitem><para>Know how to install additional third-party - software (<xref linkend="ports">).</para></listitem> </itemizedlist> <note> @@ -85,7 +97,7 @@ with &man.csup.1;, which is now part of the base system.</para> </note> </sect1> - + <sect1 id="current-stable"> <title>&os.current; vs. &os.stable;</title> <indexterm><primary>-CURRENT</primary></indexterm> @@ -104,7 +116,7 @@ &os.current; users are expected to have a high degree of technical skill, and should be capable of solving difficult system problems on their own. If you are new to &os;, think - twice before installing it. </para> + twice before installing it.</para> <sect3> <title>What Is &os.current;?</title> @@ -193,22 +205,22 @@ <sect3> <title>Using &os.current;</title> - + <indexterm> <primary>-CURRENT</primary> <secondary>using</secondary> </indexterm> <orderedlist> <listitem> - <para>Join the &a.current.name; and the &a.svn-src-head.name; lists. This is not - just a good idea, it is <emphasis>essential</emphasis>. If - you are not on the <emphasis>&a.current.name;</emphasis> list, - you will not see the comments that people are - making about the current state of the system and thus will - probably end up stumbling over a lot of problems that others - have already found and solved. Even more importantly, you - will miss out on important bulletins which may be critical - to your system's continued health.</para> + <para>Join the &a.current.name; and the &a.svn-src-head.name; + lists. This is not just a good idea, it is + <emphasis>essential</emphasis>. If you are not on the + <emphasis>&a.current.name;</emphasis> list, you will not see + the comments that people are making about the current state of + the system and thus will probably end up stumbling over a lot + of problems that others have already found and solved. Even + more importantly, you will miss out on important bulletins + which may be critical to your system's continued health.</para> <para>The &a.svn-src-head.name; list will allow you to see the commit log entry for each change as it is made, along with @@ -227,29 +239,32 @@ site</link>. You can do this in one of two ways:</para> <orderedlist> - <indexterm> - <primary><command>cvsup</command></primary> - </indexterm> - <indexterm> - <primary><command>cron</command></primary> - </indexterm> - <indexterm> - <primary>-CURRENT</primary> + <indexterm> + <primary><command>cvsup</command></primary> + </indexterm> + <indexterm> + <primary><command>cron</command></primary> + </indexterm> + <indexterm> + <primary>-CURRENT</primary> <secondary>Syncing with <application>CVSup</application></secondary> </indexterm> <listitem> <para>Use the <link linkend="cvsup">cvsup</link> program - with the <filename>supfile</filename> named <filename>standard-supfile</filename> - available from <filename>/usr/share/examples/cvsup</filename>. - This is the most recommended - method, since it allows you to grab the entire - collection once and then only what has changed from then - on. Many people run <command>cvsup</command> from - <command>cron</command> and keep their - sources up-to-date automatically. You have to - customize the sample <filename>supfile</filename> above, and configure - <link linkend="cvsup">cvsup</link> for your environment.</para> + with the <filename>supfile</filename> named + <filename>standard-supfile</filename> + available from + <filename>/usr/share/examples/cvsup</filename>. + This is the most recommended method, since it allows you to + grab the entire collection once and then only what has + changed from then on. Many people run + <command>cvsup</command> from <command>cron</command> and + keep their sources up-to-date automatically. You have to + customize the sample <filename>supfile</filename> above, + and configure <link + linkend="cvsup">cvsup</link> for your environment.</para> + <note> <para>The sample <filename>standard-supfile</filename> is intended for tracking a specific security branch of @@ -268,22 +283,22 @@ </note> </listitem> - <indexterm> - <primary>-CURRENT</primary> + <indexterm> + <primary>-CURRENT</primary> <secondary>Syncing with CTM</secondary> </indexterm> <listitem> <para>Use the <application><link - linkend="ctm">CTM</link></application> facility. If you + linkend="ctm">CTM</link></application> facility. If you have very bad connectivity (high price connections or - only email access) <application>CTM</application> is an option. - However, it is a lot of hassle and can give you broken files. - This leads to it being rarely used, which again increases - the chance of it not working for fairly long periods of - time. We recommend using + only email access) <application>CTM</application> is an + option. However, it is a lot of hassle and can give you + broken files. This leads to it being rarely used, which + again increases the chance of it not working for fairly + long periods of time. We recommend using <application><link linkend="cvsup">CVSup</link></application> - for anybody with a 9600 bps modem or faster connection. - </para> + for anybody with a 9600 bps modem or faster + connection.</para> </listitem> </orderedlist> </listitem> @@ -296,20 +311,21 @@ to compile just a subset is almost guaranteed to get you into trouble.</para> - <indexterm> - <primary>-CURRENT</primary> - <secondary>compiling</secondary> - </indexterm> + <indexterm> + <primary>-CURRENT</primary> + <secondary>compiling</secondary> + </indexterm> <para>Before compiling &os.current;, read the <filename>Makefile</filename> in <filename>/usr/src</filename> carefully. You should at least <link - linkend="makeworld">install a new kernel and rebuild the world</link> the first time through + linkend="makeworld">install a new kernel and rebuild the + world</link> the first time through as part of the upgrading process. Reading the &a.current; - and <filename>/usr/src/UPDATING</filename> will keep you up-to-date on other bootstrapping procedures - that sometimes become necessary as we move toward the next - release.</para> + and <filename>/usr/src/UPDATING</filename> will keep you + up-to-date on other bootstrapping procedures that sometimes + become necessary as we move toward the next release.</para> </listitem> - + <listitem> <para>Be active! If you are running &os.current;, we want to know what you have to say about it, especially if you @@ -320,7 +336,7 @@ </orderedlist> </sect3> </sect2> - + <sect2 id="stable"> <title>Staying Stable with &os;</title> @@ -332,8 +348,8 @@ are made. Changes go into this branch at a different pace, and with the general assumption that they have first gone into &os.current; for testing. This is <emphasis>still</emphasis> - a development branch, however, and this means that at any given time, - the sources for &os.stable; may or may not be suitable for any + a development branch, however, and this means that at any given + time, the sources for &os.stable; may or may not be suitable for any particular purpose. It is simply another engineering development track, not a resource for end-users.</para> </sect3> @@ -342,23 +358,23 @@ <title>Who Needs &os.stable;?</title> <para>If you are interested in tracking or contributing to the - FreeBSD development process, especially as it relates to the + FreeBSD development process, especially as it relates to the next <quote>point</quote> release of FreeBSD, then you should consider following &os.stable;.</para> <para>While it is true that security fixes also go into the &os.stable; branch, you do not <emphasis>need</emphasis> to - track &os.stable; to do this. Every security advisory for + track &os.stable; to do this. Every security advisory for FreeBSD explains how to fix the problem for the releases it affects <footnote><para>That is not quite true. We can not continue to - support old releases of FreeBSD forever, although we do - support them for many years. For a complete description - of the current security policy for old releases of - FreeBSD, please see <ulink - url="&url.base;/security/">http://www.FreeBSD.org/security/</ulink>.</para> - </footnote> - , and tracking an entire development branch just + support old releases of FreeBSD forever, although we do + support them for many years. For a complete description + of the current security policy for old releases of + FreeBSD, please see <ulink + url="&url.base;/security/">http://www.FreeBSD.org/security/</ulink>.</para> + </footnote>, + and tracking an entire development branch just for security reasons is likely to bring in a lot of unwanted changes as well.</para> @@ -382,28 +398,27 @@ <sect3> <title>Using &os.stable;</title> - + <indexterm> <primary>-STABLE</primary> <secondary>using</secondary> </indexterm> <orderedlist> <listitem> - <para>Join the &a.stable.name; list. This will keep you informed of - build-dependencies that may appear in &os.stable; - or any other issues requiring - special attention. Developers will also make announcements - in this mailing list when they are contemplating some - controversial fix or update, giving the users a chance to - respond if they have any issues to raise concerning the - proposed change.</para> + <para>Join the &a.stable.name; list. This will keep you informed + of build-dependencies that may appear in &os.stable; + or any other issues requiring special attention. Developers + will also make announcements in this mailing list when they are + contemplating some controversial fix or update, giving the + users a chance to respond if they have any issues to raise + concerning the proposed change.</para> <para>Join the relevant <application>SVN</application> list for the branch you are tracking. For example, if you are tracking the 7-STABLE branch, join the &a.svn-src-stable-7.name; list. - This will allow you to view the - commit log entry for each change as it is made, along with - any pertinent information on possible side-effects.</para> + This will allow you to view the commit log entry for each + change as it is made, along with any pertinent information on + possible side-effects.</para> <para>To join these lists, or one of the others available go to &a.mailman.lists.link; and click on the list that @@ -416,9 +431,9 @@ <listitem> <para>If you are going to install a new system and want it to run monthly snapshot built from &os.stable;, please - check the <ulink url="&url.base;/snapshots/"> - Snapshots</ulink> web page for more information. - Alternatively, it is possible to + check the <ulink + url="&url.base;/snapshots/">Snapshots</ulink> web page for + more information. Alternatively, it is possible to install the most recent &os.stable; release from the <link linkend="mirrors">mirror sites</link> and follow the instructions below to upgrade your system to the @@ -437,39 +452,37 @@ <primary><command>cron</command></primary> </indexterm> <indexterm> - <primary>-STABLE</primary> + <primary>-STABLE</primary> <secondary>syncing with <application>CVSup</application></secondary> </indexterm> <listitem> <para>Use the <link linkend="cvsup">cvsup</link> program - with the <filename>supfile</filename> named <filename>stable-supfile</filename> - from the directory - <filename>/usr/share/examples/cvsup</filename>. - This is the most recommended - method, since it allows you to grab the entire - collection once and then only what has changed from then - on. Many people run <command>cvsup</command> from - <command>cron</command> to keep their - sources up-to-date automatically. You have to + with the <filename>supfile</filename> named + <filename>stable-supfile</filename> from the directory + <filename>/usr/share/examples/cvsup</filename>. + This is the most recommended method, since it allows you to + grab the entire collection once and then only what has + changed from then on. Many people run + <command>cvsup</command> from <command>cron</command> to + keep their sources up-to-date automatically. You have to customize the sample <filename>supfile</filename> above, and configure <link linkend="cvsup">cvsup</link> for your environment.</para> </listitem> <indexterm> - <primary>-STABLE</primary> + <primary>-STABLE</primary> <secondary>syncing with CTM</secondary> </indexterm> <listitem> <para>Use the <application><link - linkend="ctm">CTM</link></application> facility. If + linkend="ctm">CTM</link></application> facility. If you do not have a fast and inexpensive connection to the Internet, this is the method you should consider - using. - </para> + using.</para> </listitem> - </orderedlist> - </listitem> + </orderedlist> + </listitem> <listitem> <para>Essentially, if you need rapid on-demand access to the @@ -486,11 +499,12 @@ <para>Before compiling &os.stable;, read the <filename>Makefile</filename> in <filename>/usr/src</filename> carefully. You should at least <link - linkend="makeworld">install a new kernel and rebuild the world</link> the first time through - as part of the upgrading process. Reading the &a.stable; and <filename>/usr/src/UPDATING</filename> will - keep you up-to-date on other bootstrapping procedures that - sometimes become necessary as we move toward the next - release.</para> + linkend="makeworld">install a new kernel and rebuild the + world</link> the first time through + as part of the upgrading process. Reading the &a.stable; and + <filename>/usr/src/UPDATING</filename> will keep you up-to-date + on other bootstrapping procedures that sometimes become + necessary as we move toward the next release.</para> </listitem> </orderedlist> </sect3> @@ -499,23 +513,23 @@ <sect1 id="synching"> <title>Synchronizing Your Source</title> - + <para>There are various ways of using an Internet (or email) connection to stay up-to-date with any given area of the &os; project sources, or all areas, depending on what interests you. The primary services we offer are <link linkend="anoncvs">Anonymous CVS</link>, <link linkend="cvsup">CVSup</link>, and <link - linkend="ctm">CTM</link>.</para> + linkend="ctm">CTM</link>.</para> <warning> <para>While it is possible to update only parts of your source tree, - the only supported update procedure is to update the entire tree - and recompile both userland (i.e., all the programs that run in - user space, such as those in <filename>/bin</filename> and - <filename>/sbin</filename>) and kernel sources. Updating only part - of your source tree, only the kernel, or only userland will often - result in problems. These problems may range from compile errors - to kernel panics or data corruption.</para> + the only supported update procedure is to update the entire tree + and recompile both userland (i.e., all the programs that run in + user space, such as those in <filename>/bin</filename> and + <filename>/sbin</filename>) and kernel sources. Updating only part + of your source tree, only the kernel, or only userland will often + result in problems. These problems may range from compile errors + to kernel panics or data corruption.</para> </warning> <indexterm> @@ -526,7 +540,7 @@ <para><application>Anonymous CVS</application> and <application>CVSup</application> use the <emphasis>pull</emphasis> model of updating sources. In the case of - <application>CVSup</application> the user (or a + <application>CVSup</application> the user (or a <command>cron</command> script) invokes the <command>cvsup</command> program, and it interacts with a <command>cvsupd</command> server somewhere to bring your files @@ -536,12 +550,11 @@ of interest to you. Updates are generated on the fly by the server, according to what you have and what you want to have. <application>Anonymous CVS</application> is quite a bit more - simplistic than <application>CVSup</application> in that it is just an extension to - <application>CVS</application> which allows it to pull changes - directly from a remote CVS repository. + simplistic than <application>CVSup</application> in that it is just an + extension to <application>CVS</application> which allows it to pull + changes directly from a remote CVS repository. <application>CVSup</application> can do this far more efficiently, - but <application>Anonymous CVS</application> is easier to - use.</para> + but <application>Anonymous CVS</application> is easier to use.</para> <indexterm> <primary><application>CTM</application></primary> @@ -567,8 +580,10 @@ <application>CTM</application> will not do this, and if you wipe some portion of your source tree out (and do not have it backed up) then you will have to start from scratch (from the most recent CVS - <quote>base delta</quote>) and rebuild it all with <application>CTM</application> or, with - <application>Anonymous CVS</application>, simply delete the bad bits and resync.</para> + <quote>base delta</quote>) and rebuild it all with + <application>CTM</application> or, with + <application>Anonymous CVS</application>, simply delete the bad bits + and resync.</para> </sect1> <sect1 id="makeworld"> @@ -579,8 +594,7 @@ </indexterm> <para>Once you have synchronized your local source tree against a particular version of &os; (&os.stable;, &os.current;, and so on) - you can then use the source - tree to rebuild the system.</para> + you can then use the source tree to rebuild the system.</para> <warning> <title>Make a Backup</title> @@ -593,9 +607,8 @@ source tree render your system unbootable.</para> <para>Make sure you have taken a backup. And have a fixit floppy or - bootable CD at - hand. You will probably never have to use it, but it is better to be - safe than sorry!</para> + bootable CD at hand. You will probably never have to use it, but it + is better to be safe than sorry!</para> </warning> <warning> @@ -613,15 +626,14 @@ file systems (or worse).</para> <para>If problems like these occur, a <quote>heads up</quote> is - posted to the appropriate mailing list, explaining the nature of + posted to the appropriate mailing list, explaining the nature of the problem and which systems it affects. And an <quote>all clear</quote> announcement is posted when the problem has been solved.</para> <para>If you try to track &os.stable; or &os.current; and do - not read the &a.stable; or the - &a.current; respectively, then you are - asking for trouble.</para> + not read the &a.stable; or the &a.current; respectively, then you + are asking for trouble.</para> </warning> <warning> @@ -693,8 +705,8 @@ <important> <para>Reading <filename>UPDATING</filename> is not an acceptable - substitute for subscribing to the correct mailing list, as described - previously. The two requirements are complementary, not + substitute for subscribing to the correct mailing list, as + described previously. The two requirements are complementary, not exclusive.</para> </important> </sect2> @@ -702,12 +714,11 @@ <sect2> <title>Check <filename>/etc/make.conf</filename></title> <indexterm> - <primary><filename>make.conf</filename></primary> + <primary><filename>make.conf</filename></primary> </indexterm> <para>Examine the files - <filename>/usr/share/examples/etc/make.conf</filename> - and + <filename>/usr/share/examples/etc/make.conf</filename> and <filename>/etc/make.conf</filename>. The first contains some default defines – most of which are commented out. To make use of them when you rebuild your system from source, add @@ -720,10 +731,9 @@ <makevar>CFLAGS</makevar> and <makevar>NO_PROFILE</makevar> lines found in <filename>/usr/share/examples/etc/make.conf</filename> - to - <filename>/etc/make.conf</filename> and uncomment them.</para> + to <filename>/etc/make.conf</filename> and uncomment them.</para> - <para>Examine the other definitions (<makevar>COPTFLAGS</makevar>, + <para>Examine the other definitions (<makevar>COPTFLAGS</makevar>, <makevar>NOPORTDOCS</makevar> and so on) and decide if they are relevant to you.</para> </sect2> @@ -741,15 +751,14 @@ <filename>/etc/group</filename>.</para> <para>There have been occasions when the installation part of - <command>make installworld</command> has expected certain usernames or groups - to exist. When performing an upgrade it is likely that these - users or groups did not exist. This caused problems when upgrading. - In some cases <command>make buildworld</command> will check to see if - these users or groups exist.</para> - - <para>An example of this is when the - <username>smmsp</username> user was added. Users had the - installation process fail for them when + <command>make installworld</command> has expected certain usernames + or groups to exist. When performing an upgrade it is likely that + these users or groups did not exist. This caused problems when + upgrading. In some cases <command>make buildworld</command> will + check to see if these users or groups exist.</para> + + <para>An example of this is when the <username>smmsp</username> user + was added. Users had the installation process fail for them when &man.mtree.8; was trying to create <filename>/var/spool/clientmqueue</filename>.</para> @@ -792,9 +801,9 @@ <indexterm><primary>multi-user mode</primary></indexterm> <para>Another method is to compile the system in multi-user mode, and - then drop into single user mode for the installation. If you would - like to do it this way, simply hold off on the following steps until - the build has completed. You can postpone dropping to single user + then drop into single user mode for the installation. If you would + like to do it this way, simply hold off on the following steps until + the build has completed. You can postpone dropping to single user mode until you have to <maketarget>installkernel</maketarget> or <maketarget>installworld</maketarget>.</para> @@ -806,8 +815,8 @@ mode.</para> <para>Alternatively, reboot the system, and at the boot prompt, - select the <quote>single user</quote> option. The system will then boot - single user. At the shell prompt you should then run:</para> + select the <quote>single user</quote> option. The system will then + boot single user. At the shell prompt you should then run:</para> <screen>&prompt.root; <userinput>fsck -p</userinput> &prompt.root; <userinput>mount -u /</userinput> @@ -818,20 +827,18 @@ read/write, mounts all the other UFS file systems referenced in <filename>/etc/fstab</filename> and then turns swapping on.</para> + <note> + <para>If your CMOS clock is set to local time and not to GMT + (this is true if the output of the &man.date.1; command + does not show the correct time and zone), + you may also need to run the following command:</para> - <note> - <para>If your CMOS clock is set to local time and not to GMT - (this is true if the output of the &man.date.1; command - does not show the correct time and zone), - you may also need to run the following command:</para> -<screen>&prompt.root; <userinput>adjkerntz -i</userinput></screen> - - <para>This will make sure that your local time-zone settings - get set up correctly — without this, you may later run into some - problems. - </para> - </note> + <screen>&prompt.root; <userinput>adjkerntz -i</userinput></screen> + <para>This will make sure that your local time-zone settings + get set up correctly — without this, you may later run + into some problems.</para> + </note> </sect2> <sect2> @@ -842,8 +849,8 @@ <filename>/usr/obj</filename>. The directories shadow those under <filename>/usr/src</filename>.</para> - <para>You can speed up the <command>make buildworld</command> process, and - possibly save yourself some dependency headaches by removing this + <para>You can speed up the <command>make buildworld</command> process, + and possibly save yourself some dependency headaches by removing this directory as well.</para> <para>Some files below <filename>/usr/obj</filename> may have the @@ -874,9 +881,9 @@ when the process has finished.</para> <screen>&prompt.root; <userinput>script /var/tmp/mw.out</userinput> -Script started, output file is /var/tmp/mw.out +Script started, output file is /var/tmp/mw.out &prompt.root; <userinput>make TARGET</userinput> -<emphasis>… compile, compile, compile …</emphasis> +<emphasis>… compile, compile, compile …</emphasis> &prompt.root; <userinput>exit</userinput> Script done, …</screen> @@ -900,9 +907,9 @@ Script done, …</screen> <indexterm><primary><command>make</command></primary></indexterm> <para>To rebuild the world you use the &man.make.1; command. This - command reads instructions from the <filename>Makefile</filename>, - which describes how the programs that comprise &os; should be - rebuilt, the order in which they should be built, and so on.</para> + command reads instructions from the <filename>Makefile</filename>, + which describes how the programs that comprise &os; should be + rebuilt, the order in which they should be built, and so on.</para> <para>The general format of the command line you will type is as follows:</para> @@ -926,7 +933,7 @@ Script done, …</screen> <para>is another way of specifying that profiled libraries should not be built, and corresponds with the</para> - <programlisting>NO_PROFILE= true # Avoid compiling profiled libraries</programlisting> + <programlisting>NO_PROFILE= true # Avoid compiling profiled libraries</programlisting> <para>line in <filename>/etc/make.conf</filename>.</para> @@ -942,8 +949,8 @@ Script done, …</screen> sub-steps.</para> <para>Most of the time you will not need to pass any parameters to - &man.make.1;, and so your command like will look like - this:</para> + &man.make.1;, and so your command like will look like + this:</para> <screen>&prompt.root; <userinput>make <replaceable>target</replaceable></userinput></screen> @@ -953,26 +960,27 @@ Script done, …</screen> <para>As the names imply, <maketarget>buildworld</maketarget> builds a complete new tree under <filename>/usr/obj</filename>, - and <maketarget>installworld</maketarget>, another target, installs this tree on - the current machine.</para> + and <maketarget>installworld</maketarget>, another target, + installs this tree on the current machine.</para> - <para>Having separate options is very useful for two reasons. First, it allows you - to do the build safe in the knowledge that no components of - your running system will be affected. The build is + <para>Having separate options is very useful for two reasons. First, + it allows you to do the build safe in the knowledge that no + components of your running 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. It is still - recommended that you run the - <maketarget>installworld</maketarget> part in single user - mode, though.</para> + recommended that you run the <maketarget>installworld</maketarget> + part in single user mode, though.</para> - <para>Secondly, it allows you to use NFS mounts to upgrade + <para>Secondly, it allows you to use NFS mounts to upgrade multiple machines on your network. If you have three machines, - <hostid>A</hostid>, <hostid>B</hostid> and <hostid>C</hostid> that you want to upgrade, run <command>make - buildworld</command> and <command>make installworld</command> on - <hostid>A</hostid>. <hostid>B</hostid> and <hostid>C</hostid> should then NFS mount <filename>/usr/src</filename> - and <filename>/usr/obj</filename> from <hostid>A</hostid>, and you can then run - <command>make installworld</command> to install the results of + <hostid>A</hostid>, <hostid>B</hostid> and <hostid>C</hostid> that + you want to upgrade, run <command>make buildworld</command> and + <command>make installworld</command> on <hostid>A</hostid>. + <hostid>B</hostid> and <hostid>C</hostid> should then NFS mount + <filename>/usr/src</filename> and <filename>/usr/obj</filename> + from <hostid>A</hostid>, and you can then run + <command>make installworld</command> to install the results of the build on <hostid>B</hostid> and <hostid>C</hostid>.</para> <para>Although the <maketarget>world</maketarget> target still exists, @@ -981,16 +989,16 @@ Script done, …</screen> <para>Run</para> <screen>&prompt.root; <userinput>make buildworld</userinput></screen> - - <para>It is possible to specify a <option>-j</option> option to - <command>make</command> which will cause it to spawn several - simultaneous processes. This is most useful on multi-CPU machines. - However, since much of the compiling process is IO bound rather - than CPU bound it is also useful on single CPU machines.</para> + + <para>It is possible to specify a <option>-j</option> option to + <command>make</command> which will cause it to spawn several + simultaneous processes. This is most useful on multi-CPU machines. + However, since much of the compiling process is IO bound rather + than CPU bound it is also useful on single CPU machines.</para> <para>On a typical single-CPU machine you would run:</para> - - <screen>&prompt.root; <userinput>make -j4 buildworld</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 @@ -1000,7 +1008,7 @@ Script done, …</screen> configured kernel try values between 6 and 10 and see how they speed things up.</para> </sect3> - + <sect3> <title>Timings</title> <indexterm> @@ -1008,17 +1016,17 @@ Script done, …</screen> <secondary>timings</secondary> </indexterm> - <para>Many factors influence the build time, but fairly recent - machines may only take a one or two hours to build - the &os.stable; tree, with no tricks or shortcuts used during the - process. A &os.current; tree will take somewhat longer.</para> + <para>Many factors influence the build time, but fairly recent + machines may only take a one or two hours to build + the &os.stable; tree, with no tricks or shortcuts used during the + process. A &os.current; tree will take somewhat longer.</para> </sect3> </sect2> - + <sect2> <title>Compile and Install a New Kernel</title> <indexterm> - <primary>kernel</primary> + <primary>kernel</primary> <secondary>compiling</secondary> </indexterm> @@ -1039,14 +1047,16 @@ Script done, …</screen> file.</para> <para>On &os; it is important to <link - linkend="make-buildworld">build world</link> before building a - new kernel.</para> + linkend="make-buildworld">build world</link> before building a + new kernel.</para> - <note><para>If you want to build a custom kernel, and already have a configuration - file, just use <literal>KERNCONF=<replaceable>MYKERNEL</replaceable></literal> - like this:</para> + <note> + <para>If you want to build a custom kernel, and already have a + configuration file, just use + <literal>KERNCONF=<replaceable>MYKERNEL</replaceable></literal> + like this:</para> - <screen>&prompt.root; <userinput>cd /usr/src</userinput> + <screen>&prompt.root; <userinput>cd /usr/src</userinput> &prompt.root; <userinput>make buildkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput> &prompt.root; <userinput>make installkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen> </note> @@ -1085,13 +1095,13 @@ Script done, …</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. This does not necessarily hold true for other options; - for example, <option>-j</option> must never be used with + <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. This does not necessarily hold true for other + options; for example, <option>-j</option> must never be used with <maketarget>installworld</maketarget>.</para> - + <para>For example, if you ran:</para> <screen>&prompt.root; <userinput>make -DNO_PROFILE buildworld</userinput></screen> @@ -1108,250 +1118,258 @@ Script done, …</screen> <sect2> <title>Update Files Not Updated by <command>make installworld</command></title> - + <para>Remaking the world will not update certain directories (in particular, <filename>/etc</filename>, <filename>/var</filename> and - <filename>/usr</filename>) with new or changed configuration files.</para> + <filename>/usr</filename>) with new or changed configuration + files.</para> <para>The simplest way to update these files is to use - &man.mergemaster.8;, though it is possible to do it manually - if you would prefer to do that. Regardless of which way you + &man.mergemaster.8;, though it is possible to do it manually + if you would prefer to do that. Regardless of which way you choose, be sure to make a backup of <filename>/etc</filename> in case anything goes wrong.</para> - <sect3 id="mergemaster"> - <sect3info> - <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Contributed by </contrib> - </author> - </authorgroup> - </sect3info> - <title><command>mergemaster</command></title> - <indexterm><primary><command>mergemaster</command></primary></indexterm> - - <para>The &man.mergemaster.8; utility is a Bourne script that will - aid you in determining the differences between your configuration files - in <filename>/etc</filename>, and the configuration files in - the source tree <filename>/usr/src/etc</filename>. This is - the recommended solution for keeping the system configuration files up to date - with those located in the source tree.</para> - - <para>To begin simply type <command>mergemaster</command> at your prompt, and - watch it start going. <command>mergemaster</command> will then build a - temporary root environment, from <filename>/</filename> down, and populate - it with various system configuration files. Those files are then compared - to the ones currently installed in your system. At this point, files that - differ will be shown in &man.diff.1; format, with the <option>+</option> sign - representing added or modified lines, and <option>-</option> representing - lines that will be either removed completely, or replaced with a new line. - See the &man.diff.1; manual page for more information about the &man.diff.1; - syntax and how file differences are shown.</para> - - <para>&man.mergemaster.8; will then show you each file that displays variances, - and at this point you will have the option of either deleting the new file (referred - to as the temporary file), installing the temporary file in its unmodified state, - merging the temporary file with the currently installed file, or viewing the - &man.diff.1; results again.</para> - - <para>Choosing to delete the temporary file will tell &man.mergemaster.8; that we - wish to keep our current file unchanged, and to delete the new version. - This option is not recommended, unless you see no - reason to change the current file. You can get help at any time by - typing <keycap>?</keycap> at the &man.mergemaster.8; prompt. If the user - chooses to skip a file, it will be presented again after all other files - have been dealt with.</para> - - <para>Choosing to install the unmodified temporary file will replace the - current file with the new one. For most unmodified files, this is the best - option.</para> - - <para>Choosing to merge the file will present you with a text editor, - and the contents of both files. You can now merge them by - reviewing both files side by side on the screen, and choosing parts from - both to create a finished product. When the files are compared side by side, - the <keycap>l</keycap> key will select the left contents and the - <keycap>r</keycap> key will select contents from your right. - The final output will be a file consisting of both parts, which can then be - installed. This option is customarily used for files where settings have been - modified by the user.</para> - - <para>Choosing to view the &man.diff.1; results again will show you the file differences - just like &man.mergemaster.8; did before prompting you for an option.</para> - - <para>After &man.mergemaster.8; is done with the system files you will be - prompted for other options. &man.mergemaster.8; may ask if you want to rebuild - the password file and will finish up with an option to - remove left-over temporary files.</para> + <sect3 id="mergemaster"> + <sect3info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect3info> + <title><command>mergemaster</command></title> + <indexterm><primary><command>mergemaster</command></primary></indexterm> + + <para>The &man.mergemaster.8; utility is a Bourne script that will + aid you in determining the differences between your configuration + files in <filename>/etc</filename>, and the configuration files in + the source tree <filename>/usr/src/etc</filename>. This is + the recommended solution for keeping the system configuration files + up to date with those located in the source tree.</para> + + <para>To begin simply type <command>mergemaster</command> at your + prompt, and watch it start going. <command>mergemaster</command> + will then build a temporary root environment, from + <filename>/</filename> down, and populate it with various system + configuration files. Those files are then compared to the ones + currently installed in your system. At this point, files that + differ will be shown in &man.diff.1; format, with the + <option>+</option> sign representing added or modified lines, and + <option>-</option> representing lines that will be either removed + completely, or replaced with a new line. See the &man.diff.1; + manual page for more information about the &man.diff.1; syntax and + how file differences are shown.</para> + + <para>&man.mergemaster.8; will then show you each file that displays + variances, and at this point you will have the option of either + deleting the new file (referred to as the temporary file), + installing the temporary file in its unmodified state, merging the + temporary file with the currently installed file, or viewing the + &man.diff.1; results again.</para> + + <para>Choosing to delete the temporary file will tell + &man.mergemaster.8; that we wish to keep our current file + unchanged, and to delete the new version. This option is not + recommended, unless you see no reason to change the current file. + You can get help at any time by typing <keycap>?</keycap> at the + &man.mergemaster.8; prompt. If the user chooses to skip a file, + it will be presented again after all other files have been dealt + with.</para> + + <para>Choosing to install the unmodified temporary file will replace + the current file with the new one. For most unmodified files, + this is the best option.</para> + + <para>Choosing to merge the file will present you with a text editor, + and the contents of both files. You can now merge them by + reviewing both files side by side on the screen, and choosing parts + from both to create a finished product. When the files are + compared side by side, the <keycap>l</keycap> key will select the + left contents and the <keycap>r</keycap> key will select contents + from your right. The final output will be a file consisting of + both parts, which can then be installed. This option is + customarily used for files where settings have been modified by + the user.</para> + + <para>Choosing to view the &man.diff.1; results again will show you + the file differences just like &man.mergemaster.8; did before + prompting you for an option.</para> + + <para>After &man.mergemaster.8; is done with the system files you + will be prompted for other options. &man.mergemaster.8; may ask + if you want to rebuild the password file and will finish up with + an option to remove left-over temporary files.</para> </sect3> <sect3> <title>Manual Update</title> - <para>If you wish to do the update manually, however, - you cannot just copy over the files from - <filename>/usr/src/etc</filename> to <filename>/etc</filename> and - have it work. Some of these files must be <quote>installed</quote> - first. This is because the <filename>/usr/src/etc</filename> - directory <emphasis>is not</emphasis> a copy of what your - <filename>/etc</filename> directory should look like. In addition, - there are files that should be in <filename>/etc</filename> that are - not in <filename>/usr/src/etc</filename>.</para> - - <para>If you are using &man.mergemaster.8; (as recommended), - you can skip forward to the <link linkend="cutting-edge-rebooting">next - section</link>.</para> - - <para>The simplest way to do this by hand is to install the - files into a new directory, and then work through them looking - for differences.</para> - - <warning> - <title>Backup Your Existing <filename>/etc</filename></title> - - <para>Although, in theory, nothing is going to touch this directory - automatically, it is always better to be sure. So copy your - existing <filename>/etc</filename> directory somewhere safe. - Something like:</para> - - <screen>&prompt.root; <userinput>cp -Rp /etc /etc.old</userinput></screen> - - <para><option>-R</option> does a recursive copy, <option>-p</option> - preserves times, ownerships on files and suchlike.</para> - </warning> - - <para>You need to build a dummy set of directories to install the new - <filename>/etc</filename> and other files into. - <filename>/var/tmp/root</filename> is a reasonable choice, and - there are a number of subdirectories required under this as - well.</para> - - <screen>&prompt.root; <userinput>mkdir /var/tmp/root</userinput> + <para>If you wish to do the update manually, however, + you cannot just copy over the files from + <filename>/usr/src/etc</filename> to <filename>/etc</filename> and + have it work. Some of these files must be <quote>installed</quote> + first. This is because the <filename>/usr/src/etc</filename> + directory <emphasis>is not</emphasis> a copy of what your + <filename>/etc</filename> directory should look like. In addition, + there are files that should be in <filename>/etc</filename> that are + not in <filename>/usr/src/etc</filename>.</para> + + <para>If you are using &man.mergemaster.8; (as recommended), + you can skip forward to the <link + linkend="cutting-edge-rebooting">next section</link>.</para> + + <para>The simplest way to do this by hand is to install the + files into a new directory, and then work through them looking + for differences.</para> + + <warning> + <title>Backup Your Existing <filename>/etc</filename></title> + + <para>Although, in theory, nothing is going to touch this directory + automatically, it is always better to be sure. So copy your + existing <filename>/etc</filename> directory somewhere safe. + Something like:</para> + + <screen>&prompt.root; <userinput>cp -Rp /etc /etc.old</userinput></screen> + + <para><option>-R</option> does a recursive copy, <option>-p</option> + preserves times, ownerships on files and suchlike.</para> + </warning> + + <para>You need to build a dummy set of directories to install the new + <filename>/etc</filename> and other files into. + <filename>/var/tmp/root</filename> is a reasonable choice, and + there are a number of subdirectories required under this as + well.</para> + + <screen>&prompt.root; <userinput>mkdir /var/tmp/root</userinput> &prompt.root; <userinput>cd /usr/src/etc</userinput> &prompt.root; <userinput>make DESTDIR=/var/tmp/root distrib-dirs distribution</userinput></screen> - <para>This will build the necessary directory structure and install the - files. A lot of the subdirectories that have been created under - <filename>/var/tmp/root</filename> are empty and should be deleted. - The simplest way to do this is to:</para> - - <screen>&prompt.root; <userinput>cd /var/tmp/root</userinput> + <para>This will build the necessary directory structure and install + the files. A lot of the subdirectories that have been created under + <filename>/var/tmp/root</filename> are empty and should be deleted. + The simplest way to do this is to:</para> + + <screen>&prompt.root; <userinput>cd /var/tmp/root</userinput> &prompt.root; <userinput>find -d . -type d | xargs rmdir 2>/dev/null</userinput></screen> - - <para>This will remove all empty directories. (Standard error is - redirected to <filename>/dev/null</filename> to prevent the warnings - about the directories that are not empty.)</para> - - <para><filename>/var/tmp/root</filename> now contains all the files that - should be placed in appropriate locations below - <filename>/</filename>. You now have to go through each of these - files, determining how they differ with your existing files.</para> - - <para>Note that some of the files that will have been installed in - <filename>/var/tmp/root</filename> have a leading <quote>.</quote>. At the - time of writing the only files like this are shell startup files in - <filename>/var/tmp/root/</filename> and - <filename>/var/tmp/root/root/</filename>, although there may be others - (depending on when you are reading this). Make sure you use - <command>ls -a</command> to catch them.</para> - - <para>The simplest way to do this is to use &man.diff.1; to compare the - two files:</para> - - <screen>&prompt.root; <userinput>diff /etc/shells /var/tmp/root/etc/shells</userinput></screen> - - <para>This will show you the differences between your - <filename>/etc/shells</filename> file and the new - <filename>/var/tmp/root/etc/shells</filename> file. Use these to decide whether to - merge in changes that you have made or whether to copy over your old - file.</para> - - <tip> - <title>Name the New Root Directory - (<filename>/var/tmp/root</filename>) with a Time Stamp, so You Can - Easily Compare Differences Between Versions</title> - - <para>Frequently rebuilding the world means that you have to update - <filename>/etc</filename> frequently as well, which can be a bit of - a chore.</para> - - <para>You can speed this process up by keeping a copy of the last set - of changed files that you merged into <filename>/etc</filename>. - The following procedure gives one idea of how to do this.</para> - - <procedure> - <step> - <para>Make the world as normal. When you want to update - <filename>/etc</filename> and the other directories, give the - target directory a name based on the current date. If you were - doing this on the 14th of February 1998 you could do the - following:</para> - - <screen>&prompt.root; <userinput>mkdir /var/tmp/root-19980214</userinput> + + <para>This will remove all empty directories. (Standard error is + redirected to <filename>/dev/null</filename> to prevent the warnings + about the directories that are not empty.)</para> + + <para><filename>/var/tmp/root</filename> now contains all the files + that should be placed in appropriate locations below + <filename>/</filename>. You now have to go through each of these + files, determining how they differ with your existing files.</para> + + <para>Note that some of the files that will have been installed in + <filename>/var/tmp/root</filename> have a leading <quote>.</quote>. + At the time of writing the only files like this are shell startup + files in <filename>/var/tmp/root/</filename> and + <filename>/var/tmp/root/root/</filename>, although there may be + others (depending on when you are reading this). Make sure you use + <command>ls -a</command> to catch them.</para> + + <para>The simplest way to do this is to use &man.diff.1; to compare + the two files:</para> + + <screen>&prompt.root; <userinput>diff /etc/shells /var/tmp/root/etc/shells</userinput></screen> + + <para>This will show you the differences between your + <filename>/etc/shells</filename> file and the new + <filename>/var/tmp/root/etc/shells</filename> file. Use these to + decide whether to merge in changes that you have made or whether to + copy over your old file.</para> + + <tip> + <title>Name the New Root Directory + (<filename>/var/tmp/root</filename>) with a Time Stamp, so You Can + Easily Compare Differences Between Versions</title> + + <para>Frequently rebuilding the world means that you have to update + <filename>/etc</filename> frequently as well, which can be a bit + of a chore.</para> + + <para>You can speed this process up by keeping a copy of the last + set of changed files that you merged into + <filename>/etc</filename>. The following procedure gives one + idea of how to do this.</para> + + <procedure> + <step> + <para>Make the world as normal. When you want to update + <filename>/etc</filename> and the other directories, give the + target directory a name based on the current date. If you + were doing this on the 14th of February 1998 you could do the + following:</para> + + <screen>&prompt.root; <userinput>mkdir /var/tmp/root-19980214</userinput> &prompt.root; <userinput>cd /usr/src/etc</userinput> &prompt.root; <userinput>make DESTDIR=/var/tmp/root-19980214 \ distrib-dirs distribution</userinput></screen> - </step> - - <step> - <para>Merge in the changes from this directory as outlined - above.</para> - - <para><emphasis>Do not</emphasis> remove the - <filename>/var/tmp/root-19980214</filename> directory when you - have finished.</para> - </step> - - <step> - <para>When you have downloaded the latest version of the source - and remade it, follow step 1. This will give you a new - directory, which might be called - <filename>/var/tmp/root-19980221</filename> (if you wait a week - between doing updates).</para> - </step> - - <step> - <para>You can now see the differences that have been made in the - intervening week using &man.diff.1; to create a recursive diff - between the two directories:</para> - - <screen>&prompt.root; <userinput>cd /var/tmp</userinput> + </step> + + <step> + <para>Merge in the changes from this directory as outlined + above.</para> + + <para><emphasis>Do not</emphasis> remove the + <filename>/var/tmp/root-19980214</filename> directory when you + have finished.</para> + </step> + + <step> + <para>When you have downloaded the latest version of the source + and remade it, follow step 1. This will give you a new + directory, which might be called + <filename>/var/tmp/root-19980221</filename> (if you wait a + week between doing updates).</para> + </step> + + <step> + <para>You can now see the differences that have been made in the + intervening week using &man.diff.1; to create a recursive + diff between the two directories:</para> + + <screen>&prompt.root; <userinput>cd /var/tmp</userinput> &prompt.root; <userinput>diff -r root-19980214 root-19980221</userinput></screen> - - <para>Typically, this will be a much smaller set of differences - than those between - <filename>/var/tmp/root-19980221/etc</filename> and - <filename>/etc</filename>. Because the set of differences is - smaller, it is easier to migrate those changes across into your - <filename>/etc</filename> directory.</para> - </step> - - <step> - <para>You can now remove the older of the two - <filename>/var/tmp/root-*</filename> directories:</para> - - <screen>&prompt.root; <userinput>rm -rf /var/tmp/root-19980214</userinput></screen> - </step> - - <step> - <para>Repeat this process every time you need to merge in changes - to <filename>/etc</filename>.</para> - </step> - </procedure> - - <para>You can use &man.date.1; to automate the generation of the - directory names:</para> - - <screen>&prompt.root; <userinput>mkdir /var/tmp/root-`date "+%Y%m%d"`</userinput></screen> - </tip> + + <para>Typically, this will be a much smaller set of differences + than those between + <filename>/var/tmp/root-19980221/etc</filename> and + <filename>/etc</filename>. Because the set of differences is + smaller, it is easier to migrate those changes across into + your <filename>/etc</filename> directory.</para> + </step> + + <step> + <para>You can now remove the older of the two + <filename>/var/tmp/root-*</filename> directories:</para> + + <screen>&prompt.root; <userinput>rm -rf /var/tmp/root-19980214</userinput></screen> + </step> + + <step> + <para>Repeat this process every time you need to merge in + changes to <filename>/etc</filename>.</para> + </step> + </procedure> + + <para>You can use &man.date.1; to automate the generation of the + directory names:</para> + + <screen>&prompt.root; <userinput>mkdir /var/tmp/root-`date "+%Y%m%d"`</userinput></screen> + </tip> </sect3> </sect2> - + <sect2 id="cutting-edge-rebooting"> <title>Rebooting</title> - + <para>You are now done. After you have verified that everything appears to be in the right place you can reboot the system. A simple &man.shutdown.8; should do it:</para> @@ -1361,20 +1379,20 @@ Script done, …</screen> <sect2> <title>Finished</title> - + <para>You should now have successfully upgraded your &os; system. Congratulations.</para> - + <para>If things went slightly wrong, it is easy to rebuild a particular - piece of the system. For example, if you accidentally deleted - <filename>/etc/magic</filename> as part of the upgrade or merge of - <filename>/etc</filename>, the &man.file.1; command will stop working. - In this case, the fix would be to run:</para> + piece of the system. For example, if you accidentally deleted + <filename>/etc/magic</filename> as part of the upgrade or merge of + <filename>/etc</filename>, the &man.file.1; command will stop working. + In this case, the fix would be to run:</para> <screen>&prompt.root; <userinput>cd /usr/src/usr.bin/file</userinput> &prompt.root; <userinput>make all install</userinput></screen> - </sect2> - + </sect2> + <sect2> <title>Questions</title> @@ -1385,10 +1403,11 @@ Script done, …</screen> </question> <answer> - <para>There is no easy answer to this one, as it depends on the - nature of the change. For example, if you just ran <application>CVSup</application>, and - it has shown the following files as being updated:</para> - + <para>There is no easy answer to this one, as it depends on the + nature of the change. For example, if you just ran + <application>CVSup</application>, and it has shown the + following files as being updated:</para> + <screen><filename>src/games/cribbage/instr.c</filename> <filename>src/games/sail/pl_main.c</filename> <filename>src/release/sysinstall/config.c</filename> @@ -1403,13 +1422,13 @@ Script done, …</screen> re-make the world, or at least those parts of it that are statically linked (as well as anything else you might have added that is statically linked).</para> - + <para>At the end of the day, it is your call. You might be happy re-making the world every fortnight say, and let changes accumulate over that fortnight. Or you might want to re-make just those things that have changed, and be confident you can spot all the dependencies.</para> - + <para>And, of course, this all depends on how often you want to upgrade, and whether you are tracking &os.stable; or &os.current;.</para> @@ -1421,19 +1440,18 @@ Script done, …</screen> <para>My compile failed with lots of signal 11 (or other signal number) errors. What has happened?</para> </question> - <indexterm><primary>signal 11</primary></indexterm> + <indexterm><primary>signal 11</primary></indexterm> <answer> - <para>This is normally indicative of hardware problems. (Re)making the world is an effective way to stress test your hardware, and will frequently throw up memory problems. These normally manifest themselves as the compiler mysteriously dying on receipt of strange signals.</para> - + <para>A sure indicator of this is if you can restart the make and it dies at a different point in the process.</para> - + <para>In this instance there is little you can do except start swapping around the components in your machine to determine which one is failing.</para> @@ -1445,26 +1463,26 @@ Script done, …</screen> <para>Can I remove <filename>/usr/obj</filename> when I have finished?</para> </question> - + <answer> <para>The short answer is yes.</para> - + <para><filename>/usr/obj</filename> contains all the object files that were produced during the compilation phase. Normally, one - of the first steps in the <command>make buildworld</command> process is to - remove this directory and start afresh. In this case, keeping - <filename>/usr/obj</filename> around after you have finished - makes little sense, and will free up a large chunk of disk space - (currently about 340 MB).</para> - + of the first steps in the <command>make buildworld</command> + process is to remove this directory and start afresh. In this + case, keeping <filename>/usr/obj</filename> around after you + have finished makes little sense, and will free up a large + chunk of disk space (currently about 340 MB).</para> + <para>However, if you know what you are doing you can have - <command>make buildworld</command> skip this step. This will make subsequent - builds run much faster, since most of sources will not need to - be recompiled. The flip side of this is that subtle dependency - problems can creep in, causing your build to fail in odd ways. - This frequently generates noise on the &os; mailing lists, - when one person complains that their build has failed, not - realizing that it is because they have tried to cut + <command>make buildworld</command> skip this step. This will + make subsequent builds run much faster, since most of sources + will not need to be recompiled. The flip side of this is that + subtle dependency problems can creep in, causing your build to + fail in odd ways. This frequently generates noise on the &os; + mailing lists, when one person complains that their build has + failed, not realizing that it is because they have tried to cut corners.</para> </answer> </qandaentry> @@ -1479,13 +1497,13 @@ Script done, …</screen> you found a problem.</para> <para><emphasis>In general</emphasis> (and this is not a hard and - fast rule) the <command>make buildworld</command> process builds new - copies of essential tools (such as &man.gcc.1;, and + fast rule) the <command>make buildworld</command> process + builds new copies of essential tools (such as &man.gcc.1;, and &man.make.1;) and the system libraries. These tools and libraries are then installed. The new tools and libraries are - then used to rebuild themselves, and are installed again. The + then used to rebuild themselves, and are installed again. The entire system (now including regular user programs, such as - &man.ls.1; or &man.grep.1;) is then rebuilt with the new + &man.ls.1; or &man.grep.1;) is then rebuilt with the new system files.</para> <para>If you are at the last stage, and you know it (because you @@ -1501,13 +1519,13 @@ Script done, …</screen> <para>If you see the message:</para> - <screen>-------------------------------------------------------------- + <screen>-------------------------------------------------------------- Building everything.. --------------------------------------------------------------</screen> <para>in the <command>make buildworld</command> output then it is probably fairly safe to do so.</para> - + <para>If you do not see that message, or you are not sure, then it is always better to be safe than sorry, and restart the build from scratch.</para> @@ -1517,92 +1535,94 @@ Building everything.. <qandaentry> <question> <para>How can I speed up making the world?</para> - </question> + </question> - <answer> + <answer> <itemizedlist> <listitem> <para>Run in single user mode.</para> </listitem> - + <listitem> <para>Put the <filename>/usr/src</filename> and <filename>/usr/obj</filename> directories on separate file systems held on separate disks. If possible, put these disks on separate disk controllers.</para> </listitem> - + <listitem> <para>Better still, put these file systems across multiple disks using the &man.ccd.4; (concatenated disk driver) device.</para> </listitem> - + <listitem> - <para>Turn off profiling (set <quote>NO_PROFILE=true</quote> in - <filename>/etc/make.conf</filename>). You almost certainly - do not need it.</para> + <para>Turn off profiling (set <quote>NO_PROFILE=true</quote> + in <filename>/etc/make.conf</filename>). You almost + certainly do not need it.</para> </listitem> - + <listitem> <para>Also in <filename>/etc/make.conf</filename>, set <makevar>CFLAGS</makevar> to something like <option>-O - -pipe</option>. The optimization <option>-O2</option> is much - slower, and the optimization difference between + -pipe</option>. The optimization <option>-O2</option> + is much slower, and the optimization difference between <option>-O</option> and <option>-O2</option> is normally negligible. <option>-pipe</option> lets the compiler use pipes rather than temporary files for communication, which saves disk access (at the expense of memory).</para> </listitem> - + <listitem> - <para>Pass the <option>-j<replaceable>n</replaceable></option> option to &man.make.1; to - run multiple processes in parallel. This usually helps - regardless of whether you have a single or a multi processor - machine.</para> + <para>Pass the + <option>-j<replaceable>n</replaceable></option> option to + &man.make.1; to run multiple processes in parallel. This + usually helps regardless of whether you have a single or + a multi processor machine.</para> </listitem> - - <listitem><para>The file system holding - <filename>/usr/src</filename> can be mounted (or remounted) - with the <option>noatime</option> option. This prevents the - file system from recording the file access time. You probably - do not need this information anyway.</para> - - <screen>&prompt.root; <userinput>mount -u -o noatime /usr/src</userinput></screen> - - <warning> - <para>The example assumes <filename>/usr/src</filename> is - on its own file system. If it is not (if it is a part of - <filename>/usr</filename> for example) then you will - need to use that file system mount point, and not - <filename>/usr/src</filename>.</para> - </warning> + + <listitem> + <para>The file system holding <filename>/usr/src</filename> + can be mounted (or remounted) with the + <option>noatime</option> option. This prevents the + file system from recording the file access time. + You probably do not need this information anyway.</para> + + <screen>&prompt.root; <userinput>mount -u -o noatime /usr/src</userinput></screen> + + <warning> + <para>The example assumes <filename>/usr/src</filename> is + on its own file system. If it is not (if it is a part of + <filename>/usr</filename> for example) then you will + need to use that file system mount point, and not + <filename>/usr/src</filename>.</para> + </warning> </listitem> - + <listitem> - <para>The file system holding <filename>/usr/obj</filename> can - be mounted (or remounted) with the <option>async</option> - option. This causes disk writes to happen asynchronously. - In other words, the write completes immediately, and the - data is written to the disk a few seconds later. This - allows writes to be clustered together, and can be a - dramatic performance boost.</para> + <para>The file system holding <filename>/usr/obj</filename> + can be mounted (or remounted) with the + <option>async</option> option. This causes disk writes to + happen asynchronously. In other words, the write completes + immediately, and the data is written to the disk a few + seconds later. This allows writes to be clustered + together, and can be a dramatic performance boost.</para> <warning> <para>Keep in mind that this option makes your file system more fragile. With this option there is an increased chance that, should power fail, the file system will be in an unrecoverable state when the machine restarts.</para> - + <para>If <filename>/usr/obj</filename> is the only thing on this file system then it is not a problem. If you have other, valuable data on the same file system then ensure your backups are fresh before you enable this option.</para> </warning> - + <screen>&prompt.root; <userinput>mount -u -o async /usr/obj</userinput></screen> - + <warning> <para>As above, if <filename>/usr/obj</filename> is not on its own file system, replace it in the example with the @@ -1613,34 +1633,34 @@ Building everything.. </answer> </qandaentry> - <qandaentry> - <question> - <para>What do I do if something goes wrong?</para> - </question> + <qandaentry> + <question> + <para>What do I do if something goes wrong?</para> + </question> - <answer> - <para>Make absolutely sure your environment has no - extraneous cruft from earlier builds. This is simple - enough.</para> + <answer> + <para>Make absolutely sure your environment has no + extraneous cruft from earlier builds. This is simple + enough.</para> - <screen>&prompt.root; <userinput>chflags -R noschg /usr/obj/usr</userinput> + <screen>&prompt.root; <userinput>chflags -R noschg /usr/obj/usr</userinput> &prompt.root; <userinput>rm -rf /usr/obj/usr</userinput> &prompt.root; <userinput>cd /usr/src</userinput> &prompt.root; <userinput>make cleandir</userinput> &prompt.root; <userinput>make cleandir</userinput></screen> - <para>Yes, <command>make cleandir</command> really should - be run twice.</para> + <para>Yes, <command>make cleandir</command> really should + be run twice.</para> - <para>Then restart the whole process, starting - with <command>make buildworld</command>.</para> + <para>Then restart the whole process, starting + with <command>make buildworld</command>.</para> - <para>If you still have problems, send the error and the - output of <command>uname -a</command> to &a.questions;. - Be prepared to answer other questions about your - setup!</para> - </answer> - </qandaentry> + <para>If you still have problems, send the error and the + output of <command>uname -a</command> to &a.questions;. + Be prepared to answer other questions about your + setup!</para> + </answer> + </qandaentry> </qandaset> </sect2> </sect1> @@ -1655,12 +1675,13 @@ Building everything.. </author> </authorgroup> </sect1info> + <title>Tracking for Multiple Machines</title> <indexterm> <primary>NFS</primary> <secondary>installing multiple machines</secondary> </indexterm> - + <para>If you have multiple machines that you want to track the same source tree, then having all of them download sources and rebuild everything seems like a waste of resources: disk space, @@ -1678,7 +1699,7 @@ Building everything.. custom kernel, but they will be running the same userland binaries. From that set, choose a machine to be the <emphasis>build machine</emphasis>. It is going to be the - machine that the world and kernel are built on. Ideally, it + machine that the world and kernel are built on. Ideally, it should be a fast machine that has sufficient spare CPU to run <command>make buildworld</command> and <command>make buildkernel</command>. You will also want to @@ -1696,7 +1717,7 @@ Building everything.. as well. If you have multiple build sets, <filename>/usr/src</filename> should be on one build machine, and NFS mounted on the rest.</para> - + <para>Finally make sure that <filename>/etc/make.conf</filename> and <filename>/etc/src.conf</filename> on all the machines in @@ -1718,7 +1739,7 @@ Building everything.. <para>Now that all that is done, you are ready to build everything. Build the kernel and world as described in <xref - linkend="make-buildworld"> on the build machine, + linkend="make-buildworld"> on the build machine, but do not install anything. After the build has finished, go to the test machine, and install the kernel you just built. If this machine mounts <filename>/usr/src</filename> @@ -1751,11 +1772,11 @@ Building everything.. local build directory. Finally, if you are going to be building and distributing packages, you should set <makevar>PACKAGES</makevar> to a directory similar to - <makevar>DISTDIR</makevar>.</para> + <makevar>DISTDIR</makevar>.</para> </sect2> </sect1> </chapter> -<!-- +<!-- Local Variables: mode: sgml sgml-declaration: "../chapter.decl" @@ -1765,4 +1786,3 @@ Building everything.. sgml-parent-document: ("../book.sgml" "part" "chapter") End: --> - |