Hello,

[ To those who already read this mail in private: the patch has been
  changed a bit. ]

I've seen many people asking which is the right build method, order,
etc these days on the mailing lists. I think some information should
be provided about this in the BUILDING document (where it belongs).

Here is the patch I've done for BUILDING for review. It includes a
new section that aims to be a small howto for beginners. Yeah, I know
it can contain typos and maybe some kind of misinformation, but this
can be a good starting point ;). Comments?

Index: BUILDING.mdoc
===================================================================
RCS file: /cvsroot/src/doc/BUILDING.mdoc,v
retrieving revision 1.7
diff -u -u -r1.7 BUILDING.mdoc
--- BUILDING.mdoc	2002/12/25 00:58:01	1.7
+++ BUILDING.mdoc	2003/01/03 11:55:42
@@ -38,7 +38,7 @@
 .\" NOTE: After changing this file, run "make build-docs" to generate the
 .\" proper plaintext versions, and check in all BUILDING.* files!
 .\"
-.Dd December 25, 2002
+.Dd January 3, 2003
 .Dt BUILDING 8
 .Os NetBSD
 .
@@ -49,6 +49,18 @@
 .Nx
 from source code.
 .
+.Sh INTRODUCTION
+.
+This document describes the procedure for building
+.Nx
+from source code.
+It is intended as a reference for all the commands involved in the
+build, but also provides step by step information addressed to
+beginners.
+New users should read the
+.Sx BUILDING HOWTO
+section (located near the end of the document) to get started.
+.
 .Sh STATUS
 .
 This document is a work-in-progress.
@@ -1113,10 +1125,233 @@
 To disable, use
 .Sy TOOLCHAIN_MISSING=yes .
 .El
