Updates/clarifications/adjustments to BUILDING

[David Holland <dholland-docs%netbsd.org@localhost>]

A few things in BUILDING have gone out of date, and also, some things
that should be are not documented (e.g. how build.sh -u interacts with
kernel=foo). I have done an editing pass and propose the following
patch.

The highlights:
   - mention src/tests and reference atf;
   - provide examples of MACHINE and MACHINE_ARCH -- someone please
     double-check these to make sure I haven't lied;
   - mention that MKOBJ=no is not recommented;
   - correct the default setting of USETOOLS;
   - document the interaction of build.sh -[uo] with various things;
   - document the interaction of build.sh tools and kernel=foo;
   - various typo fixes and wording adjustments, and use fewer
     parentheses.

Index: BUILDING.mdoc
===================================================================
RCS file: /cvsroot/src/doc/BUILDING.mdoc,v
retrieving revision 1.55
diff -U 10 -r1.55 BUILDING.mdoc
--- BUILDING.mdoc       8 Mar 2008 14:48:57 -0000       1.55
+++ BUILDING.mdoc       10 Mar 2008 05:59:47 -0000
@@ -120,23 +120,30 @@
 use the
 .Nx
 .Xr make 1
 .Dq reachover
 Makefile semantics when building these programs for a native host.
 .It Sy distrib/ , etc/
 Sources for items used when making a full release snapshot, such as
 files installed in
 .Sy DESTDIR Ns Pa /etc
 on the destination system, boot media, and release notes.
-.It Sy regress/
+.It Sy tests/ , regress/
 Regression test harness.
 Can be cross-compiled, but only run natively.
+.Pa tests/
+uses the
+.Xr atf 7
+test framework;
+.Pa regress/
+contains older tests that have not yet been migrated to
+.Xr atf 7 .
 .It Sy sys/
 .Nx
 kernel sources.
 .It Sy tools/
 .Dq Reachover
 build structure for the host build tools.
 This has a special method of determining out-of-date status.
 .It Sy bin/ ... usr.sbin/
 Sources to the
 .Nx
@@ -190,24 +197,26 @@
 .Li ${HOST_SH} build.sh Op Ar options
 .Ed
 .
 .It Sy HOST_CC
 Path name to C compiler used to create the toolchain.
 .
 .It Sy HOST_CXX
 Path name to C++ compiler used to create the toolchain.
 .
 .It Sy MACHINE
-Machine type.
+Machine type, e.g.,
+.Dq macppc .
 .
 .It Sy MACHINE_ARCH
-Machine architecture.
+Machine architecture, e.g.,
+.Dq powerpc .
 .
 .It Sy MAKE
 Path name to invoke
 .Xr make 1
 as.
 .
 .It Sy MAKEFLAGS
 Flags to invoke
 .Xr make 1
 with.
@@ -314,21 +323,21 @@
 unset otherwise.
 .Pp
 .Em Note :
 .Sy build.sh
 will provide a default of
 .Pa destdir. Ns Sy MACHINE
 (in the top-level
 .Sy .OBJDIR )
 unless run in
 .Sq expert
-mode
+mode.
 .
 .It Sy MAKECONF
 The name of the
 .Xr make 1
 configuration file.
 .Em Only settable in the process environment.
 .DFLT
 .Dq /etc/mk.conf
 .
 .It Sy MAKEVERBOSE
@@ -414,20 +423,27 @@
 .DFLTy
 .
 .It Sy MKOBJ
 .YorN
 Indicates whether object directories will be created when running
 .Dq make obj .
 If set to
 .Dq no ,
 then all built files will be located inside the regular source tree.
 .DFLTy
+.Pp
+Note that setting
+.Sy MKOBJ
+to
+.Dq no
+is not recommended and may cause problems when updating the tree with
+.Xr cvs 1 .
 .
 .It Sy MKPIC
 .YorN
 Indicates whether shared objects and libraries will be created and
 installed during a build.
 If set to
 .Dq no ,
 the entire built system will be statically linked.
 .DFLT
 Platform dependent.
@@ -551,30 +567,21 @@
 This is similar to the traditional
 .Nx
 build method, but does
 .Em not
 verify that the compilation tools in use are up-to-date enough in order
 to build the tree successfully.
 This may cause build or runtime problems when building the whole
 .Nx
 source tree.
 .El
