From mwm@mired.org  Mon Mar 18 01:12:29 2002
Return-Path: <mwm@mired.org>
Received: from mired.org (dsl-64-192-6-133.telocity.com [64.192.6.133])
	by hub.freebsd.org (Postfix) with SMTP id 1090237B419
	for <FreeBSD-gnats-submit@freebsd.org>; Mon, 18 Mar 2002 01:12:27 -0800 (PST)
Received: (qmail 36861 invoked by uid 100); 18 Mar 2002 09:12:19 -0000
Message-Id: <20020318091219.36860.qmail@mired.org>
Date: 18 Mar 2002 09:12:19 -0000
From: Mike Meyer <mwm@mired.org>
Reply-To: Mike Meyer <mwm@mired.org>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: [PATCH] There's not a good description of shared builds in the handbook
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         36042
>Category:       docs
>Synopsis:       [PATCH] There's not a good description of shared builds in the handbook
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    ceri
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          update
>Submitter-Id:   current-users
>Arrival-Date:   Mon Mar 18 01:20:01 PST 2002
>Closed-Date:    Fri Mar 22 06:51:57 PST 2002
>Last-Modified:  Fri Mar 22 06:51:57 PST 2002
>Originator:     Mike Meyer
>Release:        FreeBSD 4.5-STABLE i386
>Organization:
Meyer Consulting
>Environment:
System: FreeBSD guru.mired.org 4.5-STABLE FreeBSD 4.5-STABLE #1: Sun Mar 17 05:18:14 CST 2002 mwm@guru.mired.org:/sharetmp/obj/usr/src/sys/GURU i386


>Description:
	The handbook describes updating the system on a single
	machine, but doesn't deal with the very common case of someone
	wanting multiple machines to track the same branch.

>How-To-Repeat:
	Read through the handbook.

>Fix:

	The attached English patch to the
	books/handbook/cutting-edge/chapter.sgml adds a section at the
	end that describes how to set things up so one machine keeps
	sources and does the builds, and others install those, including
	dealing with the ports tree.


--- chapter.sgml.orig	Mon Mar 18 02:27:48 2002
+++ chapter.sgml	Mon Mar 18 03:11:25 2002
@@ -32,6 +32,10 @@
 	<firstname>Nik</firstname>
 	<surname>Clayton</surname>
       </author>
+      <author>
+	<firstname>Mike</firstname>
+	<surname>Meyer</surname>
+      </author>
     </authorgroup>
     <!-- with feedback from various others -->
   </chapterinfo>
@@ -1625,6 +1629,98 @@
       </qandaset>
     </sect2>
   </sect1>
