toolchain/48741: Patch to improve BUILDING documentation

[dhgutteridge%sympatico.ca@localhost]

>Number:         48741
>Category:       toolchain
>Synopsis:       Patch to improve BUILDING documentation
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    toolchain-manager
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Sun Apr 13 02:10:00 +0000 2014
>Originator:     David H. Gutteridge
>Release:        HEAD
>Organization:
>Environment:
n/a
>Description:
After that debacle with opening PRs about things I should've found
were already documented, I had a look at the BUILDING document to see
what I could add. (Embarrassment is an excellent motivator for me...)
I thought there could be more information supplied to hopefully
save someone else from confusion. Also, the list of arguments to
build particular targets was very out of date, so I tried my hand at
updating it, based on what's in the current build.sh script. I'm not
sure I got it right in all cases, but I put in every combination I
saw. I hope this helps.
>How-To-Repeat:
(1) Become confused while trying to build a userland.

Or

(2) Notice there are many options for different ARM machines (ABI,
endianness, architecture) and wonder how to enable them.
>Fix:
--- BUILDING.mdoc.orig  2014-04-09 10:17:48.000000000 -0400
+++ BUILDING.mdoc       2014-04-12 21:35:42.000000000 -0400
@@ -1487,6 +1487,12 @@
 .Sy MACHINE_ARCH
 to
 .Ar arch .
+Note some
+.Sy MACHINE
+values require the
+.Sy MACHINE_ARCH
+value to also be explicitly set. At present, these are:
+evbmips, evbsh3, and sbmips.
 .
 .It Fl B Ar buildid
 Set the value of
@@ -1623,24 +1629,72 @@
 .Sy MACHINE_ARCH .
 The following special cases for the
 .Ar mach
-argument are defined to set the listed values of
+argument are defined by setting the listed values of
 .Sy MACHINE
 and
 .Sy MACHINE_ARCH :
-.Bl -column "evbmips-el" "MACHINE" "MACHINE_ARCH" -offset indent
+.Bl -column "evbearmv6hf-el" "netwinder" "(not set, no default)" -offset indent
 .It Sy mach Ta Sy "MACHINE" Ta Sy "MACHINE_ARCH"
+.It algor Ta algor Ta (not set)
+.It algor64 Ta algor Ta mips64el
+.It arc Ta arc Ta (not set)
+.It arc64 Ta arc Ta mips64el
+.It cats Ta cats Ta (not set)
+.It ecats Ta cats Ta earmv4
+.It cobalt Ta cobalt Ta (not set)
+.It cobalt64 Ta cobalt Ta mips64el
 .It evbarm Ta evbarm Ta (not set)
-.It evbarm-eb Ta evbarm Ta armeb
 .It evbarm-el Ta evbarm Ta arm
-.It evbmips Ta evbmips Ta (not set)
+.It evbarm-eb Ta evbarm Ta armeb
+.It evbearm-el Ta evbarm Ta earm
+.It evbearm-eb Ta evbarm Ta earmeb
+.It evbearmhf-el Ta evbarm Ta earmhf
+.It evbearmhf-eb Ta evbarm Ta earmhfeb
+.It evbearmv4-el Ta evbarm Ta earmv4
+.It evbearmv4-eb Ta evbarm Ta earmv4eb
+.It evbearmv5-el Ta evbarm Ta earmv5
+.It evbearmv5-eb Ta evbarm Ta earmv5eb
+.It evbearmv6-el Ta evbarm Ta earmv6
+.It evbearmv6hf-el Ta evbarm Ta earmv6hf
+.It evbearmv6-eb Ta evbarm Ta earmv6eb
+.It evbearmv6hf-eb Ta evbarm Ta earmv6hfeb
+.It evbearmv7-el Ta evbarm Ta earmv7
+.It evbearmv7-eb Ta evbarm Ta earmv7eb
+.It evbearmv7hf-el Ta evbarm Ta earmv7hf
+.It evbearmv7hf-eb Ta evbarm Ta earmv7hfeb
+.It evbmips Ta evbmips Ta (not set, no default)
+.It evbmips64-eb Ta evbmips Ta mips64eb
+.It evbmips64-el Ta evbmips Ta mips64el
 .It evbmips-eb Ta evbmips Ta mipseb
 .It evbmips-el Ta evbmips Ta mipsel
-.It evbsh3 Ta evbsh3 Ta (not set)
+.It evbppc Ta evbppc Ta (not set)
+.It evbppc64 Ta evbppc Ta powerpc64
+.It evbsh3 Ta evbsh3 Ta (not set, no default)
 .It evbsh3-eb Ta evbsh3 Ta sh3eb
 .It evbsh3-el Ta evbsh3 Ta sh3el
-.It sbmips Ta sbmips Ta (not set)
+.It hpcarm Ta hpcarm Ta (not set)
+.It hpcearm Ta hpcarm Ta earm
+.It iyonix Ta iyonix Ta (not set)
+.It eiyonix Ta iyonix Ta earm
+.It macppc Ta macppc Ta (not set)
+.It macppc64 Ta macppc Ta powerpc64
+.It netwinder Ta netwinder Ta (not set)
+.It enetwinder Ta netwinder Ta earmv4
+.It ofppc Ta ofppc Ta (not set)
+.It ofppc64 Ta ofppc Ta powerpc64
+.It pmax Ta pmax Ta (not set)
+.It pmax64 Ta pmax Ta mips64el
+.It sbmips Ta sbmips Ta (not set, no default)
+.It sbmips64-eb Ta sbmips Ta mips64eb
+.It sbmips64-el Ta sbmips Ta mips64el
 .It sbmips-eb Ta sbmips Ta mipseb
 .It sbmips-el Ta sbmips Ta mipsel
+.It sgimips Ta sgimips Ta (not set)
+.It sgimips64 Ta sgimips Ta mips64eb
+.It shark Ta shark Ta (not set)
+.It eshark Ta shark Ta earmv4
+.It zaurus Ta zaurus Ta (not set)
+.It ezaurus Ta zaurus Ta earm
 .El
 .
 .It Fl N Ar noiselevel
@@ -1703,6 +1757,25 @@
 it is determined by complex rules that are influenced
 by the values of several variables and
 by the location of the source directory.
+.Pp
+Note that placing the
+.Ar obj
+directory location outside of the default source tree hierarchy makes
+it easier to manually clear out old files in the event the
+.Dq cleandir
+operation is unable to do so. (See
+.Sy CAVEATS
+below.)
+.Pp
+Note also that use of one of
+.Fl M
+or
+.Fl O
+is the only means of building multiple machine architecture userlands
+from the same source tree without cleaning between builds (in which
+case, one would specify distinct
+.Ar obj
+locations for each).
 .It Fl o
 Set the value of
 .Sy MKOBJDIRS
@@ -1934,3 +2007,14 @@
 and re-worked to
 .Sy TOOLCHAIN_MISSING
 after that.
+.
+.Sh CAVEATS
+.
+After significant updates to third-party components in the source
+tree, the
+.Dq cleandir
+operation may be insufficient to clean out old files in object
+directories. Instead, one may have to manually remove the
+files. Consult the
+.Sy UPDATING
+file for notices concerning this.