+.
+.Sh BUILDING HOWTO
+.
+This section outlines the build procedure in a step by step form,
+specially addressed to beginners.
+It does not cover cross compilation.
+.Pp
+We will be using the
+.Nm nbmake
+command instead of the regular
+.Xr make 1 ;
+the reason is that the former is part of the toolchain used to build
+.Nx
+and does not rely on the current system installation.
+.Pp
+An alternative is to use the
+.Nm nbmake-${MACHINE}
+wrapper which calls the real
+.Nm nbmake
+binary.
+This wrapper remembers many of the variables you used in the last
+.Nm build.sh
+invocation, making further
+.Nm nbmake
+calls easier.
+We will avoid using it in the following examples so that the new
+user does not miss anything obvious.
+.
+.Ss Building as root
+.
+Common steps:
+.Bl -enum
+.It
+Create basic directories using
+.Xr mkdir 1 .
+These include:
+.Bl -tag -width indent
+.It Va DESTDIR
+The directory that will contain the built
+.Nx
+system.
+It has no default, so you have to choose one.
+Use
+.Pa /usr/obj/root
+if you have no better idea (we will use this one in all of the
+examples).
+.It Va BSDOBJDIR
+The object tree, which defaults to
+.Pa /usr/obj .
+.It Va RELEASEDIR
+The directory that will contain the built
+.Nx
+release.
+It has no default, so you have to choose one.
+Use
+.Pa /usr/obj/release
+if you have no better idea (we will use this one in all of the
+examples).
+.It Va TOOLDIR
+The directory that contains the toolchain.
+Defaults to
+.Pa /usr/tools .
+.El
+.Pp
+Given the above suggestions, you can do:
+.Bd -literal -offset indent
+# mkdir -p /usr/obj
+# mkdir -p /usr/obj/root
+# mkdir -p /usr/obj/release
+# mkdir -p /usr/tools
+.Ed
+.Pp
+Please read the
+.Sx CONFIGURATION
+section for more information on these (and other) variables.
+.Pp
+It is a good idea to set these variables in the
+.Pa /etc/mk.conf
+file, so you do not have to pass them over and over again to the
+.Nm build.sh
+script (anyway, we will use these values in all of the calls to
+illustrate how it is done).
+.It
+Build the toolchain.
+Before you can build anything else from the source tree, you need
+a set of tools under
+.Va TOOLDIR .
+These can be built using:
+.Bd -literal -offset indent
+# ./build.sh -t -T /usr/tools -O /usr/obj
+.Ed
+.Pp
+The tools do not need to be recreated before each build (except as
+noted by the
+.Pa UPDATING
+file), so you can safely keep them between builds.
+.It
+Build, install and
+.Em boot
+a new kernel.
+See
+.Xr config 8
+for more information on how to do this.
+.It
+Cleanup work directories.
+It is recommended that you clean
+.Va DESTDIR
+and
+.Va OBJDIR
+before starting the build to avoid problems.
+.El
+.Pp
+When all the above steps are done, you are ready to build the system.
+Sources can produce different results:
+.Bl -enum
+.It
+A release.
+It provides all the compressed system sets, plus installation floppies
+and kernels.
+See
+.Xr release 7
+for more information.
+.Pp
+To build a release, use the following command:
+.Bd -literal -offset indent
+# ./build.sh -D /usr/obj/root -R /usr/obj/release
+  -T /usr/tools -O /usr/obj
+.Ed
+.Pp
+This is the most time consuming process.
+When it has finished, you have a full release under
+.Va RELEASEDIR .
+You can upgrade your system by using the boot floppies under that
+directory or unpack the system sets over the running system.
+.It
+Compressed system sets.
+This provides all the system sets, but nothing else.
+Useful if you want to update your system, but do not want all the
+extra stuff of a release (thus shortening the build time a lot).
+.Pp
+Start by building a distribution under
+.Va DESTDIR :
+.Bd -literal -offset indent
+# ./build.sh -d -D /usr/obj/root -T /usr/tools -O /usr/obj
+.Ed
+.Pp
+Generate the sets:
+.Bd -literal -offset indent
+# cd distrib/sets
+# mkdir -p /usr/obj/release/binary/sets
+# /usr/tools/bin/nbmake sets DESTDIR=/usr/obj/root
+  RELEASEDIR=/usr/obj/release
+.Ed
+.Pp
+And install them:
+.Bd -literal -offset indent
+# cd distrib/sets
+# /usr/tools/bin/nbmake installsets DESTDIR=/usr/obj/root
+  RELEASEDIR=/usr/obj/release INSTALLDIR=/
+.Ed
+.It
+A distribution.
+This will build the system, but will not generate any kind of release
+file (that is, nothing will be written to the
+.Va RELEASEDIR
+tree).
+Useful to easily update a single machine.
+.Pp
+This is done without the
+.Nm build.sh
+script, so you need to call the
+.Xr make 1
+program directly. To build the distribution (from source's top
+directory):
+.Bd -literal -offset indent
+# /usr/tools/bin/nbmake buildworld BSDOBJDIR=/usr/obj
+  TOOLDIR=/usr/tools DESTDIR=/usr/obj/root
+.Ed
+.Pp
+To install the results:
+.Bd -literal -offset indent
+# /usr/tools/bin/nbmake installworld BSDOBJDIR=/usr/obj
+  TOOLDIR=/usr/tools DESTDIR=/usr/obj/root INSTALLWORLDDIR=/
+.Ed
+.El
+.Pp
+Remember to run
+.Xr etcupdate 8
+after upgrading your system to bring
+.Pa /etc
+up to date.
+.
+.Ss Building as a regular user
+.
+The entire build process can be done as an unprivileged user.
+This is in fact recommended, so you avoid screwing up your running
+system.
+.Pp
+Make sure the directories
+.Pa DESTDIR ,
+.Pa OBJDIR ,
+.Pa RELEASEDIR
+and
+.Pa TOOLDIR
+have the right permissions for your user (read and write).
+It does not need write access to the source tree.
+.Pp
+Everything else is the same, with some small exceptions: when calling
+the
+.Nm build.sh
+script, you have to pass it the
+.Fl U
+option (that stands for unprived), and when directly calling
+.Nm nbmake
+you need to pass the extra argument
+.Ql UNPRIVED=yes .
+This will generate meta information required to set the right
+permissions on the generated files.
+.
 .Sh SEE ALSO
+.
 .Xr make 1 ,
+.Xr mk.conf 5 ,
 .Xr hier 7 ,
-.Xr release 7
+.Xr release 7 ,
+.Xr config 8 ,
+.Xr etcupdate 8
 .
 .Sh HISTORY
 .

Thanks!

-- 
Julio M. Merino Vidal <jmmv@menta.net>
The NetBSD Project - http://www.NetBSD.org/