-.DFLT
-.Dq yes
-if building all or part of a whole
-.Nx
-source tree (detected automatically);
-.Dq no
-otherwise (to preserve traditional semantics of the
-.Aq bsd.*.mk
-.Xr make 1
-include files).
+.DFLTy
 .
 .It Sy X11SRCDIR
 Directory containing the X11R6 source.
 If specified, must be an absolute path.
 The main X11R6 source is found in
 .Sy X11SRCDIR Ns Pa /xfree/xc .
 .DFLT
 .Dq /usr/xsrc
 .
 .El
@@ -596,49 +603,71 @@
 .DFLT
 .Dq /
 .
 .It Sy MKOBJDIRS
 .YorN
 Indicates whether object directories will be created automatically
 (via a
 .Dq make obj
 pass) at the start of a build.
 .DFLTn
+.Pp
+If using
+.Sy build.sh ,
+the default is
+.Dq yes .
+This may be set back to
+.Dq no
+by giving
+.Sy build.sh
+the
+.Fl o
+option.
 .
 .It Sy MKUPDATE
 .YorN
 If set, then in addition to the effects described for
 .Sy MKUPDATE=yes
 above, this implies the effects of
 .Sy NOCLEANDIR
 (i.e., 
 .Dq make cleandir
 is avoided).
 .DFLTn
+.Pp
+If using
+.Sy build.sh ,
+this may be set by giving the
+.Fl u
+option.
 .
 .It Sy NBUILDJOBS
 Now obsolete.
 Use the 
 .Xr make 1
 option
 .Fl j ,
-instead (see below)
+instead.
+See below.
 .DFLTu
 .
 .It Sy NOCLEANDIR
 If set, avoids the
 .Dq make cleandir
 phase of a full build.
 This has the effect of allowing only changed
 files in a source tree to be recompiled.
 This can speed up builds when updating only a few files in the tree.
 .DFLTu
+.Pp
+See also
+.Sy MKUPDATE .
 .
 .It Sy NODISTRIBDIRS
 If set, avoids the
 .Dq make distrib-dirs
 phase of a full build.
 This skips running
 .Xr mtree 8
 on
 .Sy DESTDIR ,
 useful on systems where building as an unprivileged user, or where it is
@@ -650,40 +679,40 @@
 .Dq make includes
 phase of a full build.
 This has the effect of preventing
 .Xr make 1
 from thinking that some programs are out-of-date simply because the
 system include files have changed.
 However, this option should not be used when updating the entire
 .Nx
 source tree arbitrarily; it is suggested to use
 .Sy MKUPDATE=yes
-in that case.
+instead in that case.
 .DFLTu
 .
 .It Sy RELEASEDIR
 If set, specifies the directory to which a
 .Xr release 7
 layout will be written at the end of a
 .Dq make release .
 If specified, must be an absolute path.
 .DFLTu
 .Pp
 .Em Note :
 .Sy build.sh
 will provide a default of
 .Pa releasedir
 (in the top-level
 .Sy .OBJDIR )
 unless run in
 .Sq expert
-mode
+mode.
 .
 .El
 .
 .Sh BUILDING
 .
 .Ss \*qmake\*q command line options
 This is not a summary of all the options available to
 .Xr make 1 ;
 only the options used most frequently with
 .Nx
@@ -704,21 +733,22 @@
 .It Fl m Ar dir
 Specify the default directory for searching for system Makefile
 segments, mainly the
 .Aq bsd.*.mk
 files.
 When building any full
 .Nx
 source tree, this should be set to the
 .Dq share/mk
 directory in the source tree.
-(This is set automatically when building from the top level.)
+This is set automatically when building from the top level, or when using
+.Sy build.sh .
 .
 .It Fl n
 Display the commands that would have been executed, but do not
 actually execute them.
 This will still cause recursion to take place.
 .
 .It Fl V Ar var
 Print
 .Xr make 1 Ns 's
 idea of the value of
@@ -854,90 +884,90 @@
 As per
 .Dq make distribution ,
 except that it ensures that
 .Sy DESTDIR
 is not the root directory.
 .
 .It Sy installworld
 Install the distribution from
 .Sy DESTDIR
 to
-.Sy INSTALLWORLDDIR
-(which defaults to the root directory).
+.Sy INSTALLWORLDDIR ,
+which defaults to the root directory.
 Ensures that
 .Sy INSTALLWORLDDIR
 is not the root directory if cross compiling.
 .Pp
 The
 .Sy INSTALLSETS
 environment variable may be set to a list of
 distribution sets to be installed.
 By default, all sets except
 .Dq etc
 and
 .Dq xetc
