Handbook update for 'make world'

Thu Jul 22 08:23:05 UTC 2004

On 2004.07.21 12:56:42 -0400, Ken Smith wrote:
> 
> Thoughts?  I *think* the flamewar over this change is finished but it might
> be premature.  But most of this probably should be done regardless IHMO.

First, I think it's good to go over this, since the ambiguity of "make
world" has been discussed before.

> Most of this de-emphasises "make world" in favor of the broken-down
> "make buildworld; make buildkernel; etc" procedure we've been recommending
> for a while now.  There is one significant-ish procedural change, I moved
> the "mergemaster -p" step to be first because there are cases that the
> "make buildworld" step now checks to see if users/groups exist before it
> will even begin compiling stuff...

Are you sure of that?  I'm rather sure that you only need mergemaster -p
before installworld, e.g. since you might be doing cross builds where
you don't want to touch the host environment... UPDATING also has
mergepaster -p before installworld, not before buildworld.

> Index: chapter.sgml
> ===================================================================
> RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml,v
> retrieving revision 1.203
> diff -u -r1.203 chapter.sgml
> --- chapter.sgml	6 Jul 2004 15:09:54 -0000	1.203
> +++ chapter.sgml	21 Jul 2004 16:49:13 -0000
> @@ -61,7 +61,7 @@
>  	  <application>CTM</application>.</para>
>        </listitem>
>        <listitem><para>How to rebuild and reinstall the entire base
> -      system with <command>make world</command>.</para>
> +      system with <command>make buildworld (etc)</command>.</para>

I think it should be "<command>make buildworld</command> (etc).", since
(etc) really isn't a command... The same appies to other entries in the
patch.

Perhaps it would be better just to write "rebuilding
<quote>world</quote>" or something like that, where that can be used
instead?

>        </listitem>
>  
>      </itemizedlist>
> @@ -536,10 +536,10 @@
>    </sect1>
>  
>    <sect1 id="makeworld">
> -    <title>Using <command>make world</command></title>
> +    <title>Using <command>make buildworld (etc)</command></title>
>  
>      <indexterm>
> -      <primary><command>make world</command></primary>
> +      <primary><command>make buildworld (etc)</command></primary>
>      </indexterm>
>      <para>Once you have synchronized your local source tree against a
>        particular version of &os; (&os.stable;, &os.current;, and so on)
> @@ -556,7 +556,8 @@
>  	when you make mistakes, or when mistakes made by others in the
>  	source tree render your system unbootable.</para>
>  
> -      <para>Make sure you have taken a backup.  And have a fixit floppy to
> +      <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>
>      </warning>
> @@ -593,7 +594,8 @@
>        <para>To update your system, you should use the following
>  	procedure:</para>
>  
> -      <screen>&prompt.root; <userinput>make buildworld</userinput>
> +      <screen>&prompt.root; <userinput>mergemaster -p</userinput>
> +&prompt.root; <userinput>make buildworld</userinput>
>  &prompt.root; <userinput>make buildkernel</userinput>
>  &prompt.root; <userinput>make installkernel</userinput>
>  &prompt.root; <userinput>reboot</userinput></screen>
> @@ -602,8 +604,7 @@
>  	<command>boot -s</command> from loader prompt for
>  	example).  Then run:</para>
>  
> -      <screen>&prompt.root; <userinput>mergemaster -p</userinput>
> -&prompt.root; <userinput>make installworld</userinput>
> +      <screen>&prompt.root; <userinput>make installworld</userinput>
>  &prompt.root; <userinput>mergemaster</userinput>
>  &prompt.root; <userinput>reboot</userinput></screen>
>  
> @@ -678,9 +679,11 @@
>  	<filename>/etc/group</filename>.</para>
>  
>        <para>There have been occasions when the installation part of
> -        <quote>make world</quote> has expected certain usernames or groups
> +        <quote>make installworld</quote> 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.</para>
> +	users or groups did not exist. This caused problems when upgrading.
> +	In some cases <quote>make buildworld</quote> will check to see if
> +	these users or groups exist.</para>
>  
>        <para>A recent example of this is when the
>  	<username>smmsp</username> user was added.  Users had the
> @@ -785,7 +788,7 @@
>  	<filename>/usr/obj</filename>.  The directories shadow those under
>  	<filename>/usr/src</filename>.</para>
>  
> -      <para>You can speed up the <quote>make world</quote> process, and
> +      <para>You can speed up the <quote>make buildworld</quote> process, and
>  	possibly save yourself some dependency headaches by removing this
>  	directory as well.</para>
>  
> @@ -895,7 +898,10 @@
>  	  &os.stable; midway between 2.2.2 and 2.2.5) the
>  	  <maketarget>world</maketarget> target has been split in
>  	  two: <maketarget>buildworld</maketarget> and
> -	  <maketarget>installworld</maketarget>.</para>
> +	  <maketarget>installworld</maketarget>. Beginning with version
                                                ^ Should be double space.

> +	  5.3 of &os the <maketarget>world</maketarget> will be changed
> +	  so it will not work at all by default because it is actually
> +	  dangerous for most users.</para>
>  
>  	<para>As the names imply, <maketarget>buildworld</maketarget>
>  	  builds a complete new tree under <filename>/usr/obj</filename>,
[...]
> @@ -1740,7 +1746,7 @@
>  	<emphasis>build machine</emphasis>.  It is going to be the
>  	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 world</command>.  You will also want to
> +	run <command>make buildworld (etc)</command>.  You will also want to

How about using "<command>make buildworld</command> and <command>make
buildkernel</command>" in this context - since that what matters for
speeding up build.

-- 
Simon L. Nielsen
FreeBSD Documentation Team
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20040722/a90dbc1d/attachment.sig>