+
+  <sect1 id="small-lan">
+    <title>Tracking for multiple machines</title>
+    
+    <para>If you have a small lan&mdash;or a large one&mdash;and 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&mdash;disk space,
+	network bandwidth, and CPU cycles. It is, and the solution is
+	to have one machine do most of the work, and the rest of the
+	machines mount that work via NFS. This section outlines a
+	method of doing that that works.</para>
+
+      <sect2 id="small-lan-preliminaries">
+        <title>Preliminaries</title>
+
+	<para>First, identify a set of machines that is going to run
+	  the same set of binaries, which we will call a
+	  <emphasis>build set</emphasis>. Each machine can have a
+	  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's 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
+	  choose a machine to be the <emphasis>test
+	  machine</emphasis>, which will test software updates before they
+	  are put into production. This <emphasis>must</emphasis> be a
+	  machine that you can afford to have down for an extended
+	  period of time. It can be the build machihne, but need not be.</para>
+
+	<para>All the machines in this build set need to mount
+	  <filename>/usr/obj</filename> and
+	  <filename>/usr/src</filename> from the same machine, and at
+	  the same point. Ideally, those are on two different drives
+	  on the build machine, but they can be NFS mounted on that machine
+	  as well. If you have multiple build sets, /usr/src should be
+	  on one build machine, and NFS mounted on the rest.</para>
+	  
+	<para>Finally make sure that the
+	  <filename>/etc/make.conf</filename> on all the machines in
+	  the build set agree with the build machine. That means that
+	  the build machine must build all the parts of the base
+	  system that any machine in the build set is going to
+	  install. Also, each build machine should have it's kernel
+	  name as <varname>KERNCONF</varname> in
+	  <filename>/etc/make.conf</filename>, and the build machine
+	  should list them all in <option>KERNCONF</option>, listing
+	  it's own kernel first.</para>
+      </sect2>
+
+      <sect2>
+	<title>The base system</title>
+
+	<para>Now that all that is done, you're read to build
+	  everything. Build the kernel and world as described <xref
+	  linkend="make-buildworld">above</xref> on the build machine,
+	  but don't install anything. After the build has finished, go
+	  to the test machine, and install the kernel you just
+	  build. If this machine mounts <filename>/usr/src</filename>
+	  and <filename>/usr/obj</filename> via NFS, when you reboot
+	  to single user you will need to enable the network and mount
+	  them. The easiest way to do that is to boot to multi-user,
+	  then do <command>shutdown now</command> to go to single user
+	  mode. Once there, you can install the world and run
+	  <command>mergemaster</command> just as you normally do. Once
+	  done, use the <reboot>command</reboot> to reboot to normal
+	  multi-user operations for this machine.</para>
+
+	<para>After you are certain that everything on the test
+	  machine is working properly, use the same procedure to
+	  install the new software on each of the other machines in
+	  the build set.</para>
+      </sect2>
+
+      <sect2>
+	<title>Ports</title>
+
+	<para>The same ideas can be used for the ports tree. The first
+	  critical step is mounting /usr/ports from the same machine to
+	  all the machines in the build set. You can then set up
+	  <filename>/etc/make.conf</filename> properly to share
+	  distfiles. You should set <varname>DISTDIR</varname> to a
+	  common shared directory that is writable by whichever user
+	  root is going to be mapped to by your NFS mounts. Each
+	  machine should set <varname>WRKDIRPREFIX</varname> to a
+	  local build directory. Finally, if you're going to be
+	  building and distributing packages, you should set
+	  <varname>PACKAGES</varname> to a directory similar to
+	  <varname>DISTDIR</varname>.</para> 
+      </sect2>
+    </sect1>
 </chapter>
 
 <!-- 



>Release-Note:
>Audit-Trail:

From: Martin Heinen <martin@sumuk.de>
To: Mike Meyer <mwm@mired.org>
Cc: FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/36042: [PATCH] There's not a good description of shared builds in the handbook
Date: Tue, 19 Mar 2002 10:00:01 +0100

 On Mon, Mar 18, 2002 at 09:12:19AM -0000, Mike Meyer wrote:
 
 > 	The handbook describes updating the system on a single
 > 	machine, but doesn't deal with the very common case of someone
 > 	wanting multiple machines to track the same branch.
 
 That's really missing and we should put the section
 into the handbook.
 
 > --- chapter.sgml.orig	Mon Mar 18 02:27:48 2002
 > +++ chapter.sgml	Mon Mar 18 03:11:25 2002
 > @@ -1625,6 +1629,98 @@
 >        </qandaset>
 >      </sect2>
 >    </sect1>
 > +
 > +  <sect1 id="small-lan">
 > +    <title>Tracking for multiple machines</title>
 > +    
 > +    <para>If you have a small lan&mdash;or a large one&mdash;and 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&mdash;disk space,
 > +	network bandwidth, and CPU cycles. It is, and the solution is
 > +	to have one machine do most of the work, and the rest of the
 > +	machines mount that work via NFS. This section outlines a
 > +	method of doing that that works.</para>
                              ^^^^^^^^^^
 Omit 'that works', this avoids doubling 'that'.  Also all procedures
 given in the handbook should be working.
 
 > +
 > +      <sect2 id="small-lan-preliminaries">
 > +        <title>Preliminaries</title>
 > +
 > +	<para>First, identify a set of machines that is going to run
 > +	  the same set of binaries, which we will call a
 > +	  <emphasis>build set</emphasis>. Each machine can have a
 > +	  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's going to be the
                                               ^^^^
 It's -> It is
 
 > +	  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
 > +	  choose a machine to be the <emphasis>test
 > +	  machine</emphasis>, which will test software updates before they
 > +	  are put into production. This <emphasis>must</emphasis> be a
 > +	  machine that you can afford to have down for an extended
 > +	  period of time. It can be the build machihne, but need not be.</para>
                                               ^^^^^^^^
 machine
 
 > +
 > +	<para>All the machines in this build set need to mount
 > +	  <filename>/usr/obj</filename> and
 > +	  <filename>/usr/src</filename> from the same machine, and at
 > +	  the same point. Ideally, those are on two different drives
 > +	  on the build machine, but they can be NFS mounted on that machine
 
 Building on NFS volumes isn't a good thing.  Although possible,
 we shouldn't mention that here.
 
 > +	  as well. If you have multiple build sets, /usr/src should be
                                                     ^^^^^^^^
 <filename>/usr/src</filename>
 
 > +	  on one build machine, and NFS mounted on the rest.</para>
 > +	  
 > +	<para>Finally make sure that the
 > +	  <filename>/etc/make.conf</filename> on all the machines in
 > +	  the build set agree with the build machine. That means that
 > +	  the build machine must build all the parts of the base
 > +	  system that any machine in the build set is going to
 > +	  install. Also, each build machine should have it's kernel
 > +	  name as <varname>KERNCONF</varname> in
 > +	  <filename>/etc/make.conf</filename>, and the build machine
 > +	  should list them all in <option>KERNCONF</option>, listing
 > +	  it's own kernel first.</para>
 
 It seems obvious, but we should mention to copy the kernel
 configuration files to the build machine.
 
 > +      </sect2>
 > +
 > +      <sect2>
 > +	<title>The base system</title>
 > +
 > +	<para>Now that all that is done, you're read to build
                                          ^^^^^^^^^^^
 you are ready
 
 > +	  everything. Build the kernel and world as described <xref
 > +	  linkend="make-buildworld">above</xref> on the build machine,
                                     ^^^^^
 this is bad linking practice.  Instead name the target of the link:
 in section <xref linkend="make-buildworld">Compile and Install
   the Base System</xref>
 
 > +	  but don't install anything. After the build has finished, go
               ^^^^^
 do not
 
 > +	  to the test machine, and install the kernel you just
 > +	  build. If this machine mounts <filename>/usr/src</filename>
 > +	  and <filename>/usr/obj</filename> via NFS, when you reboot
 > +	  to single user you will need to enable the network and mount
 > +	  them. The easiest way to do that is to boot to multi-user,
 > +	  then do <command>shutdown now</command> to go to single user
 > +	  mode. Once there, you can install the world and run
 > +	  <command>mergemaster</command> just as you normally do. Once
 > +	  done, use the <reboot>command</reboot> to reboot to normal
 > +	  multi-user operations for this machine.</para>
 
 The procedure is different to normal build and should be outlined
 inside <screen>.
 
 > +
 > +	<para>After you are certain that everything on the test
 > +	  machine is working properly, use the same procedure to
 > +	  install the new software on each of the other machines in
 > +	  the build set.</para>
 > +      </sect2>
 > +
 > +      <sect2>
 > +	<title>Ports</title>
 > +
 > +	<para>The same ideas can be used for the ports tree. The first
 > +	  critical step is mounting /usr/ports from the same machine to
                                     ^^^^^^^^^^
 <filename>/usr/ports</filename>
 
 > +	  all the machines in the build set. You can then set up
 > +	  <filename>/etc/make.conf</filename> properly to share
 > +	  distfiles. You should set <varname>DISTDIR</varname> to a
 > +	  common shared directory that is writable by whichever user
 > +	  root is going to be mapped to by your NFS mounts. Each
 > +	  machine should set <varname>WRKDIRPREFIX</varname> to a
 > +	  local build directory. Finally, if you're going to be
 > +	  building and distributing packages, you should set
 > +	  <varname>PACKAGES</varname> to a directory similar to
 > +	  <varname>DISTDIR</varname>.</para> 
 > +      </sect2>
 > +    </sect1>
 >  </chapter>
 
 Please put two spaces at the end of sentences.
 
 -- 
 Marxpitn