-are installed (so most files in
+are installed, so most files in
 .Sy INSTALLWORLDDIR Ns Pa /etc
-will not be installed or modified).
+will not be installed or modified.
 .Pp
 .Em Note :
 Before performing this operation with
 .Sy INSTALLWORLDDIR Ns = Ns Pa / ,
 it is highly recommended that you upgrade your kernel and reboot.
 After performing this operation,
 it is recommended that you use
 .Xr etcupdate 8
 to update files in
 .Sy INSTALLWORLDDIR Ns Pa /etc
 and that you use
 .Xr postinstall 8
 to check for inconsistencies (and possibly to fix them).
 .It Sy sets
 Create distribution sets from
 .Sy DESTDIR
 into
 .Sy RELEASEDIR/MACHINE Ns Pa /binary/sets .
 Should be run after
-.Dq make distribution
-(as
+.Dq make distribution ,
+as
 .Dq make build
-does not install all of the required files).
+alone does not install all of the required files.
 .
 .It Sy sourcesets
 Create source sets of the source tree into
 .Sy RELEASEDIR Ns Pa /source/sets .
 .
 .It Sy syspkgs
 Create syspkgs from
 .Sy DESTDIR
 into
 .Sy RELEASEDIR/MACHINE Ns Pa /binary/syspkgs .
 Should be run after
-.Dq make distribution
-(as
+.Dq make distribution ,
+as
 .Dq make build
-does not install all of the required files).
+alone does not install all of the required files.
 .
 .It Sy release
 Do a
 .Dq make distribution ,
 build kernels, distribution media, and install sets
 (this as per
 .Dq make sets ) ,
 and
 then package the system into a standard release layout as described by
 .Xr release 7 .
 This requires that
 .Sy RELEASEDIR
 be set (see above).
 .
-.It iso-image
+.It Sy iso-image
 Create a
 .Nx
 installation CD-ROM image in the
 .Sy RELEASEDIR Ns Pa /iso
 directory.
 The CD-ROM file system will have a layout as described in
 .Xr release 7 .
 .Pp
 For most machine types, the CD-ROM will be bootable, and will automatically
 run the
@@ -1013,21 +1043,24 @@
 This requires the
 .Xr mkisofs 1
 utility, which is not part of
 .Nx ,
 but which can be installed from
 .Pa pkgsrc/sysutils/cdrtools .
 .
 .It Sy regression-tests
 Can only be run after building the regression tests in the directory
 .Dq regress .
-Runs the compiled regression tests on the local host.
+Runs those compiled regression tests on the local host.
+Note that most tests are now managed instead using
+.Xr atf 7 ;
+this target will disappear when all tests have been migrated.
 .
 .El
 .
 .Ss The \*qbuild.sh\*q script
 .
 This script file is a Bourne shell script designed to build the
 entire
 .Nx
 system on any host with a Bourne shell in
 .Sy /bin/sh ,
@@ -1062,54 +1095,72 @@
 .
 .Pp
 The following operations are supported by
 .Sy build.sh :
 .
 .Bl -tag -width "distribution"
 .
 .It Sy build
 Build the system as per
 .Dq make build .
-This option implies the
+Before the main part of the build commences, this command runs the
 .Sy obj
-and
+operation (unless the
+.Fl o
+option is given),
+.Dq make cleandir
+(unless the
+.Fl u
+option is given),
+and the
 .Sy tools
-operations.
+operation.
 .
 .It Sy distribution
 Build a full distribution as per
 .Dq make distribution .
-This option implies the
+This command first runs the
 .Sy build
 operation.
 .
 .It Sy release
 Build a full release as per
 .Dq make release .
-This option implies the
+This command first runs the
 .Sy distribution
 operation.
 .
 .It Sy makewrapper
 Create the
 .Sy \*[toolprefix]make-MACHINE
 wrapper.
 This operation is automatically performed for any of the other
 operations.
 .
 .It Sy obj
 Perform
 .Dq make obj .
 .
 .It Sy tools
 Build and install the host tools from
 .Pa src/tools .
+This command will first run
+.Dq make obj
+and
+.Dq make cleandir
+in the 
+.Pa tools
+subdirectory unless the
+.Fl o
+or
+.Fl u
+options (respectively) are given.
 .
 .It Sy install Ns = Ns Ar idir
 Install the contents of
 .Sy DESTDIR
 to
 .Ar idir ,
 using
 .Dq make installworld .
 Note that files that are part of the
 .Dq etc
@@ -1130,29 +1181,41 @@
 .Sq /
 characters, the configuration file is expected to be found in the
 .Sy KERNCONFDIR
 directory, which is typically
 .Sy sys/arch/MACHINE/conf .
 The new kernel will be built in a subdirectory of
 .Sy KERNOBJDIR ,
 which is typically
 .Sy sys/arch/MACHINE/compile
 or an associated object directory.
-In order to ensure that the kernel is built using up-to-date tools,
-it is strongly recommended that the tools be rebuilt (using the
+.Pp
+This command does
+.Em not
+imply the
+.Sy tools
+command; run the
 .Sy tools
-operation).
+command first unless it is
+.Em certain
+that the tools already exist and are up to date.
+.Pp
+This command will run
+.Dq make cleandir
+on the kernel in question first unless the
+.Fl u
+option is given.
 .
 .It Sy releasekernel Ns = Ns Ar kconf
 Install a
 .Xr gzip 1 Ns ed
-copy of the kernel built by
+copy of the kernel previously built by
 .Sy kernel Ns = Ns Ar kconf
 into
 .Sy RELEASEDIR/MACHINE Ns Pa /binary/kernel ,
 usually as
 .Pa netbsd- Ns Ar kconf Ns Pa .gz ,
 although the
 .Dq Pa netbsd
 prefix is determined from the
 .Dq Sy config
 directives in
@@ -1238,21 +1301,25 @@
 does not have to be set when building as a non-root user.
 .Pp
 .Em Note :
 It is highly recommended that you know what you are doing when
 you use this option.
 .
 .It Fl h
 Print a help message.
 .
 .It Fl j Ar njob
-Passed through to 
+Run up to
+.Ar njob
+.Xr make 1 
+subjobs in parallel;
+passed through to 
 .Xr make 1 .
 Makefiles should use .WAIT or have explicit dependancies 
 as necessary to enforce build ordering.
 If you see build failures with -j, please save complete build logs 
 so the failures can be analyzed.
 .
 .It Fl M Ar obj
 Set
 .Sy MAKEOBJDIRPREFIX
 to
@@ -1335,22 +1402,23 @@
 and so forth.
 Unsets
 .Sy MAKEOBJDIRPREFIX .
 .
 .It Fl o
 Set the value of
 .Sy MKOBJDIRS
 to
 .Dq no .
 Otherwise, it will be automatically set to
-.Dq yes
-(which is opposite to the default behaviour).
+.Dq yes .
+This default is opposite to the behaviour when not using
+.Sy build.sh .
 .
 .It Fl R Ar rel
 Set the value of
 .Sy RELEASEDIR
 to
 .Ar rel .
 If a relative path is specified, it will be converted to an
 absolute path before being used.
 .
 .It Fl r
@@ -1365,23 +1433,23 @@
 .
 .It Fl T Ar tools
 Set the value of
 .Sy TOOLDIR
 to
 .Ar tools .
 If a relative path is specified, it will be converted to an
 absolute path before being used.
 If set, the bootstrap
 .Dq make
-will only be rebuilt as needed (when the source files for
+will only be rebuilt if the source files for
 .Xr make 1
-change).
+have changed.
 .
 .It Fl U
 Set
 .Sy MKUNPRIVED=yes .
 .
 .It Fl u
 Set
 .Sy MKUPDATE=yes .
 .
 .It Xo
@@ -1453,21 +1521,21 @@
 can be invoked in lieu of
 .Xr make 1 ,
 and will instead call the up-to-date version of
 .Dq \*[toolprefix]make
 installed into
 .Sy TOOLDIR/bin
 with several key variables pre-set, including
 .Sy MACHINE , MACHINE_ARCH ,
 and
 .Sy TOOLDIR .
-.Sy build.sh
+.Sy \*[toolprefix]make-MACHINE
 will also set variables specified with
 .Fl V ,
 and unset variables specified with
 .Fl Z .
 .Pp
 This script can be symlinked into a directory listed in
 .Sy PATH ,
 or called with an absolute path.
 .
 .Sh EXAMPLES
@@ -1524,21 +1592,21 @@
 .El
 .
 .Sh OBSOLETE VARIABLES
 .
 .Bl -tag -width "NBUILDJOBS"
 .
 .It Sy NBUILDJOBS
 Use the 
 .Xr make 1
 option
-.Fl j ,
+.Fl j
 instead.
 .
 .It Sy USE_NEW_TOOLCHAIN
 The new toolchain is now the default.
 To disable, use
 .Sy TOOLCHAIN_MISSING=yes .
 .El
 .Sh SEE ALSO
 .Xr make 1 ,
 .Xr hier 7 ,



-- 
David A. Holland
dholland%netbsd.org@localhost