From: Mike Meyer <mwm-dated-1017004489.c7e726@mired.org>
To: Martin Heinen <martin@sumuk.de>
Cc: FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/36042: [PATCH] There's not a good description of shared builds in the handbook
Date: Tue, 19 Mar 2002 15:14:49 -0600

 In <20020319100000.A57951@sumuk.de>, Martin Heinen <martin@sumuk.de> typed:
 > On Mon, Mar 18, 2002 at 09:12:19AM -0000, Mike Meyer wrote:
 > > 	The handbook describes updating the system on a single
 > > 	machine, but doesn't deal with the very common case of someone
 > > 	wanting multiple machines to track the same branch.
 > That's really missing and we should put the section
 > into the handbook.
 
 Thank you.
 
 > > +	machines mount that work via NFS. This section outlines a
 > > +	method of doing that that works.</para>
 > Omit 'that works', this avoids doubling 'that'.  Also all procedures
 > given in the handbook should be working.
 
 Good point - actually, most of them are good points, and I agree with
 any changes I don't mention here. That sentence should end with
 "method of doing so."
 
 > > +	<para>All the machines in this build set need to mount
 > > +	  <filename>/usr/obj</filename> and
 > > +	  <filename>/usr/src</filename> from the same machine, and at
 > > +	  the same point. Ideally, those are on two different drives
 > > +	  on the build machine, but they can be NFS mounted on that machine
 > Building on NFS volumes isn't a good thing.  Although possible,
 > we shouldn't mention that here.
 
 In which case, I think we should delete the entire sentence, and leave
 make world performance issues for another section.
 
 > > +	<para>Finally make sure that the
 > > +	  <filename>/etc/make.conf</filename> on all the machines in
 > > +	  the build set agree with the build machine. That means that
 > > +	  the build machine must build all the parts of the base
 > > +	  system that any machine in the build set is going to
 > > +	  install. Also, each build machine should have it's kernel
 > > +	  name as <varname>KERNCONF</varname> in
 > > +	  <filename>/etc/make.conf</filename>, and the build machine
 > > +	  should list them all in <option>KERNCONF</option>, listing
 > > +	  it's own kernel first.</para>
 
 How about adding the sentence:
 
     The build machine must have the config files for each machine in
     <filename>/usr/src/sys/<variable>arch</variable>/conf</filename>
     if it is going to build their kernelsp.
 
 as the new last sentence?
 
 > > +	  to the test machine, and install the kernel you just
 > > +	  build. If this machine mounts <filename>/usr/src</filename>
 > > +	  and <filename>/usr/obj</filename> via NFS, when you reboot
 > > +	  to single user you will need to enable the network and mount
 > > +	  them. The easiest way to do that is to boot to multi-user,
 > > +	  then do <command>shutdown now</command> to go to single user
 > > +	  mode. Once there, you can install the world and run
 > > +	  <command>mergemaster</command> just as you normally do. Once
 > > +	  done, use the <reboot>command</reboot> to reboot to normal
 > > +	  multi-user operations for this machine.</para>
 > The procedure is different to normal build and should be outlined
 > inside <screen>.
 
 I'm not convinced theren's enough difference to justify that. After
 all, if you aren't familiar with building and installing the world on
 one machine, you shouldn't be trying it on many machines.  If you want
 to write it up I'll be more than happy to have it included here as
 well, or even instead.
 
 > Please put two spaces at the end of sentences.
 
 I don't write for 19th century schoolmarms. If the target format
 requires that ugly anachronism, it should be taken care of by the
 style sheet or the formatter. If they can't do that, give me &period;
 and I'll use that. Or let us use -- instead of &mdash;.
 
 	Thank you for the feedback and corrections,
 	<mike
 --
 Mike Meyer <mwm@mired.org>			http://www.mired.org/home/mwm/
 Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.
State-Changed-From-To: open->analyzed 
State-Changed-By: ceri 
State-Changed-When: Wed Mar 20 10:04:43 PST 2002 
State-Changed-Why:  


I'm going to take this and clean it up to make people on 
-doc happy, then run it past Mike for his approval. 



Responsible-Changed-From-To: freebsd-doc->ceri 
Responsible-Changed-By: ceri 
Responsible-Changed-When: Wed Mar 20 10:04:43 PST 2002 
Responsible-Changed-Why:  


The patch has much merit, just needs a little tweaking, which 
I'll take care of. 


http://www.freebsd.org/cgi/query-pr.cgi?pr=36042 
State-Changed-From-To: analyzed->closed 
State-Changed-By: ceri 
State-Changed-When: Fri Mar 22 06:51:00 PST 2002 
State-Changed-Why:  

A slightly modified patch committed in rev 1.112 
Thanks for your submission! 


http://www.freebsd.org/cgi/query-pr.cgi?pr=36042 
>Unformatted:
